Settle the Preamble Decisions and Reshape Section 4, Section 6 and the YAML Conventions

[ptr727]

Collapses pull requests 2, 4 and 6 of the #1311 sequence into one change, which the maintainer
agreed to because the three touch the same surfaces and, run sequentially, each would re-sweep what
the last swept and pay the seam cost three times.

What it does

#1206's two maintainer decisions, applied first, since sections 4 and 6 and GOVERNANCE.md all
depend on them. D9 binds exactly as D1 through D8 do, so a style violation is a defect and
GOVERNANCE.md's target-state framing settles when an unswept workflow is fixed rather than
whether the violation counts. An overlap resolves by subject rather than by blanket
precedence, and every section 1 to 6 now has a named owner.

Section 4's two longest items shrink to their outcomes, D1.6 from about 974 words and D4.5 from
about 602. Nothing is deleted: the Microsoft.Testing.Platform runner, package floor and its
silently-green failure modes move to dotnet-codestyle, the pytest-cov dependency and coverage
selector to python-codestyle, and the failed-push recovery routes to
operational-vs-release-workflow.

Section 6 states only what each type adds, and carries no N/A list at all. All eight per-type
N/A lists are deleted rather than corrected, because such a list is right for a single-type
repository and negates a construct a second declared type supplies, which is the defect #1394
shipped through fifteen clean unit passes. Section 1's applicability rule derives the N/A set
instead, so no row can take away what another row gives. Rows are added for the seven registry
types that had none, upstream-wrapper is split out of docker, and the construct table keys on
the construct being present rather than on a registry field.

GOVERNANCE.md "Workflow YAML Conventions" is swept for the items on #1367.

What is deliberately not done

• D6.2's publisher exception stays withdrawn. A fourth wording was attempted here and
  disproved by get-version-task.yml, a called workflow whose branch classification comes from the
  caller's GITHUB_REF exactly as D3.1 requires. The item returns to the text develop carries and
  Tracker: WORKFLOW.md > 4. Behavioral Contract: Expected Outcomes #1369 records all four disproofs.
• No bullet-to-D-item mapping. One was added here, proved wrong four ways, drifted between its
  two copies in the round that wrote it, and was deleted on the maintainer's call.
• No per-guarantee evidence map, per the decision recorded on Why the Backlog Grows: Prose Review Has No Fixed Point, and a Plan to Keep the Rigor Without It #1311 step 16.
• The pypi environment's deployment-branch rule is not restored, per the caveat Tracker: WORKFLOW.md > 5. Test Methodology #1370 records:
  its one plausible content would block every .dev0 publish D3.4 requires.

Review evidence

21 read-only passes on the strongest tier before this pull request existed: 11 in round one (10
whole-unit carried-content plus a cross-unit diff pass briefed to hold registry/repos.json open),
9 in round two, and a terminal pair scoped to false claims and unfollowable instructions. Roughly
220 findings, the large majority introduced by this change and disposed of in it. The terminal pass
over GOVERNANCE.md, AUDIT.md, CODESTYLE.md and the four skills returned zero.

The measurement worth recording: the deletions were right first time and the reasons drew nearly
everything. Five claims about GitHub Actions behaviour that this change introduced were falsified
by the tree and reverted, among them that always() and !failure() && !cancelled() are
interchangeable-with-a-preference (D1.5 requires always() for the aggregator), and that the
registry's releaseTrigger decides publish-scenario applicability (it says two-phase for this
repository while publish-release.yml is workflow_dispatch: only).

A carried-content pass is recorded for all 23 canonical units this change moves.

Owed on merge

spec/files.json declares both edited GOVERNANCE.md sections at verbatim fidelity, so every
downstream copy goes stale and a fleet resync follows.

🤖 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: 5be307d7-09e4-43c3-a0aa-1e31fd23b192

---

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

It introduces markdown-formatting convention violations (hard-wrapped paragraphs) and one newly added sentence in WORKFLOW.md that is misleading as written.

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

Pull request overview

This PR consolidates and applies the agreed “preamble decisions” and restructures the CI/CD contract documentation by tightening WORKFLOW.md sections 4 and 6 and sweeping GOVERNANCE.md’s “Workflow YAML Conventions”, with supporting detail moved into the relevant skills and references (and the generated distributions regenerated).

Changes:

• Refines WORKFLOW.md’s framing, applicability rules, D-guarantee preamble, and reshapes section 6 around “constructs each type adds” instead of per-type N/A lists.
• Sweeps and clarifies GOVERNANCE.md “Workflow YAML Conventions” to align with the updated contract framing and exceptions.
• Updates skill/reference content (and regenerates .github/skills/ + .claude-plugin/ copies) to relocate detailed mechanics (e.g., MTP + coverage, publish recovery) out of WORKFLOW.md.

File summaries

