Six claims in WORKFLOW.md's preamble that the document itself falsifies

[ptr727]

WORKFLOW.md's preamble, everything above ## 1. Purpose and How to Use This Document, makes six claims about the document that the document falsifies. Found by two whole-unit canonical passes on PR #1203's fix branch, which agreed on the substance, and deferred out of that branch because each fix is a content decision rather than the one-line framing correction it carried.

WORKFLOW.md is carried at intent, so every fleet repository reads this preamble first.

The contract is not purely outcome-shaped

Its defining principle: it describes required outcomes, not a required implementation. Two repos may implement the same guarantee with different YAML.

Section 4's ### D9 - Style / Static (See Section 2) folds section 2 into the contract, and section 4's own preamble says a workflow violating any applicable guarantee is not operational. D9.2 requires specific filenames and name: suffixes, D9.3 requires the folded scalar if: >-, and D9.4 requires type=registry. Those are required implementation.

Section 5A goes further and asserts exact literals, among them release-asset-<branch>-dotnet-publish, nuget-build-<branch>, buildcache-<branch>, !inputs.smoke, the -task.yml suffix, and Check pull request workflow status job. D6.4 requires that "The github-release job body stays verbatim", which is a byte-for-byte match against a reference implementation. So "with different YAML" holds only for the parts 5A does not pin by name, and a reader who re-implements a guarantee freely fails the audit section 5A runs.

Section 2 is binding, not merely legible

The conventions in section 2 keep workflows legible. The contract in section 4 is what they must do.

D9 makes a section 2 violation a not-operational defect, and 5A's D8/D9 line audits those conventions as contract items. "Keep workflows legible" tells a reader section 2 is advisory, and the document treats it as binding.

The trailing sentence carries the same defect:

Each is a MUST, stated as the output a conforming pipeline produces.

That is section 4's own preamble at WORKFLOW.md:148, written by #1198. D9.1 (SHA pins with version comments), D9.2 (name suffixes) and D9.5 (line endings) are static properties of committed source rather than any output a run produces, and D6.2 is the same shape. A fix has to settle whether D9 is exempted or the framing is restated.

The file preamble at WORKFLOW.md:15 used to carry a matching claim and no longer does. #1209 removed it rather than restating it, for this reason, so line 148 is the one place that remains. Related to #1200.

The release policy is mis-located, and the two files each route to the other

Canonical scope. This document is authoritative for the workflow contract and test methodology (sections 3 to 6). The conventions in section 2 and the release policy also live in GOVERNANCE.md ... Section 2 restates them so this file reads on its own.

"Them" is the conventions and the release policy, and section 2 restates only the conventions. The release policy is restated in section 3's ### Release Model subsection, which sits inside the "sections 3 to 6" range the same paragraph declares this document authoritative for and then hands to GOVERNANCE.md. One paragraph gives two answers for the same text.

Section 2 does not restate all of GOVERNANCE.md "Workflow YAML Conventions" either. Its "Validate input/state consistency at entry", "Artifact retention" and "Tag pinning on releases" bullets land in WORKFLOW.md sections 3 and 4 instead.

The precedence rule then holds on one half and fails on the other. For the conventions it is mutually confirmed, since GOVERNANCE.md "Workflow YAML Conventions" says the same. For the release policy GOVERNANCE.md "Release Model" says "See WORKFLOW.md for the full CI/CD contract" and that its own summary "sketches the contract", so a reader holding a real release-policy conflict is told by each file that the other one is authoritative.

The section labels and the range do not line up

Still in that blockquote: "the workflow contract and test methodology (sections 3 to 6)". The contract is section 4 and the test methodology section 5. Section 3 is Architecture and section 6 is the per-project-type walkthroughs, neither of which either label names, so the parenthetical silently widens two labels over two sections they do not describe.

The stated scope is narrower than the rules bind

This file is its sibling for everything under .github/workflows/.

