Cut WORKFLOW.md Section 2 to a Pointer at Workflow YAML Conventions

[ptr727]

Class 6 of #1317, WORKFLOW.md section 2 against GOVERNANCE.md "Workflow YAML Conventions", on the maintainer's call in this session: pointer, not include, since the include generator walks only .agents/skills/ and an include into WORKFLOW.md would need an engine change first.

What changed

• Section 2 becomes a pointer. It keeps its heading and number, so every "section 2" reference and its slug still resolve, and its eleven condensed bullets, the twelve inventory rows against the home, become one paragraph naming GOVERNANCE.md "Workflow YAML Conventions" and nothing of its content. The line-endings bullet had no home in that section, its home being the comment-and-doc-style Skill's policy that GOVERNANCE.md "Documentation Style Conventions" routes to under "Line Endings", so it becomes a pointer at that route rather than a rule moved into the YAML section. The row that contradicted D7.3, the both-forms boolean comparison, goes with the bullets, and the conflict it exposed is now the home's own, on Tracker: GOVERNANCE.md > Workflow YAML Conventions #1367 item 1 and Tracker: WORKFLOW.md > 4. Behavioral Contract: Expected Outcomes #1369 item 35.
• The sentences that cited section 2 for a rule name the home. The preamble's opening sentence, its audit verb, and its canonical-scope note, which used to say section 2 restates the conventions so the file reads on its own, the D9 preamble inside section 4, the D8/D9 walkthrough in 5A, and the operational bullet in section 6. The generated include in references/d-guarantees.md and the three distributions regenerate from the D9 sentence.
• The two homes stop claiming to be two. GOVERNANCE.md's section no longer says it and WORKFLOW.md keep the full rules with itself winning on overlap, and the skill's "Style Rules" points at the home and at the line-ending policy's skill instead of at section 2.
• The cut line-endings bullet's rule is retired, not moved. "Workflow YAML is LF (Actions and Dependabot rewrite it that way)" had its only home in section 2, since the line-endings policy's operational section requires a CRLF default in both files and never exempts workflow YAML. A grant moved it into that policy, and the whole-unit reads the move owed showed its reason false under the configuration the policy prescribes: with the paired * text=auto eol=crlf git stores LF and checks out CRLF, so a Dependabot commit of LF bytes leaves nothing mixed, and Actions never writes a workflow file. On the maintainer's call the rule is deleted rather than carried without its reason, and the policy file is back at its develop text. The fleet's one CRLF config repo carries such a pin by hand, with the same reason in its comment, and that is left to the maintainer.
• The ledger records a whole-unit pass over each of the eleven units this moves, per local-strict-review "The Carried-Content Pass".

What did not change

The "Release Model" overlap in the canonical-scope note stays, since it is a section 3 row set the inventory lists under that home, not this class. D9's five style guarantees in section 4 stay as written, since section 4 rows were not in this class and D9 states outcomes a workflow must meet rather than the conventions' text. README.md's "Conventions" list is class 13. Two phrases the condensed bullets carried and the home does not go with them: "Lowercase, hyphen-separated" on the Filename bullet, which the inventory row already listed as drift the condensation added to a suffix-only rule, and "Grant least privilege" on the permissions bullet, which D7.2 states as the one entry point that needs the scope. The third diff pass raised the first as a rule retired without a home, and it is declined on the inventory's evidence rather than promoted into the home, since adding a case rule to GOVERNANCE.md is class 14's decision list. #1369 items 35 and 50 name "section 2" for a rule that now lives at the home alone, noted on that tracker rather than edited.

Verification

• python3 scripts/build_dist.py --check, python3 scripts/prose_lint.py . --diff origin/develop, python3 scripts/repo_gate.py --check eol, python3 spec/validate.py, python3 scripts/tests/test_build_dist.py, and markdownlint, editorconfig-checker, and cspell through scripts/docker_lint.py: clean.
• Carried-content pass: eleven units read whole, one reviewer per unit per round, at the fable tier through round 10 and at the opus tier from round 11, when that tier stopped being reachable mid-drive, recorded in reports/canonical-review.json, two of them the line-endings policy sections no pass had read before, which the final diff no longer touches. Three diff passes per local-strict-review, one after each commit, the last recorded as the receipt.

