You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Name a Pin by Its Mechanism, Never Its Value, and Audit for Copies - #1809
Agents repeatedly proposed "updating governance" after a Dependabot bump, because an instruction document had copied a pin's current value, such as "SHA-pinned at hub release 2.0.x". The value goes stale at every bump. This PR stops that at the rule and at the audit.
GOVERNANCE.md "References": an instruction document names no value a pin holds, whether a release number or a commit SHA. It names the mechanism instead. The ban sits with the issue/PR/commit ban, ahead of the carve-outs, so the revision carve-out still covers a disproved-claims record.
comment-and-doc-style reference: carried-doc-references.md item 3 gives the reason and what to write instead.
spec/audit.py: version_literals_outside_verbatim flags a three-part version or a 40-hex SHA as a drift finding. It reads AGENTS.md, GOVERNANCE.md, CODESTYLE.md, and WORKFLOW.md. Downstream, it skips the verbatim sections; in the hub, it reads the whole file, since the verbatim sections are the hub's own copies. .github/copilot-instructions.md is excluded, because its disproved-claims records name revisions by design. strip_sections gains keep_pins, because its normalization rewrites a pinned uses: line to <pin> and would hide the value. The selftest has 8 cases.
AUDIT.md and spec/fidelity-model.md describe the new content scan.
The hub's four instruction documents scan clean. Two downstream repos currently carry copied values in their own sections, and each gets its own cleanup PR after this merges.
Instruction documents stop copying a pin's release number or SHA, which
goes stale at every Dependabot bump and sends an agent to edit
governance for a change that needed none. GOVERNANCE.md References and
the comment-and-doc-style reference state the rule. spec/audit.py flags
a three-part version or full SHA in AGENTS.md, GOVERNANCE.md,
CODESTYLE.md, or WORKFLOW.md outside their verbatim sections, with
selftest cases.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… Check
Answers the strict review: the hub's own run scans verbatim sections,
where a copied pin would otherwise go undetected everywhere, an
unreadable file is reported rather than skipped, the finding names what
it matched, the pin ban moves ahead of the References carve-outs, and
AUDIT.md and spec/fidelity-model.md name the new content scan.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Answers the second strict pass: the reference file names where the
revision carve-out lives, the References test cites the sentences above
it, AUDIT.md stops calling the version scan the only content scan, the
no-remote warning names both hub-identity checks, and an uppercase SHA
gains a selftest case.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…ning
Answers the pre-push strict review: the comment-and-doc-style section
GOVERNANCE References defers to now states the pin ban and its remedy,
and the no-remote warning covers every hub-scoped check, and false
findings as well as misses.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This PR tightens the fleet documentation contract by banning copied pin values (release numbers or commit SHAs) in instruction documents, and extends the audit tooling to detect and report those copied literals as drift so they do not keep triggering unnecessary governance edits after Dependabot bumps.
Changes:
Extend GOVERNANCE.md "References" to forbid naming a pin's current value in instruction documents, requiring mechanism-based phrasing instead.
Add a new audit scan in spec/audit.py to flag three-part versions and 40-hex SHAs found in instruction-doc prose (with verbatim-section handling and selftests).
Update audit documentation (AUDIT.md, spec/fidelity-model.md) and the comment-and-doc-style reference to describe the new rule and scan.
File
Description
spec/fidelity-model.md
Updates the fidelity model narrative to include the new copied-version scan impact.
spec/audit.py
Implements version/SHA literal detection outside verbatim sections and adds selftests.
GOVERNANCE.md
Adds the new "pin mechanism, not value" rule alongside existing reference bans.
AUDIT.md
Documents the new drift scan for copied versions/SHAs in instruction documents.
Answers the strict pass: the warning says the template-reference scan
may miss in every repo while false findings land on the hub's own entry,
and AUDIT.md names the full 40-character SHA the scan actually matches.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Every enumeration of what the fallback hub name breaks missed a case, so
the warning now says every check that depends on the hub's identity is
unreliable in that run.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Copilot review overview
🔵 Needs a closer look
The new audit scope and related prose have a few correctness/conformance issues (scan coverage gap, style violation, and docstring mismatch) that should be fixed before approval.
VERSION_LITERAL_SCANNED omits AUDIT.md, but GOVENANCE.md frames the rule as applying to instruction documents in general, and carried-doc-references.md item 3 already lists the carried AUDIT.md as governed. Without scanning AUDIT.md, the new enforcement can miss copied pin values added there.
This reference says the version-literal audit flags copies in AGENTS.md/GOVERNANCE.md/CODESTYLE.md/WORKFLOW.md, but the surrounding text says the carried AUDIT.md is governed too. If the audit is updated to scan AUDIT.md, include it here so the documented contract matches the implementation.
Docstring misstates normalization output format
spec/audit.py:744
The strip_sections docstring says normalization reduces an action pin to <pin>, but normalize() actually rewrites uses: ...@<sha> to ...@<pin>. This mismatch makes the new keep_pins behavior harder to reason about when reading the code.
Audit message uses a prohibited semicolon
spec/audit.py:2679
The audit finding message uses a mid-sentence semicolon, which violates the repository's no-semicolon-in-agent-authored-prose rule (it is user-facing prose emitted by a hub tool). Recast as two sentences or with a comma.
The reason will be displayed to describe this comment to others. Learn more.
Copilot review overview
🔵 Needs a closer look
It introduces a rule forbidding pin values in instruction documents but still includes a concrete pin value example in the source skill references, and there is also a small docstring/behavior mismatch in the new audit code.
strip_sections says normalization reduces an action pin to <pin>, but normalize() actually rewrites @<sha> to @<pin> (including the @). Updating the docstring to match the actual normalized form avoids confusion when someone is debugging why a pin literal no longer appears in normalized text.
…Real Release Number
Fixes the failing test_prose_lint check, which reads the opening
paragraph's backticked Markdown paths as the instruction-doc list, by
naming the reference file without a path. Answers Copilot on #1809 by
replacing the example release number with a placeholder.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Copilot review overview
🟢 Approval recommended
The rule change and the new drift scan are consistent with the updated documentation, and spec/audit.py --selftest completes successfully with the added cases.
… Abbreviated SHAs (#1813)
## Summary
This settles one end state for the fleet, which the maintainer chose.
`AGENTS.md`, `GOVERNANCE.md`, `CODESTYLE.md`, and `WORKFLOW.md` carry no
three-part version and no commit SHA, full or abbreviated. That covers
four kinds of literal, because no check can tell them apart:
| Kind | Written instead as |
| --- | --- |
| a pin's value | its mechanism ("SHA-pinned to a hub release") |
| an illustrative example | a placeholder (`1.0.N`) |
| a minimum version | the name of the manifest or skill that holds the
number |
| a fixed constant | a description ("the all-zero placeholder version")
|
A two-part language minimum, such as a Python minor, stays. It is how
such a rule is stated.
- **Rule text:** GOVERNANCE.md "References", `comment-and-doc-style`,
and its `carried-doc-references.md` item 3 state exactly what the audit
enforces.
- **Audit:** `spec/audit.py` also flags an abbreviated SHA of 7 to 12
characters mixing digits and letters, as a standalone token. Selftest
cases cover both directions: an abbreviated SHA and a worked example are
flagged, while a placeholder, a hex color, a hex constant, an all-letter
word, and an identifier suffix are not.
- **Docs:** AUDIT.md and spec/fidelity-model.md describe the widened
scan.
This follows up #1809, which banned only a pin's value. A fleet scan
found worked examples, minimum-version floors, and constants in the same
files. Downstream fixes follow, one PR per affected repository.
## Verification
- `audit.py --selftest` passes, and the hub's four files scan clean.
- `build_dist.py --check`, `prose_lint.py --diff origin/develop
--allow-comments`, `docker_lint.py` (7 linters), and the
`test_prose_lint` and `test_build_dist` suites pass.
- The local strict review ran two edit rounds. The last pass raised 3
findings, which are answered in this PR's first fix commit.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…rship to Main (#1827)
Promotes `develop` to `main`.
## Carried
- #1806: adds the unattended handoff loop and the attended resume
procedure.
- #1807: renames three skills and states which skill wins each shared
trigger.
- #1809: names a pin by its mechanism rather than its value, and audits
for copies.
- #1808: leads every choice with a recommendation and closes every
session in order.
- #1813: bans every version literal in the four instruction documents
and catches abbreviated SHAs, following #1809.
- #1820: refuses a coverage marker indented into a code block, per
#1725.
- #1823: states that the hub commits audit reports and that a downstream
session resyncs itself. This covers the Fleet Bootstrap section, the
host fleet block, `RESYNC.md`, `AUDIT.md`, `check-this-repo`, and
`resync-a-repo`, and settles #1822. The Fleet Bootstrap section is
byte-locked, so every carrier reports drift on it until its next resync.
- #1825: strips a tilde or unclosed fence before reading review
coverage, per #1821.
Closes#1725Closes#1821Closes#1822
🤖 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
commentsPermits the comment lines the pull request adds or edits, which the prose gate otherwise refuses
2 participants
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.
ptr727
added
the
comments
Summary
Agents repeatedly proposed "updating governance" after a Dependabot bump, because an instruction document had copied a pin's current value, such as "SHA-pinned at hub release 2.0.x". The value goes stale at every bump. This PR stops that at the rule and at the audit.
comment-and-doc-stylereference:carried-doc-references.mditem 3 gives the reason and what to write instead.spec/audit.py:version_literals_outside_verbatimflags a three-part version or a 40-hex SHA as a drift finding. It readsAGENTS.md,GOVERNANCE.md,CODESTYLE.md, andWORKFLOW.md. Downstream, it skips the verbatim sections; in the hub, it reads the whole file, since the verbatim sections are the hub's own copies..github/copilot-instructions.mdis excluded, because its disproved-claims records name revisions by design.strip_sectionsgainskeep_pins, because its normalization rewrites a pinneduses:line to<pin>and would hide the value. The selftest has 8 cases.The hub's four instruction documents scan clean. Two downstream repos currently carry copied values in their own sections, and each gets its own cleanup PR after this merges.
Verification
audit.py --selftestpasses.build_dist.py --check,prose_lint.py --diff origin/develop --allow-comments,docker_lint.py(7 linters), andspec/validate.pypass.commentslabel.🤖 Generated with Claude Code