@erclx/canon 4.22.1 → 4.23.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.22.1",
+  "version": "4.23.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-diagram/SKILL.md

@@ -138,7 +138,7 @@ Stamp every entry that passed. Set `verified` to the short SHA of `HEAD` and tod
 git rev-parse --short HEAD
 ```
 
-The result is one line, `<sha> <date>`, as in `73e9a3f8 2026-08-02`.
+The result is one line, `<sha> <date>`, as in `73e9a3f8 2026-08-02`. <!-- canon-allow-reference: illustrates the verified field's two-token format, which a qualified sha would misstate -->
 
 Stamp nothing else. An entry Step 2 left alone was never re-checked, an entry whose defect survived is known wrong, and an entry whose render was skipped was never seen. All three keep the marker they already carry, and Step 7 names the last two. The field means a render was read back and judged correct, so stamping any of these spends the only signal a reader has on a diagram nobody confirmed.
 

package/claude/skills/claude-docs/references/anchor-sweep.md

@@ -27,7 +27,7 @@ Most of these name a folder rather than a file, because the number an entry anch
 
 The third rule reaches folders alone, which is what keeps it off `CLAUDE.md`. Breadth is the whole reason it exists, and a root file has none: it names one path the diff either carries or does not.
 
-What it does stop is a citation of `.claude/` matching every branch. `src/`, `scripts/`, and `.claude/` each name a tree a project organizes most of its work under, so a prefix match on one fires constantly and rebuilds the ignored warning this sweep exists to avoid. Measured against this repository's record at `87b11e87`, the skip drops 13 of the 26 folder citations and keeps the ones carrying a signal, among them `src/tooling/`, `.claude/rules/`, and `governance/rules/`.
+What it does stop is a citation of `.claude/` matching every branch. `src/`, `scripts/`, and `.claude/` each name a tree a project organizes most of its work under, so a prefix match on one fires constantly and rebuilds the ignored warning this sweep exists to avoid. Measured against this repository's record at `erclx/canon@87b11e87`, the skip drops 13 of the 26 folder citations and keeps the ones carrying a signal, among them `src/tooling/`, `.claude/rules/`, and `governance/rules/`.
 
 A decision whose folder citations are all a single segment, and which cites no file, therefore never fires. That is the correct outcome rather than a gap: a count over a whole tree moves on nearly every branch, so flagging it every time tells a reader that time has passed and nothing else.
 

package/claude/skills/claude-orchestrate/SKILL.md

@@ -119,7 +119,7 @@ Write no shape for a correction. A correction is a sentence, and a format for ad
    - Resolve the target at the moment of sending with `canon sessions list --branch`, never from a mapping written down earlier, since names rotate as sessions end and one recorded earlier in a session has failed inside the hour. The runbook read at step 5 routes on the count and the confidence it answers with
    - Open the message with the worktree and branch the sender believes the reader holds, asking to be corrected, whenever that mapping is inferred rather than confirmed
    - Name the skill for the reader to run rather than writing an invocation, which arrives as text
-   - Read the pull request's own draft flag rather than the state a worker reports, since two reported a draft that read ready inside ninety seconds, and report what the read returned and when rather than the state alone. The flag settles the question only once the worker's chain has run its undo, and nothing marks that moment, so a read taken between the pull request opening and that call sees a genuinely ready pull request about to become a draft. That is how a poll on `#1307` told an operator the opposite of what the worker had said.
+   - Read the pull request's own draft flag rather than the state a worker reports, since two reported a draft that read ready inside ninety seconds, and report what the read returned and when rather than the state alone. The flag settles the question only once the worker's chain has run its undo, and nothing marks that moment, so a read taken between the pull request opening and that call sees a genuinely ready pull request about to become a draft. That is how a poll on `erclx/canon#1307` told an operator the opposite of what the worker had said.
 
 A session is reachable when it appears in a live listing, which reads what each session registered on disk rather than probing it, and a message carries plain text and no authority. When no live session holds the branch, report the invocation for the human, naming the branch, the pull request, and the skill to run, then stop. Retrying or waiting leaves the loop believing it is open while nothing acts on it. Every dispatch in the trial behind this step found a live session, so this branch stands on reasoning rather than on observation.
 

package/claude/skills/claude-orchestrate/references/orchestrator-dispatch.md

@@ -100,7 +100,7 @@ The client expands the first slash command in a launch prompt as a user
 invocation, which is the route `disable-model-invocation: true` permits. Every
 later command in the same prompt reaches the session as prose, leaving the model
 to invoke it through the `Skill` tool, and that route answers a flagged skill
-inconsistently. `claude-autoship` has carried the flag since `#365` and seven
+inconsistently. `claude-autoship` has carried the flag since `erclx/canon#365` and seven
 other shipped skills carry it too.
 
 The block above therefore leads with the call that does not need the user route