Read record, introduced over total per read

Eight units in round 1, then only the units the previous round's fixes changed. Rounds 1 and 2 were the edit budget, round 3 is the read the round 2 fix owed, and rounds 4 to 6 are the maintainer's scoped grants under the stop rule, the first two answering the diff pass before them, the third and fourth answering what the grants' own reads found, the fourth a deletion, rounds 7 and 8 are the reads owed by the fix for Copilot's first round, the second push's two-round budget, and round 9 is the maintainer's fifth grant, un-enumerating the tie-break after the round 8 read found the three-section form naming no winner for a conflict with the Skill text a named section routes to, its Release Model half being #1206's own loop, and round 10 the sixth, dropping the line-endings clause the Copilot fix had added to the scope note after the round 9 read found "live in" false for a section that only routes to a Skill. The diff pass row sits in the column of the round it followed.

Read	R1	R2	R3	R4	R5	R6	R7	R8	R9	R10	R11	R12	R13
WORKFLOW.md (preamble)	1/5	2/4	0/4	0/2			1/2	1/1	1/1	0/1	0/1
WORKFLOW.md section 2	0/0	0/0									1/1	0/0
WORKFLOW.md section 4	0/2
WORKFLOW.md section 5	0/7	0/6			0/2
WORKFLOW.md section 6	0/3
GOVERNANCE.md Workflow YAML Conventions	0/1			0/2							0/3
Style Rules	1/1	0/0
The Behavioral Contract (include)	0/5
AGENTS.md Where the Rules Live				0/3									0/5
line-endings.md Operational (config) repos					2/2	1/1
line-endings.md Scripts and extensionless executables					1/5	0/1
Diff pass			2/2	2/2		1/1				1/1		0/0	0/0

The introduced findings, all on the pointer prose. Round 1: the Style Rules sentence said GOVERNANCE.md "Line Endings" keeps the line-ending policy where that subsection only routes to the comment-and-doc-style Skill, the same shape in section 2 and 5A, fixed as one class, and the preamble still called the document a mixture that includes code style. Round 2, both on the preamble sentences round 1 rewrote: "the GOVERNANCE.md section it points at" named one section where section 2 routes to two and 5C needs a third, and "pointed at rather than carried" was false because D9 carries five style guarantees. Round 3 raised four pre-existing findings and nothing introduced. The first diff pass then raised two introduced findings on surfaces no whole-unit read holds: the AGENTS.md "Where the Rules Live" row still said this section and WORKFLOW.md keep the full rules, and the two rewritten scope sentences had dropped the tie-break saying GOVERNANCE.md wins wherever the two overlap, narrowing the release one to section 3 while sections 3 and 4 still restate that section's bullets and D7.3 contradicts one, an added qualifier where the original had none. Both fixed in the first granted round, the tie-break restored unscoped. The second diff pass raised two more: the cut line-endings bullet, "Workflow YAML is LF", had its only home in section 2, since the line-endings policy's operational section requires a CRLF default in both files and never exempts workflow YAML while the fleet's one CRLF config repo pins its workflows to LF by hand, and the 5A sentence cited D9.5 for .gitattributes, which D9.5 does not name. The second grant moved the rule into that policy, its "Operational (config) repos" section stating the pin and its reason and "Scripts and extensionless executables" no longer saying the LF overrides are for POSIX-executed scripts only, and dropped the qualifier. The reads of the two policy sections that grant wrote raised three introduced findings on the granted sentences: the pin was written as a brace glob .gitattributes cannot expand, the operational sentence read as the only LF carve-out, and the scripts-section pointer claimed its sibling holds the POSIX-script exception. The third grant rewrote both sentences, and the re-read then showed the pin's reason itself false under the paired attribute, which the fourth grant answered by retiring the rule and returning the policy to its develop text, so the two policy sections are not in the final diff and the ledger's two entries for them record passes over text this branch held and no longer does. The granted round's three reads raised seven pre-existing findings and nothing introduced, the restored tie-break judged right on its own terms with the D7.3 conflict it overrules left at the home. One of round 3's four, that "keep workflows legible" mischaracterizes a section that is mostly safety rules, sits on a sentence this change re-routed, and it is classed pre-existing because the claim is #1206's own second item, filed before this change, the edit having touched only the route.

