Carry WORKFLOW.md Sections 3 and 5 Into workflow-ci-contract as Generated Includes - #1392
Merged
Merged
Conversation
…ated Includes AGENTS.md requires a Skill needing a rule's full text to carry it as a generated include from the rule's home rather than as a copy, and only references/d-guarantees.md complied. SKILL.md's "The Core Behavioral Spine" restated WORKFLOW.md section 3 and parts of section 4 by hand, and references/test-methodology.md restated section 5 by hand, describing itself as an index rather than the sweep. Both had already drifted, in both directions at once, and build_dist.py --check held neither to its source. references/architecture.md is new and carries section 3 whole through an include region, references/test-methodology.md now carries section 5 the same way, and the spine is replaced by a routing section naming where each of the three carried sections lives and where sections 1, 2, and 6 stay. SKILL.md drops from 8.2 KB to 5.5 KB, and the two drifted claims it carried, "repo-owned" for "repo-owned in shape" and a hand-written second statement of D6.4, are gone rather than realigned. Carrying a section moves it outside its own document, so section 3 loses the two reference-style links whose definitions live at the file's foot, and both sections name a sibling by document and heading rather than as "below" or "this document". Each section gains the closing sentence naming the skill that includes it, the shape section 4 already carries. docs/fleet-map.md and skill-lifecycle's doc-packaging examples are swept to match. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The local review found that SKILL.md's "Two layers" bullet still restated the section 3 subsection this change had just started carrying whole, which is the drift vector that already fired once on this same bullet. It keeps the one sentence that is section 1's auditing instruction and points at the carried text for the rest. docs/fleet-map.md still described the skill as carrying the per-type walkthroughs as references, which it does not and never did, and d-guarantees.md's preamble named no sibling while its two new siblings each name it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…puts The cut bullet pointed at WORKFLOW.md section 3 for the layer split and then issued section 1's audit instruction, but section 3 defines the two layers without saying which one declares which input. The mapping is section 1's, so the bullet now names both. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing |
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Team Run ID: 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. Comment |
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
The changes consistently convert sections 3 and 5 into generated include surfaces across the source and regenerated distributions without introducing functional contract inconsistencies in the reviewed text.
Pull request overview
This pull request updates the workflow-ci-contract skill to stop restating WORKFLOW.md sections 3 and 5 by hand, and instead carries those sections into the skill as generated include regions (matching the existing include for section 4). This reduces drift risk between the canonical contract (WORKFLOW.md) and the skill surfaces that agents read at workflow-edit time.
Changes:
- Add a new
references/architecture.mdinclude surface forWORKFLOW.mdsection 3, and convertreferences/test-methodology.mdto includeWORKFLOW.mdsection 5. - Replace the skill’s “Core Behavioral Spine” with routing text that points readers to the three carried include surfaces (architecture / D-guarantees / test methodology).
- Regenerate skill distribution outputs and refresh canonical-review report entries to reflect the new units/digests.
File summaries
| File | Description |
|---|---|
| WORKFLOW.md | Adjust section-3/5 wording to be include-safe and add pointers noting the sections are carried into the skill. |
| reports/canonical-review.json | Update recorded digests/findings and add new units for the new include surfaces. |
| docs/fleet-map.md | Update skill packaging map text to reflect sections 3/4/5 now carried as includes. |
| .github/skills/workflow-ci-contract/SKILL.md | Regenerated distribution copy reflecting the new routing section and include coverage. |
| .github/skills/workflow-ci-contract/references/test-methodology.md | Regenerated distribution copy carrying WORKFLOW.md section 5 via include markers. |
| .github/skills/workflow-ci-contract/references/d-guarantees.md | Regenerated distribution copy with updated preamble cross-referencing the new architecture/methodology surfaces. |
| .github/skills/workflow-ci-contract/references/architecture.md | Regenerated distribution copy introducing the new “architecture” include surface for section 3. |
| .github/skills/skill-lifecycle/SKILL.md | Regenerated distribution copy updating the doc-packaging examples for workflow-ci-contract’s new include set. |
| .claude-plugin/fleet-skills/skills/workflow-ci-contract/SKILL.md | Regenerated plugin copy matching the updated workflow-ci-contract skill text. |
| .claude-plugin/fleet-skills/skills/workflow-ci-contract/references/test-methodology.md | Regenerated plugin copy carrying WORKFLOW.md section 5 via include markers. |
| .claude-plugin/fleet-skills/skills/workflow-ci-contract/references/d-guarantees.md | Regenerated plugin copy with updated preamble cross-references. |
| .claude-plugin/fleet-skills/skills/workflow-ci-contract/references/architecture.md | Regenerated plugin copy introducing the new “architecture” include surface. |
| .claude-plugin/fleet-skills/skills/skill-lifecycle/SKILL.md | Regenerated plugin copy updating the doc-packaging examples accordingly. |
| .claude-plugin/fleet-skills/.source-digests/workflow-ci-contract | Update plugin source digest after the workflow-ci-contract source changes. |
| .claude-plugin/fleet-skills/.source-digests/skill-lifecycle | Update plugin source digest after the skill-lifecycle source changes. |
| .agents/skills/workflow-ci-contract/SKILL.md | Source-of-truth skill update: remove restated spine and route to the three include-carried sections. |
| .agents/skills/workflow-ci-contract/references/test-methodology.md | Source-of-truth include surface for WORKFLOW.md section 5 (generated include region). |
| .agents/skills/workflow-ci-contract/references/d-guarantees.md | Source-of-truth include surface preamble updated to reference architecture/methodology siblings. |
| .agents/skills/workflow-ci-contract/references/architecture.md | New source-of-truth include surface for WORKFLOW.md section 3 (generated include region). |
| .agents/skills/skill-lifecycle/SKILL.md | Source-of-truth packaging examples updated to reflect workflow-ci-contract now includes sections 3/4/5. |
Review details
- Files reviewed: 20/20 changed files
- Comments generated: 0
- Review effort level: Lite
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
This was referenced Sep 6, 2026
ptr727
added a commit
that referenced
this pull request
Sep 6, 2026
Pull request 3 of the #1311 reshape sequence, and the third to ship after PR 1 (#1373) and PR 5 (#1392). ## What it does `WORKFLOW.md` 5A carried nine "Core" bullets restating section 4's D-guarantees and five per-type addenda, roughly 2400 words of a second hand-authored wording of the contract. It is now three paragraphs: how a verdict is recorded, where evidence lives when it is not in the workflow files, and how to cite it. Section 5 drops from about 3000 words to 1000. A section that says where to look cannot disagree with the section that says what must hold, so **32 of #1370's 44 findings are unwritable rather than fixed**: each quotes 5A text that no longer exists. The two finding classes step 14 measured, "5A contradicts or misstates the guarantee it audits" (15 items) and "unsupported check" (8 items), have no surface left to sit on. ## Also fixed, from #1393 - **Item 15** (also #1370 items 2 and 44). S1 and S4 read "validate-release **skipped (smoke), succeeds**", one job with two conclusions. D2.2 makes the check exit early while the job succeeds, and warns against reading that as a job-level skip, which the old wording invited. - **Item 10.** S11 stated merge-bot auto-merge as the required output, contradicting D8.3's `auto-merge: false` tracker, which prefixes the head so no merge-bot rule matches. - **Item 11** (also #1370 item 31). 5C's maintainer-only fence reached only a probe that dispatches or re-runs, so its first bullet told an agent to open a pull request on the repository it audits. - **Items 12 and 13.** The Assessment restated 5A's recording rule more narrowly than 5A states it, and spelled the N/A token two ways. Swept to match: section 1's applicability rule and its two-layer bullet, section 6's three references to the deleted addenda, `AUDIT.md` sections 3 and 5 plus its flowchart node, and the `audit-a-repo` and `workflow-ci-contract` skills. ## Review Sixteen whole-unit carried-content passes over ten units and five diff passes, all on the strongest tier, before this pull request existed. They raised roughly 70 findings. Every one was on this change's own text or on a surface this change put in disagreement; none was against the collapse itself. All ten changed canonical units carry a recorded pass at their current text, and the local review receipt covers the final content. The maintainer settled one design question mid-flight: an interim revision carried a per-guarantee evidence map, and it was deleted because a per-guarantee map is itself a hand-authored second surface and regenerated the same defect class it replaced, at smaller scale. That decision is what the current three-paragraph shape implements. ## Known and filed, not fixed here - **D6.2 now stands unqualified.** The deleted 5A text was the sole home of its publisher exception, and the hub's own publisher stub in `docs/reusable-workflows.md` reads `github.ref_name` in four places. Moving the carve-out into D6.2 was attempted twice and withdrawn twice, each time on verified evidence that the wording was wrong. Section 4 is pull request 2's, and the evidence is filed for it. - **5B carries no counterpart to the pinned-SHA read.** `AUDIT.md` and `audit-a-repo` now tell an auditor to read a called workflow at the SHA the caller pins, and 5A's citation rule admits that evidence, but 5B, where the job graph is actually walked, does not say it. - **Two requirements had no home outside 5A.** The `pypi` environment's deployment-branch rule, which #1370 item 43 shows would block every `.dev0` develop publish D3.4 requires, is genuinely lost. The static-site generator's checksum pin survives as `spec/project-types.json`'s `hugo.generator.pinned`. Full disposition, including the section 6 and `AUDIT.md` items this review surfaced, is on #1370. Refs #1311, #1370, #1393 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
ptr727
added a commit
that referenced
this pull request
Sep 7, 2026
…sh the WORKFLOW.md Reshape (#1397) Closes #1205. Closes #1212. Closes #1240. Closes #1250. Closes #1267. Closes #1268. Closes #1271. Closes #1288. Closes #1305. Closes #1314. Sixteen commits, ten issues. Each was driven as its own feature pull request into `develop`, reviewed by the PR-hosted reviewers, and merged only with CI green and every finding disposed of by one of the five outcomes: fixed, declined on evidence, decided by the maintainer, deferred behind a filed issue, or fixed as a class. ## What this promotes **The one-home include mechanism and its first six classes** (#1317). `scripts/build_dist.py` gained include regions filled from a rule's home and checked by `--check` (#1378), so a Skill carries a rule's whole text without a copy that can drift. Classes 2 to 6 then converted the restatements: `agent-conduct`'s three conduct sections (#1382), `pr-review-conduct`'s five outcomes into `drive-pr` with every step-ref renamed to a heading (#1383), `backlog-burndown`'s two narrowing rows cut to the narrowing with fourteen restatements pointered (#1384), `WORKFLOW.md` section 4 into `workflow-ci-contract` (#1385), and section 2 cut to a pointer at `GOVERNANCE.md` "Workflow YAML Conventions" (#1388). **The `WORKFLOW.md` reshape** (#1311 step 14's six-pull-request sequence, now finished). The verdict clause aligned with section 5's Assessment (#1390), sections 3 and 5 carried into `workflow-ci-contract` as generated includes (#1392), 5A collapsed to a procedure and an evidence rule (#1394), and the preamble decisions settled alongside the reshape of section 4, section 6 and the YAML conventions (#1395). Section 4's two longest items shrank to their outcomes with the displaced knowledge moved rather than deleted, and section 6 now states only what each type adds, carrying no N/A list at all. **The review loop's stop rule and disposition policy** (#1330), rewriting disposal by deletion and committing the condition under which a whole-unit loop ends, which #1267 filed as missing. **The Merge Gate's bound on an out-of-diff prose finding**, with the reviewer footing recorded (#1333), and reviewer bots scoped away from the generated Skill mirrors (#1329) so a mirror's diff is never reviewed in place of its source. **The fleet label set**, declared and applied through `configure.sh` (#1334). **The review ledger and skills digest decoupled from the working tree** (#1328), so concurrent branches no longer conflict in a generated report that cannot be hand-merged. Plus one grouped Dependabot bump, `docker/setup-qemu-action` 4.2.0 to 4.3.0 (#1325). ## What is deliberately not closed `#1311`, `#1317`, `#1206`, `#1367`, `#1369`, `#1370`, `#1371`, `#1386` and `#1237` each still hold findings this work did not settle. #1317 stands at class 6 of fourteen, and #1311's step 17 comment records what the reshape filed rather than fixed. ## Owed on merge `spec/files.json` declares both edited `GOVERNANCE.md` sections at `verbatim` fidelity, so every downstream copy goes stale on this promotion and a fleet resync follows it. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull request 5 of the #1311 reshape sequence, and what
AGENTS.mdalready requires of these two surfaces: "A Skill that needs a rule's full text to work in isolation carries it as a generated include from the rule's home rather than as a copy."Only
references/d-guarantees.mdcomplied.SKILL.md's "The Core Behavioral Spine" restatedWORKFLOW.mdsection 3 and parts of section 4 by hand, andreferences/test-methodology.mdrestated section 5 by hand while describing itself as "an index into them rather than as the sweep itself". Both had already drifted, in both directions at once, andbuild_dist.py --checkheld neither to its source. The evidence is on #1386.What changed
references/architecture.mdis new and carriesWORKFLOW.mdsection 3 whole through an include region.references/test-methodology.mdnow carries section 5 the same way. With the existingd-guarantees.mdthe skill carries sections 3, 4, and 5, andSKILL.mdsays where sections 1, 2, and 6 stay.SKILL.mddrops from 8.2 KB to 5.5 KB, which is the directiondocs/token-efficiency-plan.mdasks for, and the two drifted claims it carried are gone rather than realigned: "repo-owned" for "repo-owned in shape" (Tracker:.agents/skills/workflow-ci-contract/SKILL.md#1386 item 5), and a hand-written second statement of D6.4 that nothing held to its source.docs/fleet-map.mdandskill-lifecycle's doc-packaging examples are swept to match.This also settles #1336 item 2, where
AGENTS.mdclaimed the skill surfaces the fullWORKFLOW.mdcontract while the skill's own scope said summary plus one include plus an index. The claim is now true, so the map row needed no weakening.The spine's citations of
GOVERNANCE.md"Workflow YAML Conventions" for the validate-at-entry and consume-then-delete rules go with it, which settles #1386 item 16.Review passes
Four whole-unit carried-content passes over 12 units and two diff passes, on the strongest tier. They raised roughly 30 findings, 8 of them introduced by this change and fixed here. The rest are pre-existing defects in
WORKFLOW.mdsections 3, 5, and 6, which this change deliberately does not touch, since pull requests 2, 3, and 4 of the sequence own that text. They will be filed as a follow-up issue rather than fixed in passing.Two findings were declined with evidence.
docs/fleet-map.md's P2 rollout checkbox still describes the two-split shape G9 actually delivered, and updating a completed checkbox would misreport what that phase shipped. And the five ledger entries this change orphans stay, becausereports/canonical-review.jsonsays it is "written byscripts/canonical_review.py record, never by hand" and that script has no prune, soreportrendering them for a reader is the designed behavior rather than a defect.🤖 Generated with Claude Code