@@ -148,7 +148,7 @@ Report the dispatch as loudly as the human-launch line it replaces: name the bra
 
 `claude-address-review` is a single pass, not a chain, so a launch naming it
 alone reaches no `claude-worker` and takes no role, which owes no message
-either. `#1251`'s replacement session was launched that way, onto the branch a
+either. `erclx/canon#1251`'s replacement session was launched that way, onto the branch a
 review had already posted findings against, and it answered by posting a
 thread reply and telling its controller nothing. Reach the role directly on
 this launch instead of wrapping a second chain around one skill that has none

package/claude/skills/claude-orchestrate/references/orchestrator-poll.md

@@ -70,7 +70,7 @@ The state reaches every stalled dispatch, since one threshold governs the headin
 
 The report is also where the count in `## Parallelism` is legible. That threshold trips on open pull requests awaiting a first pass, which is what `OPENED` and a pull request with no prior pass name here and what `SEEN` excludes, so read the count off these lines rather than off `gh pr list`, which counts a branch closed out and waiting on a merge the same as one nobody has read. It is a separate condition from the poll-start fallback above, which decides when this loop runs rather than where a review runs.
 
-The count reads low, and it errs in the direction that breaks the trigger. A review's `commit.oid` is stamped with the head at submission rather than with the commit the reviewer read, so an author pushing between the diff read and the post leaves the pass recorded against a commit it never saw, and `SEEN` then fires on a head still awaiting its first look at that delta. Measured on `#1299` on 2026-08-31, where a pass written against `5653721` landed stamped `a5ceb40` and the delta it skipped was a real fix. So a `SEEN` on a head you do not recognize is worth one `gh pr view --json reviews` before it is believed, and a wave past three is likelier to trip the fallback late than early.
+The count reads low, and it errs in the direction that breaks the trigger. A review's `commit.oid` is stamped with the head at submission rather than with the commit the reviewer read, so an author pushing between the diff read and the post leaves the pass recorded against a commit it never saw, and `SEEN` then fires on a head still awaiting its first look at that delta. Measured on `erclx/canon#1299` on 2026-08-31, where a pass written against `erclx/canon@5653721` landed stamped `erclx/canon@a5ceb40` and the delta it skipped was a real fix. So a `SEEN` on a head you do not recognize is worth one `gh pr view --json reviews` before it is believed, and a wave past three is likelier to trip the fallback late than early.
 
 The other side of that comparison used to lag as well, which made the two errors compound rather than cancel. `gh pr view --json headRefOid` answers from the pull request object and that object trails the branch ref by up to a minute after a push, reporting nothing about the trail, so a pass stamped ahead of the commit it read was compared against a head stamped behind the commit that exists. Two sessions were wrong off that field on 2026-09-01: a reviewing session posted a finding calling a pushed commit unpushed, and a worker fired a green claim it retracted on its own thread minutes later. The head now comes from `canon pr head`, which resolves the tip through `git ls-remote` and reports which commit each source names, and the object's head stays behind it as the fallback for a target whose CLI predates the verb. The review stamp is unchanged, so the paragraph above still holds on its own half.
 

package/claude/skills/claude-pr-review/SKILL.md

@@ -95,7 +95,7 @@ A non-empty result carries the comment id Step 4 needs for the third filename se
 
 A `## Post-review findings` reply carries no argued finding behind it, since it asserts a new defect rather than answering one, and this pass is its first independent reader. Restating it as a finding without opening anything is repeating the worker's claim rather than checking it. Read the file the comment names at `<headRefOid>`, the same `git show <headRefOid>:<path>` read Step 3 already runs to confirm a ticked box, and confirm the defect before it becomes a finding of this pass's own.
 
-A moved head has its own way to add nothing, which the ancestor test cannot see. When `<prior-heading>` reads `## Review closed`, the standing verdict already reports the branch clear, so a pass over the new commits that raises nothing posts a comment saying what the one above it said. Two close-outs landed on `#1201` that way on 2026-08-28, and the operator caught the pair rather than any check.
+A moved head has its own way to add nothing, which the ancestor test cannot see. When `<prior-heading>` reads `## Review closed`, the standing verdict already reports the branch clear, so a pass over the new commits that raises nothing posts a comment saying what the one above it said. Two close-outs landed on `erclx/canon#1201` that way on 2026-08-28, and the operator caught the pair rather than any check.
 
 The producing shape is narrow. A prior pass tells the author a change is their own call, the author makes it, and the delta reaching the next pass has nothing left to say by construction.
 

package/claude/skills/create-skill/SKILL.md