The pre-existing findings, 54 in all, are filed: #1336 items 2 to 9, #1367 items 9 to 14, #1369 items 52 to 57, #1370 items 20 to 34, #1371 items 2 to 4, #1389, the tracker this class opens for the line-endings reference, items 1 to 5, and the preamble's on #1206, the open decision issue that already holds most of them, which gains the six it did not. Section 5 widened from 7 to 6 new findings on unchanged text across two reads, and the preamble from 4 to 2 to 4, the pattern #1385 measured.

This pull request closes no issue. It removes two of #1206's preamble claims, the "restates them" sentence and the undrawn code-style boundary, and leaves that decision issue open.

Copilot ran four rounds, one per head, with full coverage on each. Its first round raised two threads: a missing relative pronoun in two sentences, fixed in 1a8b243, and the opening sentence not naming the style home's section, answered in 1a8b243 by keeping the opening at the document rather than one section, since the round 7 read showed one named section to be one home where section 2 routes to two, and the scope note's attempt to name both drew a finding on each of the next two reads, so it names "Workflow YAML Conventions" alone as it did when rounds 3, 4, and 6 read it clean. Round 10 then raised that one-section form as omitting the line-endings home, the mirror of round 7, and it is classed pre-existing because the same sentence shape and omission stood on develop and #1206 already holds section 2's line endings against the overlap partition. The two readings are each right about the sentence and cannot both be satisfied by naming sections, which is the non-convergence #1385 measured, and the home question is #1206's to settle. Its second round raised two threads and one suppressed finding, all wording on sentences this change wrote, fixed in 571e504: the GOVERNANCE.md intro sentence split in two, section 2's "every other file" reworded, and "workflow style rules" in the opening. Round 11 read the three units those fixes moved and found one more on this change's own text, section 2's closing clause reworded earlier from a parenthetical into a "since" clause, which fixed the property its "necessary but not sufficient" claim is measured against and made the claim false, so develop's parenthetical is restored verbatim and round 12 read it clean. Its third round raised no thread and two suppressed findings, both on unchanged text: the rules-map row reading as a fragment, fixed in 395024c with the reviewer's own connector, and the canonical-scope note's "(sections 3 to 6)" mislabel, answered in the pull request as byte-identical on develop and already #1206's item. Round 13 read the map whole and raised five more, none introduced. Its fourth round raised no thread and re-raised the "(sections 3 to 6)" mislabel alone, declined a second time on the maintainer's call, since the clause is develop's own and #1206 holds both halves of it, the widened labels and the excluded section 1, where this finding would fix only the first. The fourth diff pass raised the un-enumerated tie-break as contradicting "authoritative for sections 3 to 6" two sentences earlier, the pair that stood on develop and that #1206 files as one paragraph giving two answers, so it is pre-existing too, and the second diff pass had asked for exactly that unscoped form. The pre-existing findings count is 44, #1206 gaining a fourth.

🤖 Generated with Claude Code

[qodo-code-review]

ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: bc965f68-5734-4230-9695-53971e1db65f

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

🟡 Changes recommended

The updated WORKFLOW.md preamble includes ungrammatical/unclear phrasing that should be corrected before merge.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR converts WORKFLOW.md section 2 from a full restatement of workflow style rules into a pointer to the canonical home in GOVERNANCE.md, and updates related references across the workflow contract surfaces and skill distributions to match.

