Name a Pin by Its Mechanism, Never Its Value, and Audit for Copies

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

@@ -208,7 +208,10 @@ and the fleet's own rule documents: `AGENTS.md`, `AUDIT.md`, `CLAUDE.md`, `CODES
 `GOVERNANCE.md`, `OPERATIONS.md`, `RESYNC.md`, `STANDUP.md`, `WORKFLOW.md`, and
 `.github/copilot-instructions.md`. A tracker, a history, a plan, and a README outside those trees
 are the repository's own narrative and keep their references, as do a commit message and a pull
-request body, which are the surfaces a reference belongs on.
+request body, which are the surfaces a reference belongs on. An instruction document also names no
+value a pin holds, a release number or a commit SHA, since the copy goes stale at the next
+Dependabot bump. It names the mechanism instead, such as a reference SHA-pinned to a hub release,
+and item 3 of this skill's carried-doc-references reference carries the audit that flags a copy.
 
 Two carve-outs, each stated as a single case. Whatever neither of them affirmatively permits is
 banned by the paragraph above, which is the whole of the test and is why no list of banned cases

.agents/skills/comment-and-doc-style/references/carried-doc-references.md

@@ -14,7 +14,7 @@ verbatim, and this rule does not reach them.
 
 ## What is banned
 
-Two things, in the files above:
+Three things, in the files above:
 
 1. **Any reference to the template repo**, in prose or in a link. The coordination flow that
    produced a carried file is machinery a consumer of that repo should never have to see, and