File	Description
WORKFLOW.md	Reshapes preamble, contract framing, and section 6 type/construct mapping.
GOVERNANCE.md	Sweeps “Workflow YAML Conventions” to match subject-based overlap and clarified rules.
CODESTYLE.md	Updates section summaries to point detailed coverage/MTP guidance into codestyle skills.
AUDIT.md	Clarifies “outcome vs verbatim” and how named constructs affect audit verdicts.
reports/canonical-review.json	Records refreshed canonical-unit review coverage entries.
.agents/skills/workflow-ci-contract/SKILL.md	Updates skill text to reflect section 6’s new “constructs added” framing.
.agents/skills/workflow-ci-contract/references/architecture.md	Mirrors updated architecture wording from WORKFLOW.md section 3.
.agents/skills/workflow-ci-contract/references/d-guarantees.md	Mirrors updated D-guarantee preamble text from WORKFLOW.md section 4.
.agents/skills/workflow-ci-contract/references/test-methodology.md	Mirrors updated 5B preamble guidance from WORKFLOW.md section 5.
.agents/skills/python-codestyle/references/testing.md	Expands Python coverage obligations (pytest-cov + selector) per D1.6 move.
.agents/skills/dotnet-codestyle/SKILL.md	Notes MTP-based test project requirements at the skill summary level.
.agents/skills/dotnet-codestyle/references/testing.md	Adds detailed MTP + coverage requirements and diagnostics guidance.
.agents/skills/operational-vs-release-workflow/SKILL.md	Adds summary bullet for “failed registry push after release cut” recovery.
.agents/skills/operational-vs-release-workflow/references/release-publish-mechanics.md	Adds detailed recovery procedure for failed post-release registry push.
.github/skills/workflow-ci-contract/SKILL.md	Regenerated distribution copy of the workflow-ci-contract skill.
.github/skills/workflow-ci-contract/references/architecture.md	Regenerated distribution copy of workflow-ci-contract architecture reference.
.github/skills/workflow-ci-contract/references/d-guarantees.md	Regenerated distribution copy of workflow-ci-contract D-guarantees reference.
.github/skills/workflow-ci-contract/references/test-methodology.md	Regenerated distribution copy of workflow-ci-contract test methodology reference.
.github/skills/python-codestyle/references/testing.md	Regenerated distribution copy of python-codestyle testing reference.
.github/skills/dotnet-codestyle/SKILL.md	Regenerated distribution copy of dotnet-codestyle skill.
.github/skills/dotnet-codestyle/references/testing.md	Regenerated distribution copy of dotnet-codestyle testing reference.
.github/skills/operational-vs-release-workflow/SKILL.md	Regenerated distribution copy of operational-vs-release-workflow skill.
.github/skills/operational-vs-release-workflow/references/release-publish-mechanics.md	Regenerated distribution copy of publishing mechanics reference.
.claude-plugin/fleet-skills/skills/workflow-ci-contract/SKILL.md	Regenerated Claude plugin copy of workflow-ci-contract skill.
.claude-plugin/fleet-skills/skills/workflow-ci-contract/references/architecture.md	Regenerated Claude plugin copy of architecture reference.
.claude-plugin/fleet-skills/skills/workflow-ci-contract/references/d-guarantees.md	Regenerated Claude plugin copy of D-guarantees reference.
.claude-plugin/fleet-skills/skills/workflow-ci-contract/references/test-methodology.md	Regenerated Claude plugin copy of test methodology reference.
.claude-plugin/fleet-skills/skills/python-codestyle/references/testing.md	Regenerated Claude plugin copy of python testing reference.
.claude-plugin/fleet-skills/skills/dotnet-codestyle/SKILL.md	Regenerated Claude plugin copy of dotnet skill.
.claude-plugin/fleet-skills/skills/dotnet-codestyle/references/testing.md	Regenerated Claude plugin copy of dotnet testing reference.
.claude-plugin/fleet-skills/skills/operational-vs-release-workflow/SKILL.md	Regenerated Claude plugin copy of operational/release skill.
.claude-plugin/fleet-skills/skills/operational-vs-release-workflow/references/release-publish-mechanics.md	Regenerated Claude plugin copy of publishing mechanics reference.
.claude-plugin/fleet-skills/.source-digests/workflow-ci-contract	Updates Claude plugin source digest for workflow-ci-contract.
.claude-plugin/fleet-skills/.source-digests/python-codestyle	Updates Claude plugin source digest for python-codestyle.
.claude-plugin/fleet-skills/.source-digests/dotnet-codestyle	Updates Claude plugin source digest for dotnet-codestyle.
.claude-plugin/fleet-skills/.source-digests/operational-vs-release-workflow	Updates Claude plugin source digest for operational-vs-release-workflow.

Review details

Suppressed comments (1)

.agents/skills/dotnet-codestyle/references/testing.md:45

• These newly added paragraphs are hard-wrapped mid-sentence. Repo Markdown convention is one logical paragraph per line (no hard-wrap); see .github/skills/comment-and-doc-style/SKILL.md:90-92.