Changes:

• Replace WORKFLOW.md section 2’s bullet list with a pointer to GOVERNANCE.md "Workflow YAML Conventions" (and to the line-ending policy route).
• Update WORKFLOW.md D9 and other references to cite GOVERNANCE.md as the source of the style-rule exceptions and suffix rules.
• Regenerate/refresh the carried skill distributions and canonical-review ledger entries reflecting the updated units.

File summaries

File	Description
WORKFLOW.md	Converts section 2 into a pointer and updates D9 / walkthrough references accordingly.
GOVERNANCE.md	Updates the "Workflow YAML Conventions" preamble sentence to reflect WORKFLOW.md section 2 as a pointer.
AGENTS.md	Updates the "Editing a workflow YAML file" routing row to reflect the new ownership split (style rules vs contract).
reports/canonical-review.json	Updates the canonical review ledger entries/digests and stamps for the touched units.
.agents/skills/workflow-ci-contract/SKILL.md	Updates the skill’s "Style Rules" pointer text to reflect the new ownership and line-ending policy route.
.agents/skills/workflow-ci-contract/references/d-guarantees.md	Updates D9’s pointer sentence to cite GOVERNANCE.md instead of WORKFLOW.md section 2.
.github/skills/workflow-ci-contract/SKILL.md	Regenerated mirror of the skill text reflecting the updated pointer.
.github/skills/workflow-ci-contract/references/d-guarantees.md	Regenerated mirror of the D9 pointer sentence change.
.claude-plugin/fleet-skills/skills/workflow-ci-contract/SKILL.md	Regenerated plugin mirror of the skill text reflecting the updated pointer.
.claude-plugin/fleet-skills/skills/workflow-ci-contract/references/d-guarantees.md	Regenerated plugin mirror of the D9 pointer sentence change.
.claude-plugin/fleet-skills/.source-digests/workflow-ci-contract	Updates the source digest for the workflow-ci-contract skill bundle.

Review details

• Files reviewed: 11/11 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

A few newly introduced sentences are ambiguous/run-on in the contract docs and should be clarified to avoid misrouting readers.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

WORKFLOW.md:3

• The opening paragraph uses both "style rules" and "Code style" back-to-back, but the first phrase is about workflow YAML conventions (in GOVERNANCE.md) while the second points at CODESTYLE.md. Rewording to explicitly say "workflow YAML style conventions" avoids implying CODESTYLE.md and GOVERNANCE.md both own the same kind of style rules.

The guide for CI/CD **workflows** (GitHub Actions): a deliberate mixture of architecture, a **behavioral contract** (expected inputs and outputs), and a **test methodology**, the style rules having their home in `GOVERNANCE.md`. Code style lives in [`CODESTYLE.md`][codestyle]. This file is its sibling for everything under `.github/workflows/`.

• Files reviewed: 11/11 changed files
• Comments generated: 2
• Review effort level: Lite

[ptr727]

Answering the suppressed low-confidence finding from the round 2 review on head 1a8b243, which opens no thread. Count given by that block: (1).

WORKFLOW.md:3 The opening paragraph uses both "style rules" and "Code style" back-to-back, but the first phrase is about workflow YAML conventions (in GOVERNANCE.md) while the second points at CODESTYLE.md. Rewording to explicitly say "workflow YAML style conventions" avoids implying CODESTYLE.md and GOVERNANCE.md both own the same kind of style rules.

Fixed in 571e504. The opening now reads "the workflow style rules having their home in GOVERNANCE.md", which draws the boundary the finding asks for while keeping the sentence's length. "Workflow style rules" rather than the suggested "workflow YAML style conventions" because the same paragraph's next clause already names CODESTYLE.md as code style's home, so the qualifier only has to separate the two owners rather than restate the file glob the sentence ends with.

Round 1's suppressed block was empty and round 2's is the one above, so no earlier-round suppressed finding stands unanswered.

