@erclx/canon 4.37.1 → 4.39.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.37.1",
+  "version": "4.39.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-design-extract/SKILL.md

@@ -35,7 +35,7 @@ Read these on both paths, skipping any that do not exist:
 - `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: word, punctuation, and formatting constraints
 - The `write-human` skill: tone and sentence construction constraints
 
-On the source path, also read the UI surfaces matched in Step 1 plus any `docs/agents/output-shape.md` and `docs/index.md` the project itself carries, for output shape or framing rules already documented. Those two are the toolkit's own spelling, so a project keeping its framing rules elsewhere is read there instead.
+On the source path, also read the UI surfaces matched in Step 1 plus `canon docs output-shape` and `canon docs index`, for output shape or framing rules already documented in the toolkit's own reference. Skip either that fails to resolve, since a project keeping its framing rules elsewhere is read there instead.
 
 On the greenfield path, also read `.claude/ARCHITECTURE.md` for platform, tech stack, and surface type. Do not scan `src/`, stylesheets, or UI modules. Step 1 already established they hold nothing.
 

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

@@ -105,7 +105,7 @@ Read each changed file in scope. Skip deleted files. Run reads in parallel.
 
 ## Step 3: review
 
-Review the diff and files for the same axes as `claude-review` (bugs, edge cases, error handling, logic flaws, security, rule violations), then add the three lenses a self-review structurally cannot apply:
+Review the diff and files for the same axes as `claude-review` (bugs, edge cases, error handling, logic flaws, security, rule violations, checkout assumptions in a shipped file), then add the three lenses a self-review structurally cannot apply:
 
 - Integration: does this fit the board's order, the shared wiring seam, and any sibling PR in flight?
 - Contract: does a contract downstream features depend on land correctly, and should the plan itself be questioned?

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

@@ -66,6 +66,7 @@ Review the full diff and changed file contents for:
 3. Logic flaws that will cause problems when the code is extended
 4. Security issues relevant to the project context
 5. Violations of rules from `.claude/rules/` that apply to the changed files
+6. When the diff touches a file this project ships to a target holding none of its own history: a repository-relative path, a phase label naming a gitignored board, a same-repository pull request or commit reference, or a layout, stack, or config-path claim true of this checkout but stated as if it were general
 
 Use `CLAUDE.md`, `.claude/REQUIREMENTS.md`, `.claude/ARCHITECTURE.md`, and the auto-loaded `.claude/rules/` as project context to inform what is intentional vs problematic. Do not fix, rewrite, or suggest refactors outside the scope of a finding.
 

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

@@ -31,7 +31,7 @@ Accept work whose origin is the conversation itself only when the user says so e
 
 List the existing filenames in `.canon/tasks/` and read `index.md` for what each holds. Propose the next label from what is already on the board, and say which neighbors it sits between.
 
-Do not derive the label from a version file. `${CLAUDE_SKILL_DIR}/../../standards/versioning.md` permits free renumbering, so the board is the only surface that knows what a label currently means. Pad the phase to two digits in the filename, since index entries sort by filename alone and a bare `v9.0` sorts after `v15.0`.
+Do not derive the label from a version file. `${CLAUDE_SKILL_DIR}/../../standards/versioning.md` permits free renumbering, so the board is the only surface that knows what a label currently means. Pad the phase to two digits in the filename, since index entries sort by filename alone and a bare `v9.0` sorts after `v15.0`. <!-- canon-allow-reference: illustrates the padding rule's own sort collision, not a citation of a real task -->
 
 ### Step 3: write the file
 

package/claude/skills/setup-indexes/SKILL.md

@@ -7,7 +7,7 @@ description: Bootstraps the toolkit's `index.md` system in a target project. Sca
 
 Adds the index.md system to a project that does not have it. Operates in the active Claude session: Claude reads files, drafts frontmatter, confirms with the user, and writes. The CLI handles validation and regeneration only.
 
-Read `.claude/context/indexes.md` from the toolkit if context on the system is needed before scanning.
+Read `canon docs indexes` from the toolkit if context on the system is needed before scanning.
 
 ## Scope
 
@@ -147,7 +147,4 @@ Replace bracketed values with the values from this run. Drop the "Folders bootst
 
 ## Reference
 
-Both pages sit in the toolkit and install nowhere, so a target reads them there rather than in its own tree.
-
-- The toolkit's `.claude/context/indexes.md`: system rationale, frontmatter contract, when to adopt
-- The toolkit's `docs/agents/indexes.md`: `canon indexes regen` flags, exit codes, JSON shape
+- Run `canon docs indexes` for `canon indexes regen` flags, exit codes, and JSON shape. It resolves from the toolkit rather than from the target's own tree.

package/docs/agents/tasks.md

@@ -12,7 +12,7 @@ description: Selecting a shipped task by stem or pull request, recording a numbe
 Name the task by its filename stem, or by the pull request it carries:
 
 ```bash