**The version floor is load-bearing rather than cautionary.** Below 18.1.0 the extension is built against Microsoft.Testing.Platform 1.x,
and an 18.0.x resolution, which is what a `>= 18.0.0` range picks, throws a `TypeLoadException`
against the 2.x platform `xunit.v3` 4.0.0 carries, runs zero tests, and **still writes a
well-formed Cobertura file reporting full coverage**, so only the non-zero exit says the run
reported nothing. 18.9.0 is the first release on Microsoft.Testing.Platform 2.3.x, where every

• Files reviewed: 36/36 changed files
• Comments generated: 3
• Review effort level: Lite

---

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

[ptr727]

Answering the suppressed finding, which has no thread to resolve.

.agents/skills/dotnet-codestyle/references/testing.md:45, hard-wrapped paragraphs. Correct, and fixed in f7858fd along with the two threaded instances. Every paragraph and list item this change added to that file, to python-codestyle/references/testing.md and to operational-vs-release-workflow/references/release-publish-mechanics.md is now one logical line, per comment-and-doc-style's "One logical paragraph per line, no hard-wrap line-length limit".

The sibling reference files across the skills tree wrap the same way and are deliberately untouched. Bringing new content up to a rule the rest of the tree has yet to meet is exactly what GOVERNANCE.md's target-state framing asks for, and reflowing text no review pass read would move canonical unit digests for no content change. The tree-wide sweep is its own change.

[Copilot]

🔵 Needs a closer look

One updated prose line in GOVERNANCE.md uses a mid-sentence semicolon that conflicts with the repo’s no-semicolons-in-prose convention (and is likely to fail prose_lint).

Review details

Suppressed comments (1)

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

GOVERNANCE.md:238

• Semicolon rule: replace the mid-sentence semicolon with a comma or sentence break to comply with the repo's no-semicolons-in-prose convention (prose_lint).

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

[ptr727]

Answering round 2's suppressed finding, which has no thread to resolve.

GOVERNANCE.md:238, semicolon in prose. Correct, and fixed in 339ee48 by splitting the sentence. Worth recording why the gate missed it, since the finding is more useful than it looks.

prose_lint's semicolon rule is "no semicolon in prose, outside a list that already carries commas", and it judges the exemption per sentence: a colon announcing a list exempts the semicolons after it in that sentence. The rewritten artifact-retention bullet carries a colon ("the condition is the download's:") introducing an explanation rather than a list, and my semicolon several clauses later joined two independent clauses. The exemption fired anyway, so the gate passed a violation of its own rule.

That is the same over-exemption sentences()'s own docstring records fixing at bullet scope, where "a colon anywhere before the first semicolon marked the bullet a list and exempted every semicolon after it, however plainly one joined two clauses". Narrowing it from the bullet to the sentence shrank the hole without closing it: the colon and the semicolon still do not have to be related. Filed as its own issue rather than fixed here, since changing a lint rule alongside a prose change would put the gate and the text it grades in one diff.

[Copilot]

🔵 Needs a closer look

It introduces at least two documentation assertions whose current wording is internally inconsistent or contradicted by existing repo state.

Review details

Suppressed comments (2)

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

GOVERNANCE.md:232

• This rule states that a POSIX #!/bin/sh git-hook surface "takes set -eu", but this repository’s own POSIX hook .husky/pre-commit currently uses set -e (see .husky/pre-commit:15). Either the hook needs to be updated in this PR, or this text should be loosened so the conventions section isn’t contradicted by the tree it governs.
  WORKFLOW.md:300
• This bullet says ownership vs calling "decides which constructs it contains", but the very next clause explains both an owner and a caller still contain the D6.1/D5 constructs (they just live in different places for citation). Rewording avoids an internal contradiction and prevents readers from concluding that calling the hub task makes these constructs N/A.

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

[ptr727]

Answering round 3's two suppressed findings, which have no threads to resolve. Both stand and both are fixed in 11804dd.

GOVERNANCE.md:232, the set -eu rule contradicted by .husky/pre-commit. Correct. The hook now carries set -eu. I had filed this rather than fixing it, on the reasoning that adding -u to a live hook can break it on an unset variable, and that was guessing where I could measure: the file references no variable at all and deliberately does not source the generated _/husky.sh, so -u adds no failure path. The commit that made the change ran the hook under it.

The adopter-facing catalog/snippets/husky/pre-commit is the other half and stays filed on #1367. It carries no set line at all and it does source _/husky.sh, which is generated, gitignored, and absent at lint time, so -u there would be asserted against a file this repository cannot inspect. Every command in that snippet already ends || exit 1, so the practical gap is narrow.

WORKFLOW.md:300, ownership deciding which constructs a repo contains. Correct, and the sharper half of the finding is the consequence it names: read literally, calling the hub-hosted release task would make D6.1 and D5.1 to D5.5 N/A for the caller. The row now says the release task carries those constructs, that a repo contains them whether it owns that task or calls the copy, and that ownership changes only where 5A cites the evidence. That is what the reading rule above it already said, and the row was the surface the earlier fix did not reach.

[Copilot]

🔵 Needs a closer look

It reshapes multiple fleet-defining contract documents and regenerated skill distributions, so it warrants final human verification of correctness and downstream impact.

Review details

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