[Copilot]

🔵 Needs a closer look

Two updated doc sentences still contain a factual section-mapping mismatch and a table-row grammar break that should be corrected before merge.

Review details

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

AGENTS.md:100

• The table row reads as a sentence fragment ("..., the workflow-ci-contract Skill, that section keeping...") because it is missing a connector before "that section". Adding "with" makes the row parse cleanly and avoids ambiguity about what keeps which rules.
  WORKFLOW.md:13
• The canonical-scope note says the document is authoritative for the workflow contract and test methodology "(sections 3 to 6)", but section 3 is Architecture, section 4 is the Behavioral Contract, and the test methodology is sections 5-6. As written, this sentence mislabels the section mapping and makes it harder to follow the intended split of authority.

• Files reviewed: 11/11 changed files
• Comments generated: 0 new
• Review effort level: Lite

[ptr727]

Answering the two suppressed low-confidence findings from the round 3 review on head 571e504, which open no threads. Count given by that block: (2), both marked "Previously missed, in code that hasn't changed since the last review".

AGENTS.md:100 The table row reads as a sentence fragment ("..., the workflow-ci-contract Skill, that section keeping...") because it is missing a connector before "that section". Adding "with" makes the row parse cleanly and avoids ambiguity about what keeps which rules.

Fixed in 395024c, with the reviewer's own proposed connector. The row now reads "surfaced with the full WORKFLOW.md contract by the workflow-ci-contract Skill, with that section keeping the style rules and WORKFLOW.md the contract".

WORKFLOW.md:13 The canonical-scope note says the document is authoritative for the workflow contract and test methodology "(sections 3 to 6)", but section 3 is Architecture, section 4 is the Behavioral Contract, and the test methodology is sections 5-6. As written, this sentence mislabels the section mapping and makes it harder to follow the intended split of authority.

No change needed here, and the finding is correct rather than wrong. The parenthetical is byte-identical on develop:

git show origin/develop:WORKFLOW.md | sed -n '13p'
> **Canonical scope.** This document is authoritative for the workflow contract and test methodology (sections 3 to 6). ...

This pull request rewrote the two sentences after it and left that clause untouched, so the mislabel predates the change. It is already filed as its own item on #1206, the open decision issue for this preamble, under "The section labels and the range do not line up", which also records that section 1 falls outside the declared range while section 5's Assessment leans on it. Fixing it means deciding what the range should say about sections 1 and 3, which is that issue's call rather than this class's, per the tracker route in pr-review-conduct's Merge Gate item 3 for a pre-existing finding on a canonical unit.

Both round 2 suppressed findings were answered earlier in this conversation, so nothing from an earlier round stands unanswered.

[Copilot]

🔵 Needs a closer look

The canonical-scope sentence in WORKFLOW.md still describes “contract and test methodology” as spanning sections 3-6 even though section 3 is Architecture; the fix is a small wording correction on an edited line.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

WORKFLOW.md:13

• The canonical-scope sentence says the workflow contract and test methodology are in "sections 3 to 6", but section 3 is the Architecture section. Rewording the subject list to include architecture makes the section range accurate and avoids repeating the mismatch called out elsewhere in the doc.

• Files reviewed: 11/11 changed files
• Comments generated: 0 new
• Review effort level: Lite

[ptr727]

Answering the suppressed low-confidence finding from the round 4 review on head 395024c, which opens no thread. Count given by that block: (1).

WORKFLOW.md:13 The canonical-scope sentence says the workflow contract and test methodology are in "sections 3 to 6", but section 3 is the Architecture section. Rewording the subject list to include architecture makes the section range accurate and avoids repeating the mismatch called out elsewhere in the doc.

No change needed here. This is the same finding the round 3 block raised, reworded, and it is correct rather than wrong. It is declined again for the same reason, put to the maintainer this time because a second raise makes it a recurring finding rather than a one-off, and answered here so the head carries no unanswered suppressed finding.