@@ -25,6 +25,16 @@ Two things, in the files above:
 2. **A sibling fleet repo named as an illustrative example** ("repo X does it this way", "see repo
    Y's adoption"), which couples the repos and rots as they diverge. To point at a current good
    example, name it in the onboarding or conformance issue, never in a carried doc.
+3. **A value a pin holds**, the release number or commit SHA a pinned workflow, action, or tool
+   currently points at ("SHA-pinned at hub release 2.0.x", with a real number in place of the x).
+   The pin lives in the workflow or manifest that uses it, where Dependabot moves it, so the copy in
+   prose is stale at the next bump and sends the next agent to edit governance for a change that
+   needed none. Name the mechanism instead ("SHA-pinned to a hub release, with the release in a
+   trailing comment"). The audit flags a three-part version or a full SHA in `AGENTS.md`,
+   `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md`, outside their verbatim sections downstream and
+   across the whole file in the hub. `.github/copilot-instructions.md` is left out of that scan,
+   since its disproved-claims records name a revision by design, which the revision carve-out in
+   `GOVERNANCE.md` "References" permits.
 
 ## The two exceptions
 

.claude-plugin/fleet-skills/.source-digests/comment-and-doc-style

@@ -1 +1 @@
-d4024b32e9692f89
+74f03860c1a0b71c

.claude-plugin/fleet-skills/skills/comment-and-doc-style/SKILL.md

@@ -208,7 +208,10 @@ and the fleet's own rule documents: `AGENTS.md`, `AUDIT.md`, `CLAUDE.md`, `CODES
 `GOVERNANCE.md`, `OPERATIONS.md`, `RESYNC.md`, `STANDUP.md`, `WORKFLOW.md`, and
 `.github/copilot-instructions.md`. A tracker, a history, a plan, and a README outside those trees
 are the repository's own narrative and keep their references, as do a commit message and a pull
-request body, which are the surfaces a reference belongs on.
+request body, which are the surfaces a reference belongs on. An instruction document also names no
+value a pin holds, a release number or a commit SHA, since the copy goes stale at the next
+Dependabot bump. It names the mechanism instead, such as a reference SHA-pinned to a hub release,
+and item 3 of this skill's carried-doc-references reference carries the audit that flags a copy.
 
 Two carve-outs, each stated as a single case. Whatever neither of them affirmatively permits is
 banned by the paragraph above, which is the whole of the test and is why no list of banned cases

.claude-plugin/fleet-skills/skills/comment-and-doc-style/references/carried-doc-references.md

@@ -14,7 +14,7 @@ verbatim, and this rule does not reach them.
 
 ## What is banned
 
-Two things, in the files above:
+Three things, in the files above:
 
 1. **Any reference to the template repo**, in prose or in a link. The coordination flow that
    produced a carried file is machinery a consumer of that repo should never have to see, and
@@ -25,6 +25,16 @@ Two things, in the files above:
 2. **A sibling fleet repo named as an illustrative example** ("repo X does it this way", "see repo
    Y's adoption"), which couples the repos and rots as they diverge. To point at a current good
    example, name it in the onboarding or conformance issue, never in a carried doc.
+3. **A value a pin holds**, the release number or commit SHA a pinned workflow, action, or tool
+   currently points at ("SHA-pinned at hub release 2.0.x", with a real number in place of the x).
+   The pin lives in the workflow or manifest that uses it, where Dependabot moves it, so the copy in
+   prose is stale at the next bump and sends the next agent to edit governance for a change that
+   needed none. Name the mechanism instead ("SHA-pinned to a hub release, with the release in a
+   trailing comment"). The audit flags a three-part version or a full SHA in `AGENTS.md`,
+   `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md`, outside their verbatim sections downstream and
+   across the whole file in the hub. `.github/copilot-instructions.md` is left out of that scan,
+   since its disproved-claims records name a revision by design, which the revision carve-out in
+   `GOVERNANCE.md` "References" permits.
 
 ## The two exceptions
 

.github/skills/comment-and-doc-style/SKILL.md

@@ -208,7 +208,10 @@ and the fleet's own rule documents: `AGENTS.md`, `AUDIT.md`, `CLAUDE.md`, `CODES
 `GOVERNANCE.md`, `OPERATIONS.md`, `RESYNC.md`, `STANDUP.md`, `WORKFLOW.md`, and
 `.github/copilot-instructions.md`. A tracker, a history, a plan, and a README outside those trees
 are the repository's own narrative and keep their references, as do a commit message and a pull
-request body, which are the surfaces a reference belongs on.
+request body, which are the surfaces a reference belongs on. An instruction document also names no
+value a pin holds, a release number or a commit SHA, since the copy goes stale at the next
+Dependabot bump. It names the mechanism instead, such as a reference SHA-pinned to a hub release,
+and item 3 of this skill's carried-doc-references reference carries the audit that flags a copy.
 
 Two carve-outs, each stated as a single case. Whatever neither of them affirmatively permits is
 banned by the paragraph above, which is the whole of the test and is why no list of banned cases

.github/skills/comment-and-doc-style/references/carried-doc-references.md

@@ -14,7 +14,7 @@ verbatim, and this rule does not reach them.
 
 ## What is banned
 
-Two things, in the files above:
+Three things, in the files above:
 
 1. **Any reference to the template repo**, in prose or in a link. The coordination flow that
    produced a carried file is machinery a consumer of that repo should never have to see, and
@@ -25,6 +25,16 @@ Two things, in the files above:
 2. **A sibling fleet repo named as an illustrative example** ("repo X does it this way", "see repo
    Y's adoption"), which couples the repos and rots as they diverge. To point at a current good
    example, name it in the onboarding or conformance issue, never in a carried doc.
+3. **A value a pin holds**, the release number or commit SHA a pinned workflow, action, or tool
+   currently points at ("SHA-pinned at hub release 2.0.x", with a real number in place of the x).
+   The pin lives in the workflow or manifest that uses it, where Dependabot moves it, so the copy in
+   prose is stale at the next bump and sends the next agent to edit governance for a change that
+   needed none. Name the mechanism instead ("SHA-pinned to a hub release, with the release in a
+   trailing comment"). The audit flags a three-part version or a full SHA in `AGENTS.md`,
+   `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md`, outside their verbatim sections downstream and
+   across the whole file in the hub. `.github/copilot-instructions.md` is left out of that scan,
+   since its disproved-claims records name a revision by design, which the revision carve-out in
+   `GOVERNANCE.md` "References" permits.
 
 ## The two exceptions
 

AUDIT.md

@@ -31,7 +31,7 @@ This audit is not occasional. Run it whenever you **create, adopt, or materially
 
 - **A full sweep opens with a fleet membership check, not a per-repo one.** `spec/audit.py`, run with no repo names, first lists every non-fork repository the registry `owner` actually owns on GitHub and diffs it against `registry/repos.json`. A repo that exists but carries no entry is invisible to every other check in this file, since all of them iterate the registry and never look past it, so this is the only place that gap is caught. The check also reconciles one field: a registry `status: "archived"` must agree with GitHub's own archived flag, in either direction. A name-filtered run or `--issue` skips it, since those are scoped to repos already known to the registry. Run this as `gh auth login` for the owner's own account: a fine-grained PAT scoped to "selected repositories" returns an incomplete list with no error, so the sweep would read clean while some repos were never inspected.
 - **Onboarding a repo is complete only when it either passes this audit** (operational on every applicable check) **or carries a committed `reports/<repo>/audit.md` plus a tracking issue** enumerating every residual delta. A repo that is partially set up but never audited is itself a **defect**, the exact state this process prevents. The create-to-conformance counterpart is [`STANDUP.md`][standup]. Because both read the same manifests, a repo stood up by that file passes this audit by construction.
-- **Touching a repo** (any conformance-affecting change) ends by re-running the applicable checks and **reconciling the registry entry to reality**: `status`, `types`, `releaseTrigger`, `workflowModel`, `driftNotes`. The registry records reality, not intent. [`spec/validate.py`][validate] proves the catalog is self-consistent, not that it matches the live repo. Closing that gap is this audit's job. The deterministic subset (settings, rulesets, secret names, file presence, per-scope Markdown section presence, workflow interface conformance, verbatim content, hub-hosted files a repo carries, branch facts) is mechanized in [`spec/audit.py`][audit-runner]: owner-initiated, run on demand when onboarding a repo, on suspected drift, or before fleet-wide changes. A required section missing from a carried Markdown file is a **drift finding**, not a letter, because a heading rename reads as missing and equivalence is judged by hand. A carried `interface` workflow (spec/fidelity-model.md) is checked by name and wiring (required jobs, the ruleset-bound check name, the artifact-name handoff, and the forbidden `artifact-ids:` fork), all at **drift**, since the body is owned and a rename is a hint to verify. A carried `verbatim` unit, whether a whole file (`.markdownlint-cli2.jsonc`) or a canonical workflow job region (the `github-release` job), is content-hashed against the hub's canonical after line-ending normalization. A mismatch is classified **stale** (matches a past hub revision, re-vendor) or **modified** (matches none, the repo changed fixed content), both at **drift**, since equivalence is intent-governed and a byte diff is a hint to review. A carried `intent` unit gets one advisory beyond presence, a last-modified comparison: a hub canonical changing after the copy's own last commit marks the copy as possibly trailing, at **drift**, a hint rather than proof, since a copy touched without reconciling reads current and content is never judged.
+- **Touching a repo** (any conformance-affecting change) ends by re-running the applicable checks and **reconciling the registry entry to reality**: `status`, `types`, `releaseTrigger`, `workflowModel`, `driftNotes`. The registry records reality, not intent. [`spec/validate.py`][validate] proves the catalog is self-consistent, not that it matches the live repo. Closing that gap is this audit's job. The deterministic subset (settings, rulesets, secret names, file presence, per-scope Markdown section presence, workflow interface conformance, verbatim content, hub-hosted files a repo carries, branch facts) is mechanized in [`spec/audit.py`][audit-runner]: owner-initiated, run on demand when onboarding a repo, on suspected drift, or before fleet-wide changes. A required section missing from a carried Markdown file is a **drift finding**, not a letter, because a heading rename reads as missing and equivalence is judged by hand. A carried `interface` workflow (spec/fidelity-model.md) is checked by name and wiring (required jobs, the ruleset-bound check name, the artifact-name handoff, and the forbidden `artifact-ids:` fork), all at **drift**, since the body is owned and a rename is a hint to verify. A carried `verbatim` unit, whether a whole file (`.markdownlint-cli2.jsonc`) or a canonical workflow job region (the `github-release` job), is content-hashed against the hub's canonical after line-ending normalization. A mismatch is classified **stale** (matches a past hub revision, re-vendor) or **modified** (matches none, the repo changed fixed content), both at **drift**, since equivalence is intent-governed and a byte diff is a hint to review. A carried `intent` unit gets one advisory beyond presence, a last-modified comparison: a hub canonical changing after the copy's own last commit marks the copy as possibly trailing, at **drift**, a hint rather than proof, since a copy touched without reconciling reads current and content is never judged. A content scan also looks for a copied version: a three-part version or a full 40-character commit SHA in `AGENTS.md`, `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md`, outside the verbatim sections downstream and across the whole file in the hub, is a **drift** finding, since a pin's value in prose goes stale at the next bump.
 
 **Verify the host before running any hub tool.** The tools carry version floors, and a host below one answers `--version`, looks healthy, and produces a wrong answer, so a clean audit run from a broken host is a clean-looking result rather than a result.
 

GOVERNANCE.md

@@ -165,7 +165,7 @@ The full comment philosophy, what earns one, structure, capitalization, growth d
 
 ### References
 
-No comment, no docstring, and no instruction document names an issue, a pull request, or a commit, and a commit message and a pull request body each carry theirs as usual. Two carve-outs. In a code or workflow comment, a URL naming an issue or a pull request on a public repository other than this one is a source citation and is permitted. And a record whose subject is the revision itself keeps it, which is what lets a disproved-claims entry in `.github/copilot-instructions.md` name the revision its proof was read against. Whatever neither carve-out affirmatively permits is banned by the sentence above them, which is the whole of the test. The reasons, the surfaces the ban reaches, the narrative files it leaves alone, and what to write instead are in the `comment-and-doc-style` Skill referenced above.
+No comment, no docstring, and no instruction document names an issue, a pull request, or a commit, and a commit message and a pull request body each carry theirs as usual. An instruction document also names no value a pin holds, a release number or a commit SHA, since the pin lives in the workflow or manifest that uses it, where Dependabot moves it, and a copy in prose is stale at the next bump. It names the mechanism instead, such as a reference SHA-pinned to a hub release. Two carve-outs. In a code or workflow comment, a URL naming an issue or a pull request on a public repository other than this one is a source citation and is permitted. And a record whose subject is the revision itself keeps it, which is what lets a disproved-claims entry in `.github/copilot-instructions.md` name the revision its proof was read against. Whatever neither carve-out affirmatively permits is banned by the sentences above them, which is the whole of the test. The reasons, the surfaces the ban reaches, the narrative files it leaves alone, and what to write instead are in the `comment-and-doc-style` Skill referenced above.
 
 ### Character Set