@@ -29,4 +29,4 @@ Read these files in parallel:
 
 Every skill carries a requirement. A skill created without one is a gap someone closes in a later sweep, and the sweep has to reconstruct what the skill was for from the body it already shipped.
 
-The two-question check has a shipped precedent. Pull request `#516` dropped `git-stash` for wrapping a single git command that needed no skill body, and `release-changelog` for being low-frequency and invoked by no other skill. The first is question one, and the second is question three read back after the fact, which is why it stays a review criterion rather than something this skill can gate on.
+The two-question check has a shipped precedent. Pull request `erclx/canon#516` dropped `git-stash` for wrapping a single git command that needed no skill body, and `release-changelog` for being low-frequency and invoked by no other skill. The first is question one, and the second is question three read back after the fact, which is why it stays a review criterion rather than something this skill can gate on.

package/claude/skills/write-human/REQUIREMENT.md

@@ -13,7 +13,7 @@ The output of that arrangement is specific rather than general. Paragraphs come
 
 A session also has no name for the patterns no closed word set can match. Rule-of-three, synonym cycling, false ranges, inline-header lists, and adverb propping each survive a clean scan, so a passage carrying all five reports zero findings and still reads wrong. Nothing tells the session those patterns exist, and a ban list cannot be extended to reach them, because each is a shape rather than a token.
 
-Importing that catalog wholesale fails on a different measurement. External material of this kind bans abstract metaphor nouns and names `surface` among them, which this corpus uses 593 times in tracked markdown at `57ee7467`. A session handed the catalog with no stated position either rewrites established vocabulary or silently ignores the item, and neither outcome is recoverable by a later reader who cannot tell which happened.
+Importing that catalog wholesale fails on a different measurement. External material of this kind bans abstract metaphor nouns and names `surface` among them, which this corpus uses 593 times in tracked markdown at `erclx/canon@57ee7467`. A session handed the catalog with no stated position either rewrites established vocabulary or silently ignores the item, and neither outcome is recoverable by a later reader who cannot tell which happened.
 
 ## Must
 

package/claude/skills/write-human/references/source-material.md

@@ -24,7 +24,7 @@ The ambiguity rules travel with that layer for the same reason. Compression is w
 - **Any restatement of a banned word set.** The bans ship as package data that `canon markdown audit` reads, and a copy here would be a second source for one list with a machine reading the other.
 - **A voice register per surface.** One baseline covers every surface. A surface needing a warmer register states its own voice and claims the yield, which lifts voice alone and leaves the bans, the rhythm rules, and the tells in force.
 
-The first of those four rests on a count. The source names `surface` among the nouns it bans, and tracked markdown in the authoring repository used `surface` 593 times, `harness` 95, `scaffolding` 17, and `primitive` 4, measured at `57ee7467` on 2026-08-19. Adopting the item either rewrites established vocabulary across the corpus or is ignored in silence, and a reader arriving later cannot tell which happened.
+The first of those four rests on a count. The source names `surface` among the nouns it bans, and tracked markdown in the authoring repository used `surface` 593 times, `harness` 95, `scaffolding` 17, and `primitive` 4, measured at `erclx/canon@57ee7467` on 2026-08-19. Adopting the item either rewrites established vocabulary across the corpus or is ignored in silence, and a reader arriving later cannot tell which happened.
 
 ## Where this diverges
 

package/docs/agents/context-audit-checks.md

@@ -55,7 +55,7 @@ The table check reports a catalog that grows a row per shipped thing, not a tabl
 
 The provenance check reports the markers narrating how a domain reached its shape rather than describing what it is: a date, a change number, or a release label. The standard admits a rejected alternative and the reasoning that killed it while refusing the provenance attached to it, so a marker names a line to read rather than a line to delete. Findings group by entry and sort left to right within a line, since what a reader acts on is which file to open.
 
-A date stamping a measurement is excluded, because the standard cuts a date attached to a change and permits one dating a figure. The check reads the clause in front of the date, back to the nearest sentence boundary, for one of five verbs: measured, verified, driven, passed, and fired. The noun `run` counts only where it sits against the date, so `A run on 2026-08-14` is excluded and `Runs on #632 and #634 landed 2026-08-02` reports. The set is closed, and a date it cannot place reports as a change marker rather than as a state of its own, which names one date too many rather than clearing one the rule cuts.
+A date stamping a measurement is excluded, because the standard cuts a date attached to a change and permits one dating a figure. The check reads the clause in front of the date, back to the nearest sentence boundary, for one of five verbs: measured, verified, driven, passed, and fired. The noun `run` counts only where it sits against the date, so `A run on 2026-08-14` is excluded and `Runs on erclx/canon#632 and erclx/canon#634 landed 2026-08-02` reports. The set is closed, and a date it cannot place reports as a change marker rather than as a state of its own, which names one date too many rather than clearing one the rule cuts.
 
 A release label reports with or without its leading `v` at three segments, since the rule cuts the label rather than a spelling of it. Two segments still need the `v`, which keeps a dollar cost and a duration out. Another tool's version reports too, and the check cannot tell one from a release, so treat a version beside a tool name as a line to read rather than one to cut.
 