The clause is byte-identical on develop and this pull request never touched it:

git show origin/develop:WORKFLOW.md | sed -n '13p'
> **Canonical scope.** This document is authoritative for the workflow contract and test methodology (sections 3 to 6). ...

It is filed on #1206, the open decision issue for this preamble, under "The section labels and the range do not line up", which holds both halves of the defect: the two labels widened over sections they do not describe, and section 1 left outside the declared range while section 5's Assessment leans on its N/A rule. Naming architecture in the subject list, as this finding proposes, fixes the first half and leaves the second, so the range still needs the decision that issue exists to make.

The reviewer's own note that the mismatch is "called out elsewhere in the doc" is the reason to settle it there rather than here: this class replaced WORKFLOW.md section 2's restatement of GOVERNANCE.md "Workflow YAML Conventions" with a pointer, and the preamble's own reads during this pull request produced eleven further findings on that unit, every one of them filed on #1206 rather than fixed, on the tracker route pr-review-conduct's Merge Gate item 3 sets for a pre-existing finding on a canonical unit.

[ptr727]

Correction to this pull request's read record

Three errors in my own reporting, found after the merge. None changes a finding, a fix, or the merge decision, and all three are about how the reads were briefed and counted.

1. Nine of thirteen preamble findings in rounds 1 to 3 re-derived claims already filed. Those three rounds were briefed "None filed for this unit, tracker None", and #1206 existed throughout holding about eleven claims about that exact preamble. I found #1206 only later, while searching for issues about section 2. The overlap, by round:

Round	Finding	Already held by
1	.github/workflows/ scope understated	#1206 "The stated scope is narrower than the rules bind"
1	verdict says "observed" where 5B predicts	#1206 comment, "'Observed' is the wrong word on the normal path"
1	callout names one overlap	#1206 comment, "The overlap partition is wrong in a third way"
1	opening's code-style boundary	#1206 "The code-style boundary is stated twice and drawn nowhere", partial, since this change made a flagged awkwardness into a falsehood
2	"(sections 3 to 6)" mislabel	#1206 "The section labels and the range do not line up"
2	"drive a live probe" against 5C	#1206's scope note, already covered by #1201
3	outcomes-not-implementation against D6.4	#1206 "The contract is not purely outcome-shaped"
3	"keep workflows legible"	#1206 "Section 2 is binding, not merely legible"
3	audit verb names only the workflows	#1206 "The stated scope is narrower than the rules bind"

The four that were not re-derivations: the "operational" verdict word and the tie-break's silence on a GOVERNANCE.md-versus-section-4 conflict, both new and filed on #1206, and the two introduced findings in round 2 that round 1's own fix wrote.

Nothing was double-filed. I mapped the overlap before filing and the #1206 comments name which findings restate its claims. What the record overstates is discovery: those rounds' pre-existing counts read as new findings and are partly rediscovery, so the preamble's row in the read record above should be read as nine known plus four new rather than thirteen new.

2. Tracker #1386 was fetched with --json body and briefed five of its six items. Item 6 lives in a comment I never fetched. The effect here is nil, since #1386 was cited only in the two Style Rules briefs and that unit is three lines of pointer text, while item 6 concerns a build-leaves sentence in a section this class never read. It is recorded because the next such miss need not be inert.

3. "The retirement left two ledger entries" is wrong; it left one. reports/canonical-review.json carries a single entry from the retired line-endings work, over "Scripts and extensionless executables", which canonical_review.py report now shows as stale because the file reverted to its develop text. The "Operational (config) repos" pass was read twice and never recorded, because the stop rule interrupted between the read and the record both times. That unit reads as never in the burn-down, which is accurate.

What this does not touch. Every unit read covered its whole current text, which is what the carried-content pass requires, and an absent suppression list cannot make a raised finding false. The introduced classifications stand, since each was about text this change wrote and no tracker could have pre-empted one. The gates and Copilot's four full-coverage rounds are independent of my briefs.