-canon tasks archive v28.1-trigger-escalation
+canon tasks archive v28.1-trigger-escalation # canon-allow-reference: illustrates the stem-selection form, not a citation of a real task
 canon tasks archive --pull-request 673 --json
 ```
 
@@ -66,7 +66,7 @@ Branch on `reason` rather than on the exit code, which is the rule the archive s
 A `live` location with an empty `citedBy` is the sweep to run. One whose `citedBy` names a sibling is a plan several tasks share, which the sweep leaves alone and the archive gate lets through.
 
 ```bash
-canon tasks plan-citations v28.1-trigger-escalation --json | jq -r '.location'
+canon tasks plan-citations v28.1-trigger-escalation --json | jq -r '.location' # canon-allow-reference: illustrates the stem-selection form, not a citation of a real task
 ```
 
 ## Plan answers
@@ -111,7 +111,7 @@ canon tasks plan-answers dispatch-answer-gate --json | jq -r '.launchable'
 Name the task by its filename stem, or by the plan its `Plan:` line points at:
 
 ```bash
-canon tasks pull-request 673 v28.1-trigger-escalation
+canon tasks pull-request 673 v28.1-trigger-escalation # canon-allow-reference: illustrates the stem-selection form, not a citation of a real task
 canon tasks pull-request 673 --plan worktree-scratch-routing --json
 ```
 
@@ -132,7 +132,7 @@ A malformed argument refuses as `bad-input` instead, which sits outside that set
 `canon tasks outcome` marks outcomes `[x]` on a task by their position in its outcome list, counting every checkbox in file order from 1.
 
 ```bash
-canon tasks outcome v28.1-trigger-escalation --close 1 --close 3
+canon tasks outcome v28.1-trigger-escalation --close 1 --close 3 # canon-allow-reference: illustrates the stem-selection form, not a citation of a real task
 canon tasks outcome --plan worktree-scratch-routing --close 2 --json
 ```
 
@@ -188,7 +188,7 @@ The comparative phrase is bounded the same way and for the same reason. A closed
 
 The collision check is the one a person cannot run by eye. Paths come from the backticked spans in the Touches column, a span naming no file is dropped, and a directory collides with any file beneath it. A `## Run now` row whose column parses to nothing is reported rather than skipped, since a row stating no file set makes a claim nothing can check.
 
-Where a directory holds the other row's file, the finding names the row that claimed it, reading `both touch src/tasks, which v2.0-second claims as a folder.` The shared strings alone leave an over-broad cell and a genuine overlap identical, which is how a correct report was once read as the verb comparing folders rather than files.
+Where a directory holds the other row's file, the finding names the row that claimed it, reading `both touch src/tasks, which v2.0-second claims as a folder.` The shared strings alone leave an over-broad cell and a genuine overlap identical, which is how a correct report was once read as the verb comparing folders rather than files. <!-- canon-allow-reference: illustrates the finding's own sentence shape, not a citation of a real task -->
 
 The blocker check re-takes a measurement the board records once and never repeats. Two of the five blocker kinds put a fact on disk: a dependency is settled by the cited task being archived or by its work reaching the trunk, and a collision is settled by nothing under `## Run now` still holding the file the cell cites.
 