package/docs/agents/key-changes.md

@@ -28,7 +28,7 @@ The positional is the pull request to read, defaulting to the one open on this b
 
 Without `--body` the body, the file list, and the head commit come back from one `gh pr view` call, because the three have to describe the same commit and reading them apart leaves a window where a push between them compares a body against another head's files.
 
-That view caps its file list at 100 rows and says nothing about having done so, which was measured against `#1250`: the pull request carries 101 files and the view reports 100. A pull request at the cap therefore takes a second read through the paginated endpoint, and a failure there refuses with `gh-truncated` rather than comparing against a set known to be short. A set silently one file short is the worst input this takes, since the missing file is exactly what a correct bullet would then be accused of inventing.
+That view caps its file list at 100 rows and says nothing about having done so, which was measured against `erclx/canon#1250`: the pull request carries 101 files and the view reports 100. A pull request at the cap therefore takes a second read through the paginated endpoint, and a failure there refuses with `gh-truncated` rather than comparing against a set known to be short. A set silently one file short is the worst input this takes, since the missing file is exactly what a correct bullet would then be accused of inventing.
 
 ## The two directions
 
@@ -105,7 +105,7 @@ The bound is that the corpus is one repository writing to one house style. A pro
 
 What it cannot see is a bullet claiming a change to a file the branch did touch for another reason, and a path written without backticks. A claim in a second coordinated clause after the comma is read and credited, and it stays out of the graded direction, since nothing here separates it from a file the same clause cites for context.
 
-One class stays open and is named rather than closed. A bullet can cite where something is defined while claiming an edit somewhere else, as `#1274` does with "Name the slug transform in `standards/slug.md` inline in the same step". The path is a definition site, the edit target is the step, and separating the two needs the sentence parsed rather than cut. A finding on such a bullet is this class rather than a stale claim, and a reader weighing an `unmet` path checks whether the bullet's real target is a locative the path does not name.
+One class stays open and is named rather than closed. A bullet can cite where something is defined while claiming an edit somewhere else, as `erclx/canon#1274` does with "Name the slug transform in `standards/slug.md` inline in the same step". The path is a definition site, the edit target is the step, and separating the two needs the sentence parsed rather than cut. A finding on such a bullet is this class rather than a stale claim, and a reader weighing an `unmet` path checks whether the bullet's real target is a locative the path does not name.
 
 ## Where it runs
 

package/docs/agents/markdown-audit.md

@@ -114,7 +114,7 @@ The unit is the paragraph and each file names its worst on each measure, which f
 
 Neither number gates and neither names a file wrong. This is a weaker claim than the one the weight checkpoints make, because a healthy range differs by surface: a catalog entry is several short sentences carrying one fact each, and a page arguing a decision is not, so one range applied across the corpus would report the surfaces that are correct. The run therefore states where the numbers came from beside them, and the counts are what a reader compares against.
 
-Measured at `6c273324` across the corpus, 2119 paragraphs reached the floor, 165 sat at or under the spread checkpoint and 50 past the opener checkpoint. Over the 60 files carrying at least ten measured paragraphs the flat rate runs from zero to 21 percent with a median near 6, which is the spread that makes the measure worth reading. Two wiki pages sit at either end of it: a server catalog reports 19 percent, its flattest paragraph five sentences within four words of each other and three of them verbless, while a page arguing where the prose rules came from reports none.
+Measured at `erclx/canon@6c273324` across the corpus, 2119 paragraphs reached the floor, 165 sat at or under the spread checkpoint and 50 past the opener checkpoint. Over the 60 files carrying at least ten measured paragraphs the flat rate runs from zero to 21 percent with a median near 6, which is the spread that makes the measure worth reading. Two wiki pages sit at either end of it: a server catalog reports 19 percent, its flattest paragraph five sentences within four words of each other and three of them verbless, while a page arguing where the prose rules came from reports none.
 
 That reading travels with the command rather than staying here. `BASELINE` in `src/markdown/structure.ts` carries the overall share, the per-file range, and the ten-paragraph floor beneath which a file's own rate says nothing, and the run prints all four in the legend beside the rate it measured. A count with no range beside it reads as a finding, and naming that a healthy range differs by surface states that a range exists rather than what it looks like. This page is toolkit-internal, so a reader running the command in a project that installed no standards would otherwise have two counts and nothing to place them against.
 
