Cite a Contract Section in a Comment Without Echoing It by ptr727 · Pull Request #2918 · ptr727/ProjectTemplate

ptr727 · 2026-10-12T21:24:35Z

Refs #2907

Summary

Comments that named a contract section and also copied or paraphrased its reasoning now keep the citation and drop the copy. Where nothing local remained, the comment became a bare pointer such as See D5.2. This covers the hub workflows, the catalog snippets, and the stubs docs/reusable-workflows.md mirrors.
GOVERNANCE.md "Workflow YAML Conventions", Concurrency bullet: each documented exception is cited by number, never restated, in the comment above its implementing workflow's concurrency: key. The tails of (3) and (4) that placed the rationale in the bullet rather than a header comment are gone. The merge-bot, publisher, and canonical-review-sweep comments now carry the citation alone.
The comment-and-doc-style Comments bullet now settles that a paraphrase counts as echoing, that an id unique across the instruction set (a WORKFLOW.md D-id) may stand alone while any other citation names its file, and that a citable section is one of the fleet's own instruction set.
Distributions regenerated with scripts/build_dist.py.

Carries the comments label, since editing comments is the change.

Local review findings and their outcomes

Fixed in 00f2519: the root-default comment in .github/workflows/validate-task.yml is now the bare pointer See D1.2 for the undeclared root.
Fixed in 00f2519: the prune comment in .github/workflows/deploy-site-task.yml no longer says a write-only repo skips a step that still runs its no-op hook.
Declined with evidence in the thread: Concurrency exception (3) is implemented only in a site repository's own deploy caller, which holds the carried bullet itself.
style, declined: the Concurrency bullet's "never restated" and the Skill's "echoes or paraphrases" use different verbs for one rule.
Declined with evidence: positional exception numbers can shift on insertion, but WORKFLOW.md D-ids are positional numbers cited from comments the same way.
Declined: the prune comment describes a write-only repo's hook per repo, as WORKFLOW.md's own hook-target row does, so a per-environment refinement belongs in that row first.

Filed

Document or Reshape the Codegen Snippet's Workflow-Only Concurrency Group #2915: the codegen snippet's workflow-only concurrency group matches no documented exception.
Say Whether a Comment May Cite a Hub docs/ Section #2916: whether a comment may cite a hub docs/ section.
Drop the Verification Discipline Restatement From the Validate Action's Burn-Down Comment #2917: the validate action's burn-down comment restates "Verification Discipline".

🤖 Generated with Claude Code

Comments that named a contract section and also copied its reasoning keep the citation and drop the copy. The Concurrency exceptions are now cited by number in their implementing workflows' header comments rather than restated there, and the Comments rule settles paraphrase, bare ids, and which sections count. Refs #2907 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…ntract-echo

The D5.2 and D1.6 citations keep only the section id, the prune comment keeps its local reason, and the Concurrency bullet names the comment above the concurrency key rather than a header comment. Refs #2907 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The validate-task D1.6 comments point at the section rather than restating it, the prune comment no longer contradicts its no-op hook line, and the sweep header drops its first-run history. Refs #2907 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…ntract-echo

coderabbitai · 2026-10-12T21:24:44Z

Important

🔍 Trigger review

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

⚙️ Run configuration

Configuration used: Repository: ptr727/ProjectTemplate/.coderabbit.yaml
Review profile: CHILL
Plan: Advanced
Run ID: 8d897d8f-4228-46fd-ac03-76ead62f320b

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

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

Copilot

🟡 Changes recommended

Open findings remain in workflow comments, citation guidance, and concurrency documentation.

5 open findings

Clarify whether hub documentation is citable · New
Restore rationale for the default-branch trigger · New
Restore the D5.6 citation · New
Remove undocumented historical gate wording · New
Add a canonical citation for concurrency exception 3 · New

What changed in this PR

This PR replaces repeated workflow rationale with contract citations and regenerates comment-style guidance.

Changes:

Simplifies workflow and catalog comments.
Clarifies citation and concurrency rules.
Regenerates distributed skill files and digests.

File	Summary
`GOVERNANCE.md`	Updates concurrency exception guidance.
`docs/reusable-workflows.md`	Updates workflow comment citations.
`catalog/snippets/workflows/test-pull-request.yml`	Simplifies contract comments.
`catalog/snippets/workflows/publish-release.yml`	Updates release comments.
`catalog/snippets/workflows/merge-bot-pull-request.yml`	Adds concurrency citations.
`.github/workflows/validate-task.yml`	Simplifies validation comments.
`.github/workflows/publish-release.yml`	Updates publish comments.
`.github/workflows/merge-bot-pull-request.yml`	Adds concurrency citations.
`.github/workflows/get-version-task.yml`	Simplifies versioning comments.
`.github/workflows/deploy-site-task.yml`	Revises deployment comments.
`.github/workflows/canonical-review-sweep.yml`	Updates sweep comments.
`.github/workflows/build-release-task.yml`	Simplifies release comments.
`.github/skills/comment-and-doc-style/SKILL.md`	Updates citation guidance.
`.claude-plugin/fleet-skills/skills/comment-and-doc-style/SKILL.md`	Regenerates skill guidance.
`.claude-plugin/fleet-skills/.source-digests/comment-and-doc-style`	Updates the source digest.
`.agents/skills/comment-and-doc-style/SKILL.md`	Updates canonical comment guidance.