The rules bind version.json (section 1's Default branch bullet, D3.2, D3.3), every committed .sh script (section 2 "Shells"), .editorconfig (D9.5), codecov.yml, global.json and .gitignore (D1.6), composite actions under .github/actions/** (D1.3 and 5A), and a branch ruleset's context: string (D9.2), which is not a file in the repository at all.

This bites in the numbered list directly above:

Audit - statically check the workflows against the conventions (section 2) and the structural facts each guarantee implies (section 5A).

5A's first sentence is "Read the workflow files plus version.json", and section 1 declares a publicReleaseRefSpec divergence there a defect. An agent auditing exactly what the preamble names never opens the file where that defect lives.

The code-style boundary is stated twice and drawn nowhere

a deliberate mixture of code style, architecture, a behavioral contract (expected inputs and outputs), and a test methodology. Code style lives in [CODESTYLE.md][codestyle].

Two adjacent sentences say this file contains code style and that code style lives elsewhere, with nothing stating the boundary. The boundary is not the two-way split implied either: CODESTYLE.md disclaims workflow YAML and routes it to GOVERNANCE.md, and the one rule that visibly straddles it, set -Eeuo pipefail on every committed .sh script, is stated in all three files.

Scope note

One finding, the "Test" bullet telling an agent to "drive a live probe (section 5C)" with no hint that 5C's deploy probe is explicitly maintainer-only and that others need secrets and same-repo access, is already covered by #1201 and is not restated here.

Related to #1200 (section 4's own claims), #1201 (section 5's procedure), #1204 and #1205.

[ptr727]

One more, found by a whole-unit pass over the skill that condenses this document, and sharper than most of the above because the contract falsifies its own portability rule.

Section 3's Release Model prose hardcodes main where D3.2 is deliberately portable.

WORKFLOW.md line 125 says "main a release, develop a prerelease". Section 1's own Default branch bullet says guarantees "say 'default branch' portably", names the three places the literal is implemented, and states that "These MUST all reference the repo's actual default branch. A divergence is a defect (section 5A)." D3.2 says the same, and D4.3 sets prerelease equal to branch != default.

So the document states a portability MUST in section 1 and then writes the literal in section 3, in a file carried by every fleet repository at appliesTo: "*". A repository whose default branch is not main reads line 125 as the rule. The condensed skill copy inherited the same literal, which is how this surfaced, and that half is tracked in #1208, but the fix belongs here at the source as much as there.

Worth noting that nothing downstream can re-derive the right answer either: registry/repos.json carries no defaultBranch field, so a repository whose default branch differs has no fleet data saying so.

Separately, and relevant to the framing item above: the fix branch for #1203 initially rewrote line 15 to say the guarantees are "stated as the output a conforming pipeline produces", matching section 4's preamble. Its own diff review then pointed out that this issue calls that exact claim false for D9, D6.2 and D5.5, so the branch would have propagated the overclaim to a fifth surface while its commit message declined to propagate it to the skill for that same reason. Line 15 now states no framing at all and routes the reader to section 4's preamble instead. The overclaim at line 148 is untouched and remains this issue's to settle.

[ptr727]

A further whole-unit pass adds four defects to those above, all in the same preamble.

Applicability is decided by hub files this document does not carry.

Given this document, an agent must be able to do three things to any project

The verdict depends on applicability, and applicability turns on data the document does not hold. D1.6 defers to "a lint-only profile for that type, per the hub's registry/repos.json" and to "the hub's spec/secrets.json typeMechanisms mapping", and 5A's D4 check turns on releaseTrigger: dispatch-only, another registry field. An agent holding only this document cannot decide what is applicable, so it cannot reach the third verb at all.

"Observed" is the wrong word on the normal path.

render a verdict: operational (every applicable guarantee holds and every applicable scenario's observed output equals the expected)

5B is titled "End-to-End Trace Scenarios (No Execution, Deterministic from the YAML)" and asks for a predicted table compared against the expected. Nothing is observed unless 5C runs, and 5C runs only "where warranted". Section 5's own Assessment paragraph repeats "observed output", so the fix belongs in both places.

Section 1 is left with no declared authority.

The Canonical scope blockquote assigns sections 3 to 6 to this document and section 2's conventions to GOVERNANCE.md, and says nothing about section 1. The rest of the file cites section 1 as binding: 5A's D1 check says "a package-push flag there is itself a finding, per section 1", and section 5's preamble says "Skip N/A items (section 1)". A reader asking who owns the applicability and N/A rules gets no answer from the scope statement.

The overlap partition is wrong in a third way.

Beyond the mis-located release policy already described above, GOVERNANCE.md "Workflow YAML Conventions" also holds rules this file states in sections 3 and 4, where the blockquote says this document wins: artifact retention (against section 3 "Resource Lifecycle" and D5.1 to D5.5), validate-input-at-entry (against section 3 "Validate-at-Entry" and D2.1), and tag pinning and target_commitish (against D4.2). None of those three appear as section 2 conventions, which is the concrete sense in which "Section 2 restates them so this file reads on its own" fails. Separately, section 2's "Line endings" bullet is in neither named GOVERNANCE.md section, it is in that file's own "Line Endings" section.

For the record on the fix branch: line 15 now reads "The guarantees are distilled from failures observed in practice. Section 4's preamble states how each item is written." An intermediate version kept the original's trailing "so the document stays portable to any project", which a pass flagged as a non sequitur once the framing clause it leaned on was removed, since provenance in observed failures does not cause portability. The outcome framing that does earn portability is in the second paragraph and is untouched.

[ptr727]

Correction to this issue's own text. The section "Section 2 is binding, not merely legible" blockquotes the trailing preamble sentence as

The guarantees are distilled from failures observed in practice and stated as the output a conforming pipeline produces

and concludes that a fix has to settle whether D9 is exempted "in both places". That sentence exists in no commit. It was an intermediate state on #1209's branch, written while fixing the Copilot finding and amended away once a review pass pointed out that this issue calls that exact claim false for D9. develop at 99f8de2 has "stated as the failure-mode each prevents", and #1209 ships no framing clause there at all:

The guarantees are distilled from failures observed in practice. Section 4's preamble states how each item is written.

So the scope is one place rather than two. WORKFLOW.md:148, section 4's own preamble, is what remains and is what this issue should be read as covering. Everything else in that section stands, since the D9 argument is about section 4's preamble and D9's items, not about the file preamble that now routes to it.