@@ -132,7 +132,7 @@ Exit codes are `0` for a completed run with no gating finding, `1` for a refusal
 
 A banned character is a fact rather than a judgment, which is the test that admits it to a gate. What held it back was that gating on day one against a corpus never checked mechanically fails loudly on work nobody has had a chance to fix. The order was to land the verb reporting, measure the corpus once, fix what it finds, and turn the gate on as its own change, and the gate is the last of the four.
 
-Measured at `4b7b13a2` across 444 files with the paragraph checkpoint at 600: 8 word hits, no character or spelling hits, 119 heavy bullets, 221 heavy paragraphs across 86 files, and 41 files carrying a run past the depth checkpoint. Of the paragraphs, 88 fire on weight alone. That is the baseline the corpus sweep started from, and the ban count is the only one of the five a gate should ever read.
+Measured at `erclx/canon@4b7b13a2` across 444 files with the paragraph checkpoint at 600: 8 word hits, no character or spelling hits, 119 heavy bullets, 221 heavy paragraphs across 86 files, and 41 files carrying a run past the depth checkpoint. Of the paragraphs, 88 fire on weight alone. That is the baseline the corpus sweep started from, and the ban count is the only one of the five a gate should ever read.
 
 The ban half reached zero, which was the precondition the gate waited on, and it was re-measured against the same corpus at the moment the gate landed. Three sweep slices then took the structural half, and the corpus reports 1 heavy bullet and 22 heavy paragraphs across 6 files on 2026-08-06, every one on a ground the triage record holds as exempt.
 

package/docs/agents/skills-audit.md

@@ -60,7 +60,7 @@ The check is preventive rather than diagnostic. Every mechanical rule passed acr
 
 ```bash
 canon claude skills drift HEAD~20
-canon claude skills drift 02d7b265 --json
+canon claude skills drift 02d7b265 --json # canon-allow-reference: a copyable command takes a literal git ref, which no qualified form is
 ```
 
 | Option   | Behavior                                                   |

package/docs/agents/superseded.md

@@ -38,7 +38,7 @@ Pass an empty replacement to retire a value outright, as in `canon gov supersede
 
 ## The templated citation
 
-A citation naming a family as a pattern carries neither value. `canon-*` and `internal-<X>` are the two forms this corpus writes, and a literal comparison matches neither, so a rename running the verb once per name reports clean while the family citations stay stale. Two of those on `#1250` had inverted, stating the old prefix as a guard, which left a rule instructing the next session to flag the correct naming as a mismatch.
+A citation naming a family as a pattern carries neither value. `canon-*` and `internal-<X>` are the two forms this corpus writes, and a literal comparison matches neither, so a rename running the verb once per name reports clean while the family citations stay stale. Two of those on `erclx/canon#1250` had inverted, stating the old prefix as a guard, which left a rule instructing the next session to flag the correct naming as a mismatch.
 
 Beside the literal comparison the run matches a family stem, derived from the segment the two values actually differ on, with everything they share carried ahead of it. `toolkit-operator` to `canon-operator` derives `toolkit`, and `canon-cli` to `canon-shell` derives `canon-cli` rather than `canon`, which is what keeps a rename of one folder off every sibling in its family.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.22.1",
+  "version": "4.23.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/gate/measures.ts

@@ -1,6 +1,12 @@
 import { createHash } from 'node:crypto'
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import {
+  isShippedCorpus,
+  REFERENCE_MARKER,
+  referencesIn,
+  SHIPPED_CORPORA,
+} from '@/shipped/references'
 
 export interface CommandResult {
   readonly exitCode: number
@@ -434,6 +440,98 @@ export const standardCriteria: Measure = async (ctx) => {
   }
 }
 