@@ -207,7 +207,7 @@ The other three kinds rest on a person's judgment, so a row neither half reached
   "untested": [
     {
       "group": "Needs a plan",
-      "subject": "v50.6-a-standard-no-skill-reads",
+      "subject": "v50.6-a-standard-no-skill-reads", // canon-allow-reference: shows the subject field's real vXX.Y-slug shape, not a citation of a real task
       "message": "..."
     }
   ]
@@ -223,7 +223,7 @@ A `## Run now` row whose Touches column names a bare folder lands in a third arr
   "claims": [
     {
       "group": "Run now",
-      "subject": "v1.0-first",
+      "subject": "v1.0-first", // canon-allow-reference: shows the subject field's real vXX.Y-slug shape, not a citation of a real task
       "message": "claims the whole src/tasks folder, so it collides with every row written under it."
     }
   ]

package/package.json

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

package/scripts/docs/list.sh

@@ -88,7 +88,7 @@ collect_docs() {
 # It stops at the folder where listTopics goes on to name each sub-area file.
 # This is the downstream catalog and that one answers what a caller could have
 # typed, so a reachable name absent here is the same divergence the internal
-# topics already carry, and docs/agents/docs.md states it.
+# topics already carry, and `canon docs docs` states it.
 collect_context() {
   local file name description
   {

package/src/commands/migrate.ts

@@ -263,6 +263,15 @@ function reportRecords(plan: RecordsPlan, records: number): void {
   if (plan.excluded.length > 0) {
     logInfo(`${plural(plan.excluded.length, 'file')} excluded from the sweep.`)
   }
+
+  // A list rather than a count. A coupled file is the handful an operator has
+  // to open by hand, and a bare count gives them nothing to act on.
+  if (plan.coupled.length > 0) {
+    logInfo(
+      `${plural(plan.coupled.length, 'file')} couple to an excluded path:`,
+    )
+    for (const path of plan.coupled) logInfo(`  ${path}`)
+  }
 }
 
 function toRecordsRecord(
@@ -279,6 +288,7 @@ function toRecordsRecord(
     rewritten: plan.rewritten,
     kept: plan.kept,
     excluded: plan.excluded.length,
+    coupled: plan.coupled,
     records,
     paths: plan.entries.map((entry) => ({
       path: entry.path,

package/src/gate/measures.ts

@@ -13,6 +13,7 @@ import {
   REFERENCE_MARKER,
   referencesIn,
   SHIPPED_CORPORA,
+  type ShippedReference,
 } from '@/shipped/references'
 
 export interface CommandResult {
@@ -482,9 +483,28 @@ function shippedCorpusFiles(root: string): string[] {
   return files.sort()
 }
 
+/** The clause `shippedReferences` appends after naming a reference's text. */
+function describeShippedReference(reference: ShippedReference): string {
+  if (reference.selfCitation) {
+    return "a citation of this repository's own history that resolves for no reader outside it, qualified or not"
+  }
+
+  switch (reference.kind) {
+    case 'commit':
+      return 'a commit sha that resolves nowhere for a reader in a target'
+    case 'pull-request':
+      return 'a pull request number that resolves elsewhere for a reader in a target'
+    case 'docs-path':
+      return 'a path into this repository that a registry install never carries'
+    case 'phase-label':
+      return 'a phase label that names a board no target holds'
+  }
+}
+
 /**
- * A pull request number or a commit sha that a reader in a target cannot
- * resolve, over the seven corpora that reach one.
+ * A pull request number, a commit sha, a docs-path citation, or a phase
+ * label 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
@@ -513,7 +533,7 @@ export const shippedReferences: Measure = async (ctx) => {
   }
 
   const found = files.flatMap((file) =>
-    referencesIn(file, readFileSync(join(ctx.root, file), 'utf8')),
+    referencesIn(file, readFileSync(join(ctx.root, file), 'utf8'), ctx.root),
   )
 
   if (found.length === 0) {
@@ -529,15 +549,13 @@ export const shippedReferences: Measure = async (ctx) => {
   return {
     emissions: found.map((reference) =>
       warn(
-        reference.selfCitation
-          ? `${reference.file}:${reference.line} carries ${reference.text}, a citation of this repository's own history that resolves for no reader outside it, qualified or not`
-          : `${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`,
+        `${reference.file}:${reference.line} carries ${reference.text}, ${describeShippedReference(reference)}`,
       ),
     ),
     failure:
       found.length === 1
-        ? `One reference in the shipped corpora resolves wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, state a same-repository citation as a fact instead and relocate the evidence to the owning .claude/context/ entry, or mark the line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`
-        : `${found.length} references in the shipped corpora resolve wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, state a same-repository citation as a fact instead and relocate the evidence to the owning .claude/context/ entry, or mark each line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`,
+        ? `One reference in the shipped corpora resolves wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning .claude/context/ entry, or mark the line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`
+        : `${found.length} references in the shipped corpora resolve wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning .claude/context/ entry, or mark each line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`,
   }
 }
 

package/src/migrate/records.ts

@@ -91,6 +91,13 @@ function escape(value: string): string {
  * pair into two copies of the new one and shellcheck reports a pattern that can
  * never match. The guard then stops firing in a project the move has not
  * reached, which is silent: the index goes stale while every save succeeds.
+ *
+ * A file outside this list can still couple to one inside it, naming an
+ * excluded path as plain text while it also carries a live citation of its
+ * own, which `referencesExcluded` reports separately below. Widening this list
+ * or `EXCLUDED_SUFFIXES` to catch that case would mean guessing at a naming
+ * convention no project here declares, where the coupling check instead reads
+ * what the file's own text already says.
  */
 const EXCLUDED_PREFIXES: readonly string[] = [
   'src/migrate/',
@@ -109,6 +116,25 @@ export function isExcludedPath(path: string): boolean {
   return EXCLUDED_SUFFIXES.some((suffix) => path.endsWith(suffix))
 }
 
+/**
+ * Whether `text` names an `EXCLUDED_PREFIXES` or `EXCLUDED_PATHS` entry as
+ * literal substring text, which is how a rewritten file can couple to one this
+ * module leaves alone: a citation gets rewritten clean while a line a few away
+ * still spells the excluded path it was testing against.
+ *
+ * `EXCLUDED_SUFFIXES` plays no part here, since a suffix names a file's own
+ * shape rather than text its content could quote. The one gap this cannot
+ * close is a file that names the excluded surface by description rather than
+ * by path, such as "the exemption hook" rather than `.claude/hooks/`, which is
+ * the same limit `isExcludedPath` already carries for content it cannot parse.
+ */
+export function referencesExcluded(text: string): boolean {
+  return (
+    EXCLUDED_PATHS.some((path) => text.includes(path)) ||
+    EXCLUDED_PREFIXES.some((prefix) => text.includes(prefix))
+  )
+}
+
 /**
  * The roots holding nothing but records, so a path under one is a record
  * whatever it is named.
@@ -299,6 +325,7 @@ export interface RecordsPlan {
   readonly collisions: readonly string[]
   readonly entries: readonly CitationEntry[]
   readonly excluded: readonly string[]
+  readonly coupled: readonly string[]
   readonly rewritten: number
   readonly kept: number
 }
@@ -318,6 +345,7 @@ export function planRecordsMove(
   const moves = planFolderMoves(root)
   const entries: CitationEntry[] = []
   const excluded: string[] = []
+  const coupled: string[] = []
   let kept = 0
 
   for (const source of sources) {
@@ -339,6 +367,8 @@ export function planRecordsMove(
     kept += counts.kept
     if (counts.rewritten === 0) continue
 
+    if (referencesExcluded(source.text)) coupled.push(source.path)
+
     entries.push({
       path: source.path,
       text: rewriteText(source.text),
@@ -352,6 +382,7 @@ export function planRecordsMove(
     collisions: collisions(root, moves),
     entries,
     excluded,
+    coupled,
     rewritten: entries.reduce((sum, entry) => sum + entry.rewritten, 0),
     kept,
   }

package/src/shipped/references.ts

@@ -1,3 +1,5 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
 import { isMarked } from '@/exempt-marker'
 
 /**
@@ -125,11 +127,53 @@ const COMMIT_SHA = /(?<![0-9A-Za-z_@/#])([0-9a-f]{7,40})(?![0-9A-Za-z_])/g
 const SAME_REPOSITORY =
   /(?<![0-9A-Za-z_/])erclx\/canon(#[0-9]+|@[0-9a-f]{7,40})(?![0-9A-Za-z_])/g
 
+/**
+ * A repository-relative path under `docs/`, reported only where `isResolvable`
+ * confirms it resolves against this checkout.
+ *
+ * Shape alone cannot separate a citation of this repository's own reference
+ * corpus from an illustration naming a target's own tree, since both are
+ * `docs/...md` tokens: `docs/agents/tasks.md` and `docs/retry.md` read
+ * identically to a pattern with no filesystem behind it. Of 124 such tokens
+ * across the shipped corpora, four distinct paths resolved here and the rest
+ * named a target's own tree, measured on 2026-09-03. Resolving against `root`
+ * is what turns that 124-hit pattern into the four-hit gate.
+ *
+ * `.claude/context/` carries no equivalent pattern. The same resolution test
+ * cannot separate a path every scaffolded project holds, such as
+ * `.claude/context/index.md`, from this repository's own domain entry, such
+ * as `.claude/context/indexes.md`, since both resolve here and only the
+ * second is a defect. That is a semantic read no pattern makes, so it stays
+ * with the rule and the review checklist rather than joining this reader.
+ */
+const DOCS_PATH = /(?<![\w./-])docs\/[^\s`)\]]*\.md\b/g
+
+/**
+ * A phase-label-shaped token: exactly two numeric groups, with a negative
+ * lookahead rejecting a third.
+ *
+ * This does not reuse `VERSION_TOKEN` from `src/labels/phase.ts`, which
+ * admits one or two decimal groups and therefore matches a three-group
+ * semver tag as readily as a two-group phase label. That is the right shape
+ * there, since `scanPhaseLabels` sorts the two namespaces apart by asking
+ * whether the pull request carrying the token is release-please's own, a
+ * signal this reader has no equivalent of: a shipped-corpus file carries no
+ * pull request to test. Shape is the only discriminator available here, and
+ * every phase label this board issues carries exactly two groups while every
+ * semver tag carries three, so narrowing to two removes the semver class by
+ * construction rather than by a marker standing in for the missing signal.
+ *
+ * A target holds no board to resolve a label against, so a bare instance
+ * here is unresolvable the same way a same-repository citation is, and is
+ * muted the same way when it names the label format rather than a real row.
+ */
+const PHASE_LABEL = /\bv\d+\.\d+(?!\.\d)\b/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'
+  readonly kind: 'pull-request' | 'commit' | 'docs-path' | 'phase-label'
   /** The reference as written, so a report names the token to qualify. */
   readonly text: string
   /**
@@ -140,13 +184,36 @@ export interface ShippedReference {
   readonly selfCitation?: true
 }
 
+/**
+ * Whether a `DOCS_PATH` match names a real file in this checkout.
+ *
+ * `file` gates the `docs/` corpus out by the caller's own location rather
+ * than by a pattern exemption: a citation from inside `docs/` is read
+ * together with the rest of that corpus through the same `canon docs`
+ * resolution, which is a weaker claim than one from a skill body with no
+ * `docs/` sibling at all.
+ */
+function isDocsPathResolvable(
+  file: string,
+  path: string,
+  root: string,
+): boolean {
+  if (file.startsWith('docs/')) return false
+  return existsSync(join(root, path))
+}
+
 /**
  * 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
+ * The corpus walk is deliberately absent, which lets most of 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`.
+ * draws in `skills-reach.ts`. `DOCS_PATH` is the one pattern that still needs
+ * a filesystem, since resolving against this checkout is the only thing that
+ * separates its two readings, so it takes `root` as the one caller-supplied
+ * exception to that rule. `root` is required rather than defaulted, since a
+ * caller that dropped it silently would report zero docs-path findings
+ * rather than raising, which is the wrong failure direction for a gate.
  *
  * 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
@@ -156,7 +223,11 @@ export interface ShippedReference {
  * 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[] {
+export function referencesIn(
+  file: string,
+  text: string,
+  root: string,
+): ShippedReference[] {
   const lines = text.split('\n')
   const references: ShippedReference[] = []
 
@@ -190,6 +261,25 @@ export function referencesIn(file: string, text: string): ShippedReference[] {
         selfCitation: true,
       })
     }
+
+    for (const match of line.matchAll(DOCS_PATH)) {
+      if (!isDocsPathResolvable(file, match[0], root)) continue
+      references.push({
+        file,
+        line: index + 1,
+        kind: 'docs-path',
+        text: match[0],
+      })
+    }
+
+    for (const match of line.matchAll(PHASE_LABEL)) {
+      references.push({
+        file,
+        line: index + 1,
+        kind: 'phase-label',
+        text: match[0],
+      })
+    }
   }
 
   return references

package/standards/tasks.md

@@ -31,8 +31,8 @@ Does not govern:
 ├── priority.md           ← hand-maintained execution order
 ├── backlog.md            ← unordered, what is not being scheduled
 ├── session-<slug>.md     ← optional, what a compaction is about to destroy
-├── v09.0-sync-paths.md
-└── v13.0-toolkit-drift.md
+├── v09.0-sync-paths.md      # canon-allow-reference: illustrates the vXX.Y-slug filename this section defines
+└── v13.0-toolkit-drift.md   # canon-allow-reference: illustrates the vXX.Y-slug filename this section defines
 ```
 
 One file per task is what keeps the board safe under parallel sessions. Two sessions working different tasks never write the same file, which matters because a gitignored board has no history to recover a clobbered write from.
@@ -137,13 +137,13 @@ Add no fourth readiness group in place of this file. The three group names are t
 
 ## Validation
 
-`canon tasks validate` reads the board against the tree, and what it checks, what it refuses on, and what it reports are at `docs/agents/tasks.md`. Run it when the readiness claim is made rather than on a schedule, since the board is gitignored per-machine scratch and no shared moment exists to hang it on.
+`canon tasks validate` reads the board against the tree, and what it checks, what it refuses on, and what it reports are at `canon docs tasks`. Run it when the readiness claim is made rather than on a schedule, since the board is gitignored per-machine scratch and no shared moment exists to hang it on.
 
 ## Filenames
 
 `vXX.Y-<slug>.md`, where the version is the phase label zero-padded to two digits and the slug is kebab-case.
 
-Padding is load-bearing. Index entries sort by filename and nothing else, so a bare `v9.0` sorts after `v15.0` and the catalog reads out of board order. `standards/versioning.md` governs the label itself and permits free renumbering, so expect the occasional rename. Nothing points at a task filename, since a `Plan:` line runs from task to plan rather than the reverse.
+Padding is load-bearing. Index entries sort by filename and nothing else, so a bare `v9.0` sorts after `v15.0` and the catalog reads out of board order. `standards/versioning.md` governs the label itself and permits free renumbering, so expect the occasional rename. Nothing points at a task filename, since a `Plan:` line runs from task to plan rather than the reverse. <!-- canon-allow-reference: illustrates the padding rule's own sort collision, not a citation of a real task -->
 
 ## Frontmatter
 
@@ -151,7 +151,7 @@ Every task file carries both fields. The index walker fails the whole folder whe
 
 ```yaml
 ---
-title: 'v13.0: Detect and close toolkit drift in target projects'
+title: 'v13.0: Detect and close toolkit drift in target projects' # canon-allow-reference: illustrates the quoted title shape, not a citation of a real task
 description: Record what a target installed and report the delta against the toolkit
 ---
 ```
@@ -245,7 +245,7 @@ The line is what lets a merge close its own task. Every merge on `main` is a squ
 
 ## Archiving
 
-Never delete a task file. A shipped task moves to `.canon/tasks/archive/` under its own name, and the live index regenerates without it. `canon tasks archive` owns that move, and what it does and what it refuses on are at `docs/agents/tasks.md`.
+Never delete a task file. A shipped task moves to `.canon/tasks/archive/` under its own name, and the live index regenerates without it. `canon tasks archive` owns that move, and what it does and what it refuses on are at `canon docs tasks`.
 
 The archive nests inside `.canon/tasks/` rather than sitting beside it as a flat `.claude/task-archive/`. Nesting is what lets a reader tell the two shapes apart on sight: the flat sibling is what a binary predating this convention still writes, so meeting one names an older checkout rather than a second archive to reconcile against this one.
 

package/standards/versioning.md

@@ -25,7 +25,7 @@ Internal coordination vocabulary used in the task board and chat.
 
 - Format is project-specific.
 - Used to order work and disambiguate streams during planning.
-- Re-numbers freely as scope shifts. Inserting a half-step between two existing labels (a `v1.5` between `v1` and `v2`) is fine.
+- Re-numbers freely as scope shifts. Inserting a half-step between two existing labels (a `v1.5` between `v1` and `v2`) is fine. <!-- canon-allow-reference: illustrates the renumbering rule's own format, not a citation of a real row -->
 - Does not have to map to any external release.
 
 ## Semver tags

package/tooling/base/reference.md

@@ -4,7 +4,7 @@
 
 The base layer covers every project the toolkit scaffolds, whatever language sits on top. It ships formatting, spelling, shell linting, conventional commits, git hooks, CI, and one maintenance script. Every other stack extends it, so a decision made here is one every stack inherits.
 
-A repository with several language roots layers this stack once at the root and skips it per subtree, since git honors only one `core.hooksPath` and a re-dropped husky silently breaks. `docs/target-projects.md` carries the recipe.
+A repository with several language roots layers this stack once at the root and skips it per subtree, since git honors only one `core.hooksPath` and a re-dropped husky silently breaks. `canon docs target-projects` carries the recipe.
 
 ## What ships as golden configs
 
@@ -97,4 +97,4 @@ Sticky negative knowledge. Do not relearn.
 
 `bun run check` repairs a checkout rather than gating one. It runs `format` first to auto-fix drifted code, then asserts only what the formatters could not fix. The pull request workflow calls `check:format`, `check:spell`, and `check:shell` directly, and those three are the gate.
 
-`scripts/verify.sh`'s `Markdown bans` stage is the exception: it gates rather than repairs. It runs `canon markdown audit` over every tracked markdown file except `CHANGELOG.md`, since a generated changelog carries commit subjects nobody wrote against the ban set, and exits `2` on a finding or `3` on a shipped-empty ban set, failing `bun run check` and the `pre-push` hook that calls it. A refusal to measure exits `1` and is logged as a skip rather than a failure, as does a corpus with no file left to check once `CHANGELOG.md` is set aside. The stage needs `canon` on PATH. `docs/target-projects.md` names the install command. Without it, the stage is skipped and logged, and coverage falls back to the three checks above.
+`scripts/verify.sh`'s `Markdown bans` stage is the exception: it gates rather than repairs. It runs `canon markdown audit` over every tracked markdown file except `CHANGELOG.md`, since a generated changelog carries commit subjects nobody wrote against the ban set, and exits `2` on a finding or `3` on a shipped-empty ban set, failing `bun run check` and the `pre-push` hook that calls it. A refusal to measure exits `1` and is logged as a skip rather than a failure, as does a corpus with no file left to check once `CHANGELOG.md` is set aside. The stage needs `canon` on PATH. `canon docs target-projects` names the install command. Without it, the stage is skipped and logged, and coverage falls back to the three checks above.