🧠 Review effort: Lite

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

codecov · 2026-10-12T21:28:49Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (develop@813ae67). Learn more about missing BASE report.

Additional details and impacted files

@@            Coverage Diff             @@
##             develop    #2918   +/-   ##
==========================================
  Coverage           ?   60.00%           
==========================================
  Files              ?       17           
  Lines              ?     8773           
  Branches           ?        0           
==========================================
  Hits               ?     5264           
  Misses             ?     3509           
  Partials           ?        0

Flag	Coverage Δ
python-3.13	`60.00% <ø> (?)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

The prune comment points at D5.6, the root-default comment states current behavior instead of an old gate, and the sweep header drops a line whose only consequence was its first run, which has already happened. Refs #2907 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The root-default comment names D1.2 rather than restating its condition, and the prune block no longer restates the D5.6 ownership its pointer names. Refs #2907 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

ptr727 · 2026-10-12T21:48:31Z

A recorded local strict-review pass covers head 5de85b7bae479673ecf198e41b9bf74e5088e985, the content this pull request carries at that commit against develop, and it recorded 2 findings.

…mment The root-default comment names D1.2 alone, and the prune comment no longer says a write-only repo skips a step that still runs its no-op hook. Refs #2907 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…ntract-echo

ptr727 · 2026-10-12T22:02:16Z

A recorded local strict-review pass covers head 3430f8198b614ac559216caa43769edf1d4d4bc0, the content this pull request carries at that commit against develop, and it recorded 2 findings.

…t Citation Fixes to Main (#2919) - #2910 reads the open handoff chain through `handoff.py tracks --json` in the `session-handoff` and `unattended-handoff` skills, not the search index - #2913 names the shared stash in the GOVERNANCE.md write-safety law and the host-wide agent-safety block - #2914 shares one GraphQL transport and cursor walker between `pr_review.py` and `handoff.py` - #2911 states the no-`push` condition in D4.1 and drops the `!= 'schedule'` form from the audit - #2918 lets a comment cite a contract section without echoing it, and cites the Concurrency exceptions by number Closes #2902 Closes #2900 Closes #2903 Closes #2904 Closes #2907 🤖 Generated with [Claude Code](https://claude.com/claude-code)

ptr727 and others added 5 commits October 12, 2026 13:53

Merge remote-tracking branch 'origin/develop' into feature/comment-co…

e395d70

…ntract-echo

Merge remote-tracking branch 'origin/develop' into feature/comment-co…

d0f7a47

…ntract-echo

Copilot AI lite review requested due to automatic review settings October 12, 2026 21:24

ptr727 added the comments Permits the comment lines the pull request adds or edits, which the prose gate otherwise refuses label Oct 12, 2026

Copilot started reviewing on behalf of ptr727 October 12, 2026 21:25

View session

Copilot AI reviewed Oct 12, 2026

View reviewed changes

Comment thread .agents/skills/comment-and-doc-style/SKILL.md

Comment thread .github/workflows/canonical-review-sweep.yml Outdated

Comment thread .github/workflows/deploy-site-task.yml Outdated

Comment thread .github/workflows/validate-task.yml Outdated

Comment thread GOVERNANCE.md

ptr727 and others added 2 commits October 12, 2026 14:37

Point the Root-Default and Prune Comments at Their Sections

5de85b7

The root-default comment names D1.2 rather than restating its condition, and the prune block no longer restates the D5.6 ownership its pointer names. Refs #2907 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

ptr727 and others added 2 commits October 12, 2026 14:53

Merge remote-tracking branch 'origin/develop' into feature/comment-co…

3430f81

…ntract-echo

ptr727 merged commit 203d283 into develop Oct 12, 2026
13 checks passed

ptr727 deleted the feature/comment-contract-echo branch October 12, 2026 22:12

ptr727 mentioned this pull request Oct 12, 2026

Promote the Handoff Read, Stash Law, GraphQL Walker, D4.1, and Comment Citation Fixes to Main #2919

Merged

ptr727 mentioned this pull request Oct 12, 2026

Session Handoff [engineering]: #2902, #2900, #2903, #2904, #2907 Released as 2.0.1002, #2916 Decision and #2915 Next #2921

Closed

Navigation Menu

Repository navigation

Cite a Contract Section in a Comment Without Echoing It - #2918

Cite a Contract Section in a Comment Without Echoing It#2918
ptr727 merged 9 commits into
developfrom
feature/comment-contract-echo

ptr727 commented Oct 12, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Oct 12, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Oct 12, 2026 •

edited

Loading

Uh oh!

ptr727 commented Oct 12, 2026

Uh oh!

ptr727 commented Oct 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

ptr727 commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Local review findings and their outcomes

Filed

Uh oh!

coderabbitai Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ptr727 commented Oct 12, 2026

Uh oh!

ptr727 commented Oct 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ptr727 commented Oct 12, 2026 •

edited

Loading

coderabbitai Bot commented Oct 12, 2026 •

edited

Loading

codecov Bot commented Oct 12, 2026 •

edited

Loading