+/**
+ * Every file in the gated corpus, walked from `ctx.root` rather than from the
+ * changed set.
+ *
+ * The stage's `scope` already decides whether the run happens at all, and once
+ * it does the whole corpus is read. A walk keyed on the diff would pass a
+ * branch that moved a reference between two files without changing it, and the
+ * corpus is a few hundred text files, so reading it whole costs the stage
+ * nothing it would notice.
+ *
+ * `dot` is what reaches the seeds, which is half of what `tooling/` ships. Every
+ * seeded `.claude/` tree, `.cspell/` list, and `.husky/` hook sits behind a
+ * dotted segment, so the default scan walks `tooling/` and returns none of the
+ * files a scaffolded project actually receives.
+ */
+function shippedCorpusFiles(root: string): string[] {
+  const files: string[] = []
+
+  for (const corpus of SHIPPED_CORPORA) {
+    const dir = join(root, corpus)
+    if (!existsSync(dir)) continue
+
+    for (const relative of new Bun.Glob('**/*').scanSync({
+      cwd: dir,
+      onlyFiles: true,
+      dot: true,
+    })) {
+      const path = `${corpus}/${relative}`
+      if (isShippedCorpus(path)) files.push(path)
+    }
+  }
+
+  return files.sort()
+}
+
+/**
+ * A pull request number or a commit sha that a reader in a target cannot
+ * resolve, over the seven corpora that reach one.
+ *
+ * Every instance on the trunk was written by a branch that passed review, this
+ * row's own planning session included, so the only instrument before this stage
+ * was a person noticing. That is the argument for gating rather than reporting:
+ * `canon labels audit` already demonstrated that a finding nobody gates on goes
+ * unread until a range happens to include it, and the count here grew from six
+ * to eighteen while a report was the only instrument.
+ *
+ * It is a prose pattern rather than a resolution. Nothing here asks GitHub
+ * whether a number resolves, so a genuinely reachable citation written bare
+ * fails it. That is the intended direction, since the repair is one token and
+ * the alternative is a network read inside `bun run check`.
+ *
+ * The whole set is emitted before the failure returns. A stage halts the run on
+ * its first failing check, so a branch carrying several references would
+ * otherwise see one and repair one.
+ */
+export const shippedReferences: Measure = async (ctx) => {
+  const files = shippedCorpusFiles(ctx.root)
+
+  if (files.length === 0) {
+    return {
+      emissions: [],
+      unmeasured: `No corpus under ${SHIPPED_CORPORA.join(', ')} is present, so no shipped file was read.`,
+    }
+  }
+
+  const found = files.flatMap((file) =>
+    referencesIn(file, readFileSync(join(ctx.root, file), 'utf8')),
+  )
+
+  if (found.length === 0) {
+    return {
+      emissions: [
+        info(
+          `No unresolvable reference across ${files.length} files in ${SHIPPED_CORPORA.length} shipped corpora`,
+        ),
+      ],
+    }
+  }
+
+  return {
+    emissions: found.map((reference) =>
+      warn(
+        `${reference.file}:${reference.line} carries ${reference.text}, a ${reference.kind === 'commit' ? 'commit sha that resolves nowhere' : 'pull request number that resolves elsewhere'} for a reader in a target`,
+      ),
+    ),
+    failure:
+      found.length === 1
+        ? `One reference in the shipped corpora names this repository without saying so. Qualify it as owner/repo#123 or owner/repo@abc1234, or mark the line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`
+        : `${found.length} references in the shipped corpora name this repository without saying so. Qualify each as owner/repo#123 or owner/repo@abc1234, or mark the line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`,
+  }
+}
+
 /**
  * `canon sandbox coverage` moves only when a person runs it, so a scenario added
  * with no expectation ships unnoticed.

package/src/gate/stages.ts

@@ -7,9 +7,11 @@ import {
   recordIdempotence,
   sandboxCoverage,
   seedStandards,
+  shippedReferences,
   standardCriteria,
   unreferencedRules,
 } from '@/gate/measures'
+import { SHIPPED_CORPORA } from '@/shipped/references'
 
 /**
  * One thing a stage does, as an argument vector rather than a shell line.
@@ -354,6 +356,17 @@ export const STAGES: readonly Stage[] = [
     label: 'Markdown bans',
     checks: [{ kind: 'measure', measure: markdownBans }],
   },
+  {
+    // Scoped to the corpora it reads rather than run unconditionally, so a
+    // branch touching only `src/` or `.claude/` skips it and says so. The
+    // measure walks the whole corpus once the scope lets it run, which is what
+    // reaches a reference moved between two files rather than written.
+    id: 'shipped-references',
+    label: 'Shipped references',
+    scope: new RegExp(SHIPPED_CORPORA.map((corpus) => `^${corpus}/`).join('|')),
+    skipped: 'No shipped corpus changed, so no reference was read',
+    checks: [{ kind: 'measure', measure: shippedReferences }],
+  },
   {
     id: 'seed-standards',
     label: 'Seed standards',

package/src/shipped/references.ts

@@ -0,0 +1,160 @@
+import { isMarked } from '@/exempt-marker'
+
+/**
+ * The corpora a target reader reaches, which is the `files` field less `src`.
+ *
+ * The field is the statement of what leaves this repository, and `src/secrets/
+ * shipped.ts` reads it directly for the credential sweep. This list is narrower
+ * on purpose rather than by omission. What decides membership here is whether
+ * anything serves the file to a reader who does not hold this repository: a
+ * skill body loads into a session, a docs page is read through `canon docs`, a
+ * standard through `canon standards`, a rule through a glob match, a snippet
+ * through an `@` expansion, and a seed through an install. A `src/` doc comment
+ * is read by someone working on the toolkit, in this checkout, where every
+ * number resolves.
+ *
+ * That is also what keeps the check a prose pattern rather than a parser.
+ * `src/design/base.css` and `src/design/tokens.ts` carry sixteen values shaped
+ * `#191512`, which no width or boundary rule separates from a pull request
+ * number, so telling them apart would need the line's syntactic position.
+ *
+ * `claude/standards` and `claude/snippets` are symlinks into two of the roots
+ * below, and a walk that followed them would read those two corpora twice and
+ * report every finding in them under two paths. Nothing is lost by not
+ * following, since both are corpora here in their own right.
+ */
+export const SHIPPED_CORPORA = [
+  'claude',
+  'docs',
+  'governance',
+  'scripts',
+  'snippets',
+  'standards',
+  'tooling',
+] as const
+
+/**
+ * Trees inside a corpus above that no target receives, matching the negations
+ * the `files` field already makes. A number under either names something its
+ * only reader can already resolve.
+ */
+export const SHIPPED_EXCLUSIONS = [
+  /^scripts\/sandbox\//,
+  /^scripts\/eval\//,
+] as const
+
+/** Whether a repository-relative path sits in the gated corpus. */
+export function isShippedCorpus(path: string): boolean {
+  if (SHIPPED_EXCLUSIONS.some((pattern) => pattern.test(path))) return false
+  if (path.endsWith('.test.ts')) return false
+
+  return SHIPPED_CORPORA.some((corpus) => path.startsWith(`${corpus}/`))
+}
+
+export const REFERENCE_MARKER = 'canon-allow-reference'
+
+/**
+ * A pull request number a target reader resolves against their own repository.
+ *
+ * The leading boundary is what excludes the repair form by construction rather
+ * than by exemption, and that is load bearing. A lookbehind rejecting a word
+ * character before `#` never matches `erclx/canon#1299`, so a qualified
+ * reference passes with no marker, and `claude/skills/claude-worktree/SKILL.md`
+ * already ships `anthropics/claude-code#58345` in exactly that form.
+ *
+ * The trailing boundary is what the first shape of this pattern lacked, and it
+ * costs a live finding to omit. `governance/rules/framework/250-tailwind.md`
+ * writes `bg-[#316ff6]`, a Tailwind arbitrary hex color, which an unbounded
+ * `#[0-9]+` reads as pull request 316. Requiring a non-word character after the
+ * digits rejects it and rejects nothing real, since a citation is always
+ * followed by a space, a backtick, or punctuation.
+ *
+ * Any digit run counts. This repository is past `#1300` so a four-digit pattern
+ * reads as complete, and `#1`, `#12`, and `#123` all resolve to the wrong thing
+ * in a target just as surely.
+ */
+const PULL_REQUEST = /(?<![0-9A-Za-z_])#([0-9]+)(?![0-9A-Za-z_])/g
+
+/**
+ * A commit sha, which is the worse half: it resolves to nothing anywhere rather
+ * than to the wrong pull request.
+ *
+ * Seven characters is git's own short-sha floor and forty is a full one. No
+ * rule here requires a letter, because an all-digit sha is real:
+ * `orchestrator-poll.md` cites `5653721`, and the first pass at this classifier
+ * required a letter and lost it.
+ *
+ * The lookbehind rejects `@` and `/` so the repair form `erclx/canon@5653721`
+ * passes the check that told the author to write it, and rejects `#` so a hex
+ * color long enough to reach the floor is not reported twice under two names.
+ *
+ * Three false-positive classes survive by construction and the marker is what
+ * answers each. An all-digit hex color is indistinguishable from a pull request
+ * number. A seven-letter word spelled from `a` through `f` alone, such as
+ * `defaced`, reads as a sha. Neither occurs anywhere in the corpus today.
+ *
+ * The third is the one a later author meets. Admitting an all-digit sha admits
+ * every run of seven or more decimal digits with it, so a date written without
+ * separators, a large count, or a float artifact reads as a commit reference.
+ * The corpus carries no instance and that is the exclusions rather than luck:
+ * twelve such runs sit under the seven roots, eleven of them under
+ * `scripts/sandbox/`, `scripts/eval/`, or a test file, and the twelfth is the
+ * genuine sha in `orchestrator-poll.md`. Write a seven-digit measurement into a
+ * shipped page and the push fails on it, which the marker answers and no
+ * narrowing can, since requiring a letter loses the all-digit sha above.
+ */
+const COMMIT_SHA = /(?<![0-9A-Za-z_@/#])([0-9a-f]{7,40})(?![0-9A-Za-z_])/g
+
+export interface ShippedReference {
+  readonly file: string
+  /** One-based, matching the `file:line` form a reader clicks. */
+  readonly line: number
+  readonly kind: 'pull-request' | 'commit'
+  /** The reference as written, so a report names the token to qualify. */
+  readonly text: string
+}
+
+/**
+ * Every reference in one shipped file that no marker mutes.
+ *
+ * The corpus walk is deliberately absent, which lets the shape be tested
+ * against a string rather than against a fixture. That is the seam
+ * `headingCitationsIn` draws in `src/claude/skills-headings.ts` and `citationsIn`
+ * draws in `skills-reach.ts`.
+ *
+ * The unit is the match rather than the line, unlike those two, because one
+ * line here can carry three separate tokens each needing its own repair and a
+ * report naming the line once leaves two of them unsaid.
+ *
+ * `isMarked` reads the line itself and the line above and stops there, so the
+ * marker mutes a line and nothing narrower. A real citation later added beside
+ * a marked illustration ships unreported.
+ */
+export function referencesIn(file: string, text: string): ShippedReference[] {
+  const lines = text.split('\n')
+  const references: ShippedReference[] = []
+
+  for (const [index, line] of lines.entries()) {
+    if (isMarked(lines, index, REFERENCE_MARKER)) continue
+
+    for (const match of line.matchAll(PULL_REQUEST)) {
+      references.push({
+        file,
+        line: index + 1,
+        kind: 'pull-request',
+        text: match[0],
+      })
+    }
+
+    for (const match of line.matchAll(COMMIT_SHA)) {
+      references.push({
+        file,
+        line: index + 1,
+        kind: 'commit',
+        text: match[0],
+      })
+    }
+  }
+
+  return references
+}

package/standards/diagrams.md

@@ -37,7 +37,7 @@ An entry that fails these is non-conforming regardless of whether it satisfies e
 - `title` (required): sentence case, names what the entry answers (`System context`, `Request flow`), not what it draws.
 - `description` (required): one line on which question the entry settles and which source signal drives it.
 - `category` (required): the diagram kind, one of the five in Entry kinds. It is the grouping field `canon indexes regen` renders headings from.
-- `verified` (required): the short commit SHA an entry was last checked against and the ISO date of that check, separated by a space (`73e9a3f8 2026-08-02`). A stub nobody has drawn yet carries the literal `TODO: never verified` instead, which is the one other accepted value.
+- `verified` (required): the short commit SHA an entry was last checked against and the ISO date of that check, separated by a space (`73e9a3f8 2026-08-02`). A stub nobody has drawn yet carries the literal `TODO: never verified` instead, which is the one other accepted value. <!-- canon-allow-reference: illustrates the field's two-token format, which a qualified sha would misstate -->
 - `stale` (optional): one line naming what changed under the entry since that check. Nothing writes it on its own, so it sits on an entry because a reader put it there and is absent everywhere else.
 
 The first three feed `.canon/diagrams/index.md` when regenerated. The catalog sorts categories alphabetically rather than in narrative order, so an entry cannot rely on its position to introduce another. Each entry names its own starting point, and the catalog's subtitle routes a first-time reader to the system context entry.

package/standards/publish.md

@@ -60,7 +60,11 @@ Removing the link before a merge does not substitute for never writing it. One b
 
 A number referring to a pull request or an issue takes the form its destination renders. Write it bare where the destination auto-links it, and in backticks where it does not. Both spellings are correct, each in one place, so a reference moved from one destination to the other is rewritten rather than copied.
 
-Text published to a remote is the auto-linking half: a pull request body, an issue body, a comment on either, and a commit message. Write `#123` there, and `owner/repo#123` where the reference crosses repositories, which the same auto-linking reaches. A markdown file browsed from the repository tree is the other half, where neither spelling links and the backticked one marks the number as an identifier.
+Text published to a remote is the auto-linking half: a pull request body, an issue body, a comment on either, and a commit message. Write `#123` there, and `owner/repo#123` where the reference crosses repositories, which the same auto-linking reaches. A markdown file browsed from the repository tree is the other half, where neither spelling links and the backticked one marks the number as an identifier. <!-- canon-allow-reference: the two spellings this section defines, which a qualified form would destroy -->
+
+Content that installs into another repository is the third destination, and there the qualified form is required rather than chosen. A skill body loads from a plugin cache, a docs page is read through `canon docs`, and a standard through `canon standards`, so the reader holds their own repository rather than the one the number belongs to. A bare number resolves against theirs and reaches something else, and a bare sha resolves nowhere at all.
+
+Write `owner/repo#123` and `owner/repo@abc1234` across every such surface. `canon gate run` fails a push on a bare reference there, and a line whose bare form is the point carries `canon-allow-reference: <reason>` on itself or on the line above.
 
 A commit message takes the bare form even though it is also read through the log, where nothing links. The remote is what the form is chosen for, since a reader in the log loses only a link that plain text never carried.