@erclx/canon 4.122.0 → 4.124.0

package/docs/workflow/skill-map.md

@@ -0,0 +1,148 @@
+---
+title: Skill map
+description: When to reach for each plugin skill, grouped by the moment a project meets it
+category: Workflow
+---
+
+# Skill map
+
+Groups run in the order a project meets them, so a reader at a known point scans to that group and reads across. The set reconciles the scenarios in [AI workflow](ai-workflow.md) with the lifecycle [target projects](../target-projects.md) describes, rather than inventing a third vocabulary beside those two, so a group name matches neither source exactly and every moment either one names has a group. Each row says when to reach for the skill. What it does is the skill's own description.
+
+This page is the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row here. A skill serving two moments sits at the earlier one, and a mention on any other page is prose rather than routing.
+
+## Set up a project
+
+| Skill                  | When to use                                                                                            |
+| ---------------------- | ------------------------------------------------------------------------------------------------------ |
+| `canon:target-setup`   | On a fresh scaffold, to detect the stack and run the install chain, or to reach one phase of it alone  |
+| `canon:canon-operator` | On a project that already exists, to read what it carries before an install is picked                  |
+| `canon:sketch-design`  | Before `design-extract`'s greenfield path, to trace a design direction from reference images or URLs   |
+| `canon:design-extract` | Before the first UI feature, to draft `canon/DESIGN.md`                                                |
+| `canon:draft-diagram`  | Once the architecture is written, to draft per-kind entries under `.canon/diagrams/`                   |
+| `canon:repo-metadata`  | When the GitHub About text, homepage, or topics may have drifted, to reconcile them against the README |
+
+## Decide what to build
+
+| Skill                      | When to use                                                                       |
+| -------------------------- | --------------------------------------------------------------------------------- |
+| `canon:plan-intake`        | When the input is a pile of findings rather than one feature                      |
+| `canon:plan-intake-answer` | When an intake folder holds unread slots waiting on your decision                 |
+| `canon:backlog-triage`     | When the backlog needs pruning, to file a verdict per row and apply approved ones |
+| `canon:plan-groundwork`    | When the state is unmeasured and more than one approach is live                   |
+| `canon:decision-escalate`  | When open decisions turn on your preference and want batching into one set        |
+| `canon:draft-and-pick`     | When the call is taste and wants several candidates rendered side by side         |
+| `canon:task-board`         | When a decided item needs a file on the board, or a shipped one needs archiving   |
+| `canon:plan-feature`       | When the approach is settled and the next step is a plan                          |
+| `canon:codebase-layout`    | When a plan or change adds a file and you need to decide which folder holds it    |
+
+## Build the feature
+
+| Skill                        | When to use                                                                                                |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `canon:session-worktree`     | At the plan-to-execute boundary, to get an isolated tree and branch, or to route a refused main-root write |
+| `canon:auto-ship`            | After plan approval, to chain implement, verify, review, draft PR                                          |
+| `canon:project-commands`     | When the project's own command needs running                                                               |
+| `canon:test-first`           | Before implementing a planned change, to run its test red, green, then refactor                            |
+| `canon:test-craft`           | When writing or changing any test, to pick its layer and filter what it asserts                            |
+| `canon:review-craft`         | When reviewing a change, for what to look for and how much evidence a finding needs                        |
+| `canon:systematic-debugging` | When a test fails or a bug surfaces, to force root cause first                                             |
+| `canon:ui-checklist`         | After a UI change, to write what to look at and name what ships untested                                   |
+
+## Check the work before it leaves the branch
+
+| Skill                    | When to use                                                                             |
+| ------------------------ | --------------------------------------------------------------------------------------- |
+| `canon:review-branch`    | On the local branch diff, before anything is pushed                                     |
+| `canon:standards-audit`  | When changed markdown has to answer to the authoring standards                          |
+| `canon:document-health`  | When the documents themselves have to answer for length, placement, and staleness       |
+| `canon:markdown-propose` | When a markdown claim needs rewriting and the change should wait for an answer per file |
+| `canon:ux-audit`         | To read UI source for missing states, edge cases, and inconsistencies                   |
+| `canon:ux-measure`       | To start the interface and measure paint, processor, and layout cost                    |
+| `canon:ux-walkthrough`   | To run a multi-finding inspection pass over a running app with the operator             |
+
+## Ship it
+
+| Skill                  | When to use                                                                                       |
+| ---------------------- | ------------------------------------------------------------------------------------------------- |
+| `canon:git-ship`       | To run the whole post-feature chain from the verify gate through open PR                          |
+| `canon:memory-capture` | First skill in that chain, to route what the session learned to the surface owning it             |
+| `canon:context-fold`   | When decisions diverged from the plan, or a shipped task needs its outcomes marked                |
+| `canon:docs-fold`      | Never on purpose. A pointer at the old name that names `context-fold` <!-- canon-keep-retired --> |
+| `canon:docs-sync`      | When a change since main left `README.md` or `docs/` stale                                        |
+| `canon:git-stage`      | When the staged set spans several concerns and wants one commit each                              |
+| `canon:git-commit`     | When the staged set is one concern, or was staged hunk by hand                                    |
+| `canon:git-branch`     | When a branch name needs generating or renaming to conventional form                              |
+| `canon:git-pr`         | When a pull request needs a title and body written from the diff                                  |
+| `canon:memory-review`  | When the pen has grown, to propose where each entry belongs                                       |
+
+## After the pull request opens
+
+| Skill                  | When to use                                                          |
+| ---------------------- | -------------------------------------------------------------------- |
+| `canon:review-pr`      | From an independent session, to post findings on the PR itself       |
+| `canon:review-address` | On the worker's side, to fix posted findings and push a follow-up    |
+| `canon:git-followup`   | For a small self-review edit on a branch whose PR is already open    |
+| `canon:git-split`      | When a branch turns out to carry unrelated commits                   |
+| `canon:git-issue`      | When something surfaced that belongs on the tracker rather than here |
+| `canon:git-worktree`   | After a PR merges, to list worktrees and reclaim the slot            |
+
+## Run several tracks at once
+
+| Skill                     | When to use                                                                                                 |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `canon:role-orchestrator` | To assert the control session that owns the queue and reviews each worker's PR                              |
+| `canon:role-planner`      | To assert the thinking role for a cold session writing a plan, a groundwork track, or an intake pass        |
+| `canon:role-worker`       | To assert the worker role for a cold session building one branch under one plan                             |
+| `canon:session-relay`     | When this session owes another session a message, with or without a role                                    |
+| `canon:session-resume`    | At the start of a session, to pick up what a previous one left                                              |
+| `canon:session-compact`   | Before a compaction or a move to another machine, to write a plain session's handoff note outside the board |
+| `canon:session-map`       | At the close of an orchestrating session, to write its board-side handoff                                   |
+
+## Keep the project current with the toolkit
+
+| Skill                         | When to use                                                                            |
+| ----------------------------- | -------------------------------------------------------------------------------------- |
+| `canon:target-check`          | In a target project, to report per domain what it holds against what the toolkit ships |
+| `canon:seed-sync`             | After a toolkit update, to reconcile installed seeds without losing customizations     |
+| `canon:canon-feedback`        | When something in the toolkit is broken, missing, or off, to open an issue on it       |
+| `canon:canon-feedback-triage` | In the toolkit repo, to work through the open feedback issues                          |
+| `canon:canon-rollout`         | In the toolkit repo, to take one change out to every consuming project at once         |
+
+## Generate an artifact on demand
+
+| Skill                     | When to use                                                                                                       |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `canon:create-rule`       | For a project-specific governance rule the toolkit does not ship                                                  |
+| `canon:create-skill`      | For a new `SKILL.md`                                                                                              |
+| `canon:create-snippet`    | For a reusable prompt                                                                                             |
+| `canon:create-standard`   | For a new authoring convention                                                                                    |
+| `canon:draft-docs`        | For a brand-new `docs/*.md` page, drafted against `standards/docs.md`                                             |
+| `canon:draft-ready`       | For finished files a worker should copy, written as a ready folder with its overview, thin plan, and task         |
+| `canon:draft-context`     | For a brand-new `canon/context/<domain>.md` entry, drafted against `standards/context.md`                         |
+| `canon:draft-wireframes`  | For a brand-new `canon/wireframes/<surface>.md` file, drafted against `standards/wireframes.md`                   |
+| `canon:draft-wiki`        | For a brand-new wiki reference page on a subject owned outside the project, drafted against `standards/wiki.md`   |
+| `canon:draft-figure`      | For a hand-drawn figure inside an existing doc, drafted against `standards/figures.md` in Mermaid or freehand SVG |
+| `canon:draft-readme`      | For a project's `README.md`, drafted against `standards/readme.md`                                                |
+| `canon:bash-script`       | For an interactive, human-facing shell tool                                                                       |
+| `canon:bash-cli-script`   | For a non-interactive automation, CI, or pipeline script                                                          |
+| `canon:ci-workflow`       | For a GitHub Actions workflow file                                                                                |
+| `canon:draft-slides`      | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint                                             |
+| `canon:draft-screencast`  | For a recording script with beats and defaults already seeded                                                     |
+| `canon:record-screencast` | For compiling and running a screencast draft into a recording and a still                                         |
+| `canon:draft-identity`    | For a project's logo mark and its social card, drafted through `draft-and-pick`'s pick loop                       |
+
+## Answer a question at any point
+
+| Skill                       | When to use                                                                                                                                                            |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `canon:canon-cli`           | Before running an unfamiliar verb, a sync, or an install, to learn which command to run, which reference doc covers it, or what it overwrites, merges, or leaves alone |
+| `canon:index-lookup`        | To find where a topic is documented across the tracked `index.md` catalogs                                                                                             |
+| `canon:youtube-transcripts` | When a video transcript is wanted in the repo as context                                                                                                               |
+| `canon:read-frames`         | To read a recorded demo back frame by frame and report what each one shows, with no verdict on whether the recording looks right                                       |
+| `canon:teach-workspace`     | To learn a subject across sessions, in a workspace that holds the progress                                                                                             |
+| `canon:write-human`         | Before drafting or revising prose, for voice, rhythm, and density                                                                                                      |
+| `canon:restate-plainly`     | When an answer or a document has to be read again in plain words                                                                                                       |
+
+Every row answers a question rather than marking a point in a project's life, so a phase above would send a reader to the wrong group.
+
+A learning workspace produces two halves and only one of them leaves. A lesson is worked through once and stays in the workspace, and a reference page or a glossary carries no learner, so it belongs wherever the project already keeps prose on that subject. Asking `canon:teach-workspace` to promote sorts each durable page by who owns its subject, sending an Anthropic-owned subject to the wiki, an internal one to the matching context entry, and everything else, subject-neutral material included, to the public docs. It proposes and waits, because a promoted page is public prose that needs a line naming who owns the subject, and it writes nothing to a destination: each page the operator confirms goes to a handoff file that `canon:context-fold` folds in from a branch. A project with no wiki folder gets a refusal naming `canon wiki init` rather than a folder it never asked for.

package/governance/renames.toml

@@ -11,3 +11,37 @@
 # stay. A key must name no live rule and every chain must end on one, which
 # `src/gov/renames.test.ts` checks against this file.
 [renamed]
+"005-behavior" = "565-behavior"
+"015-output" = "566-output"
+"070-planning" = "567-planning"
+"025-indexes" = "601-indexes"
+"035-tasks" = "602-tasks"
+"045-memory" = "603-memory"
+"055-scratch" = "604-scratch"
+"085-worktrees" = "605-worktrees"
+"087-git" = "606-git"
+"510-context" = "610-context"
+"511-indexes" = "611-indexes"
+"520-wireframes" = "620-wireframes"
+"530-requirements" = "630-requirements"
+"540-architecture" = "640-architecture"
+"545-decisions" = "645-decisions"
+"550-design" = "650-design"
+"555-tasks" = "655-tasks"
+"556-groundwork" = "656-groundwork"
+"557-intake" = "657-intake"
+"558-plan" = "658-plan"
+"559-memory" = "659-memory"
+"560-diagrams" = "660-diagrams"
+"561-teach" = "661-teach"
+"562-session" = "662-session"
+"563-ready" = "663-ready"
+"500-prose" = "800-prose"
+"501-markdown" = "801-markdown"
+"502-mermaid" = "802-mermaid"
+"580-readme" = "880-readme"
+"591-standard-authoring" = "891-standard-authoring"
+"065-spelling" = "765-spelling"
+"075-dependencies" = "775-dependencies"
+"080-config-comments" = "780-config-comments"
+"090-code-comments" = "790-code-comments"

package/governance/rules/{claude/555-tasks.md → canon/655-tasks.md}

@@ -1,5 +1,5 @@
 ---
-description: Route .canon/tasks/ edits to the tasks standard for filenames, frontmatter, and task file format
+description: Route .canon/tasks/ edits to the tasks standard for task files and the board standard for priority.md and backlog.md
 paths:
   - '.canon/tasks/**'
 ---
@@ -9,4 +9,5 @@ paths:
 ## Authority
 
 - Follow the tasks standard for filenames, frontmatter, what belongs, and the task file format. It is the single source. Read it with `canon standards tasks`.
+- Follow the board standard for `priority.md` and `backlog.md`, their readiness groups, and row order. Read it with `canon standards board`.
 - Never hand-edit `.canon/tasks/index.md`. A hook regenerates it from sibling frontmatter.

package/governance/rules/{claude/560-diagrams.md → canon/660-diagrams.md}

@@ -10,7 +10,7 @@ paths:
 ## Authority
 
 - Follow the diagrams standard for which question an entry answers, the entry kinds and their source signals, the frontmatter, and the explanation prose beneath the fence. It is the single source. Read it with `canon standards diagrams`.
-- Layout, budgets, accessibility, labels, and render verification inside the fence are a separate topic. `502-mermaid` routes them to `mermaid.md`.
+- Layout, budgets, accessibility, labels, and render verification inside the fence are a separate topic. `802-mermaid` routes them to `mermaid.md`.
 - A diagram entry carries structure and flow, not implementation. Read the standard before adding or revising a kind.
 
 ## Scope

package/governance/rules/{claude/562-session.md → canon/662-session.md}

@@ -8,7 +8,7 @@ paths:
 
 ## What a handoff carries
 
-- Follow this rule rather than `555-tasks.md` for a `session-` file. A handoff is not a task and carries neither `## Outcomes` nor `## Findings`.
+- Follow this rule rather than `655-tasks.md` for a `session-` file. A handoff is not a task and carries neither `## Outcomes` nor `## Findings`.
 
 ## Authority
 

package/governance/rules/code/000-code.md

@@ -0,0 +1,21 @@
+---
+description: Code placement, dependency, error, and naming choices a model does not make by default
+---
+
+# Code standards
+
+## Placement
+
+- Load the `canon:codebase-layout` skill before placing a new file, and report it rather than proceeding silently when it does not resolve.
+- Prioritize native platform capabilities over third-party libraries.
+- Ensure data and configuration reside in designated Single Source of Truth locations.
+
+## Errors
+
+- Return structured error types for recoverable failures.
+- Never expose internal implementation details in error messages.
+
+## Naming
+
+- Prefix booleans with `is`, `has`, `should`, or `can`: `isLoading`, `hasAccess`.
+- Prefix event handlers with `handle`: `handleClick`, `handleSubmit`.

package/governance/rules/lib/300-testing-ts.md

@@ -9,10 +9,6 @@ paths:
 
 # TypeScript/JavaScript testing tooling
 
-## Layer
-
-- Load the `canon:test-craft` skill to pick the layer a test belongs at before choosing the tooling below, and report it rather than proceeding silently when the skill does not resolve.
-
 ## Unit and integration
 
 - Use Vitest for unit and integration tests.

package/governance/rules/lib/330-testing-py.md

@@ -8,10 +8,6 @@ paths:
 
 # Python testing tooling
 
-## Layer
-
-- Load the `canon:test-craft` skill to pick the layer a test belongs at before choosing the tooling below, and report it rather than proceeding silently when the skill does not resolve.
-
 ## Framework
 
 - Use `pytest` for all tests. Do not use `unittest.TestCase`.

package/governance/rules/{claude/500-prose.md → writing/800-prose.md}

@@ -12,4 +12,4 @@ paths:
 - Load it before drafting a passage, not after revising one.
 - Report it rather than proceeding silently when the skill does not resolve.
 - Do not work these rules from memory.
-- Punctuation, formatting, and file references are a separate topic. `501-markdown` routes them.
+- Punctuation, formatting, and file references are a separate topic. `801-markdown` routes them.

package/governance/rules/{claude/501-markdown.md → writing/801-markdown.md}

@@ -11,4 +11,4 @@ paths:
 - Follow the markdown standard for headings, paragraph and list structure, code spans, punctuation, emphasis, file references, and the wording of a `title` or `description`. It is the single source. Read it with `canon standards markdown`.
 - Read it before a substantial markdown edit. Do not work the banned characters from memory.
 - Run `canon markdown audit <path>` after the edit, and rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
-- Voice, rhythm, and sentence construction are a separate topic. `500-prose` routes them.
+- Voice, rhythm, and sentence construction are a separate topic. `800-prose` routes them.

package/governance/rules/{claude/502-mermaid.md → writing/802-mermaid.md}

@@ -11,4 +11,4 @@ paths:
 - Apply this rule only when the edit drafts or revises a Mermaid fence. Skip it on a markdown edit carrying no diagram.
 - Follow the mermaid standard for direction and layout, node and edge budgets, the accessibility fields, punctuation inside labels, and how a render is verified. It is the single source. Read it with `canon standards mermaid`.
 - Read it before drafting the fence. Do not work the layout or the budgets from memory.
-- Which diagram a document carries and what question it answers is a separate topic. `560-diagrams` routes it.
+- Which diagram a document carries and what question it answers is a separate topic. `660-diagrams` routes it.

package/governance/stacks/base.toml

@@ -1,8 +1,9 @@
 extends = ""
-# All four folders whole. Every rule authored under them ships to a base
+# Four audience groups whole. Every rule authored under them ships to a base
 # consumer, so adding one is a single edit rather than a file and a name here.
-# `snippets` carries the `@`-reference convention rule, which lost its only
-# other delivery path when `canon snippets install` retired. `ci` carries the
-# workflow rule, whose glob is the only inbound route to the `ci-workflow`
-# skill.
-rules = ["core", "claude", "snippets", "ci", "120-bash"]
+# `canon` carries the toolkit workflow and canonical-doc rules, `claude` the
+# session conduct and `.claude/` authoring rules, `tooling` the dev setup and
+# CI workflow rules, and `writing` the prose and document-shape rules. The
+# `code` group is left to the stacks that write code, so a docs or writing
+# project loads no rule it can never apply.
+rules = ["canon", "claude", "tooling", "writing", "120-bash"]

package/governance/stacks/node.toml

@@ -1,2 +1,2 @@
 extends = "base"
-rules = ["100-typescript"]
+rules = ["code", "100-typescript"]

package/governance/stacks/python.toml

@@ -1,2 +1,2 @@
 extends = "base"
-rules = ["110-python", "340-pydantic", "330-testing-py", "360-security-server", "370-database"]
+rules = ["code", "110-python", "340-pydantic", "330-testing-py", "360-security-server", "370-database"]

package/package.json

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

package/scripts/core/install-check.sh

@@ -91,13 +91,11 @@ log_step "Assert scaffold"
 # Standards and snippets name no path because neither corpus installs into a
 # target. A scaffold reads a standard through `canon standards <name>` and a
 # snippet through the plugin's live `claude/snippets` symlink, both resolving
-# against the toolkit rather than a copy this gate could assert on. The
-# `@`-reference convention rule is the one snippets-domain file that still
-# installs, since `base` carries `governance/rules/snippets/` as a
-# folder-whole entry the same way it does `core` and `claude`.
+# against the toolkit rather than a copy this gate could assert on. The two
+# rule paths stand for the `claude` and `canon` groups `base` takes whole.
 for path in "CLAUDE.md" ".claude/wiki/index.md" ".claude" "canon/context/index.md" "canon/wireframes/index.md" ".canon/diagrams/index.md" \
   ".prettierrc" ".editorconfig" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.sh" \
-  ".claude/rules/canon/core/000-constitution.md" ".claude/rules/canon/snippets/600-at-references.md"; do
+  ".claude/rules/canon/claude/565-behavior.md" ".claude/rules/canon/canon/604-scratch.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then
     log_error "Missing after canon init: $path"
   fi

package/src/claude/routing.ts

@@ -196,7 +196,7 @@ function frontmatter(text: string): string {
  *
  * A glob opening `**` reaches every folder in the tree, so it answers that a
  * file type is governed and never that a named path is. Counting one would
- * report every markdown path covered by `501-markdown` and leave the column
+ * report every markdown path covered by `801-markdown` and leave the column
  * saying nothing a reader could act on.
  */
 function isAnchored(glob: string): boolean {

package/src/commands/gov.ts

@@ -234,7 +234,7 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'Measures the rule in .claude/rules/canon/core/070-planning.md that asks for',
+        'Measures the rule in .claude/rules/canon/claude/567-planning.md that asks for',
         'the test before the code. It reports and never gates, because pairing',
         'a test to an implementation is a judgment.',
         '',

package/src/commands/tasks.ts

@@ -11,6 +11,7 @@ import {
   type DeclineOutcome,
   declineTask,
   type PlanCitations,
+  type PlanMove,
   planCitations,
 } from '@/tasks/archive'
 import {
@@ -154,9 +155,9 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'The task carries its plan with it when no other live task cites that',
-        'plan, and the archived task keeps a working Plan: pointer at the new',
-        'path. A plan several tasks share stays where it is.',
+        'The task carries each plan its Plan: line links when no other live',
+        'task cites that plan, and the archived task keeps a working pointer',
+        'at each new path. A plan several tasks share stays where it is.',
         '',
         'The ready folder the task names moves to .canon/ready/archive/ with its',
         'plan, and the Ready: line and the plan path to it are retargeted. A',
@@ -260,6 +261,7 @@ export function register(program: Command): void {
         '',
         'Locations:',
         '  unstated  the task carries no Plan: line',
+        '  several   the Plan: line links more than one plan, named in targets',
         '  live      the target resolves inside .canon/plans/',
         '  archived  the target resolves inside .canon/plans/archive/',
         '  outside   the target resolves somewhere else',
@@ -448,12 +450,14 @@ export function register(program: Command): void {
         '',
         'Exit codes:',
         '  0  the line was added, corrected, or already correct',
-        '  1  refused, with the reason on stderr or in the JSON record',
+        '  1  refused, including several-plans for a line linking more than one',
+        '     plan, with the reason on stderr or in the JSON record',
         '',
         'It writes Plan: [<label>](<target>) right after the H1, corrects the',
-        'target in place when the line exists, and resolves both a bare slug',
-        'and a board-relative path the way canon tasks plan-answers does. Safe',
-        'from a linked worktree, since it resolves the board root in-process.',
+        'target in place when the line exists and names the one it replaced,',
+        'and resolves both a bare slug and a board-relative path the way canon',
+        'tasks plan-answers does. Safe from a linked worktree, since it',
+        'resolves the board root in-process.',
         '',
         'Examples:',
         '  canon tasks plan-link v28.1-trigger-escalation dispatch-answer-gate',
@@ -793,6 +797,7 @@ function reportPlanLink(
         path: relative(root, outcome.path),
         plan: outcome.plan,
         action: outcome.action,
+        replaced: outcome.replaced,
       })}\n`,
     )
     return 0
@@ -801,6 +806,7 @@ function reportPlanLink(
   intro('canon tasks plan-link')
   logStep(outcome.action === 'unchanged' ? 'Already recorded' : 'Recorded')
   logInfo(`${outcome.stem} names plan ${outcome.plan}`)
+  if (outcome.replaced) logInfo(`replaced ${outcome.replaced}`)
   if (outcome.action !== 'unchanged') logAdd(relative(root, outcome.path))
   outro()
 
@@ -975,6 +981,10 @@ function reportCitations(
 function describeCitations(outcome: PlanCitations): string {
   if (outcome.location === 'unstated') return 'carries no Plan: line.'
 
+  if (outcome.location === 'several') {
+    return `links ${outcome.targets.length} plans (${outcome.targets.join(', ')}), so no single plan is the sweep's to settle.`
+  }
+
   if (outcome.location === 'archived') {
     return `points at ${outcome.target}, which an earlier sweep already archived.`
   }
@@ -1396,11 +1406,7 @@ function report(
   logStep('Archived')
   logRemove(relative(root, outcome.from))
   logAdd(relative(root, outcome.to))
-  if (outcome.plan) {
-    logRemove(relative(root, outcome.plan.from))
-    logAdd(relative(root, outcome.plan.to))
-    logInfo('retargeted the Plan: line')
-  }
+  logPlanMoves(outcome.plans, root)
   if (outcome.ready) {
     logRemove(relative(root, outcome.ready.from))
     logAdd(relative(root, outcome.ready.to))
@@ -1414,6 +1420,24 @@ function report(
   return 0
 }
 
+function logPlanMoves(plans: readonly PlanMove[], root: string): void {
+  for (const plan of plans) {
+    logRemove(relative(root, plan.from))
+    logAdd(relative(root, plan.to))
+  }
+  if (plans.length > 0) logInfo('retargeted the Plan: line')
+}
+
+function planMovesFor(
+  plans: readonly PlanMove[],
+  root: string,
+): readonly { readonly from: string; readonly to: string }[] {
+  return plans.map((plan) => ({
+    from: relative(root, plan.from),
+    to: relative(root, plan.to),
+  }))
+}
+
 function recordFor(
   outcome: ArchiveOutcome,
   root: string,
@@ -1434,12 +1458,7 @@ function recordFor(
     to: relative(root, outcome.to),
     priorityRowRemoved: outcome.priorityRowRemoved,
     indexRegenerated: outcome.indexRegenerated,
-    plan: outcome.plan
-      ? {
-          from: relative(root, outcome.plan.from),
-          to: relative(root, outcome.plan.to),
-        }
-      : null,
+    plans: planMovesFor(outcome.plans, root),
     ready: outcome.ready
       ? {
           from: relative(root, outcome.ready.from),
@@ -1537,11 +1556,7 @@ function reportDecline(
   logStep('Declined')
   logRemove(relative(root, outcome.from))
   logAdd(relative(root, outcome.to))
-  if (outcome.plan) {
-    logRemove(relative(root, outcome.plan.from))
-    logAdd(relative(root, outcome.plan.to))
-    logInfo('retargeted the Plan: line')
-  }
+  logPlanMoves(outcome.plans, root)
   if (outcome.priorityRowRemoved) logInfo('cleared the ordering row')
   if (outcome.backlogRowRemoved) logInfo('cleared the backlog row')
   if (outcome.indexRegenerated) logInfo('regenerated index.md')
@@ -1571,11 +1586,6 @@ function declineRecordFor(
     priorityRowRemoved: outcome.priorityRowRemoved,
     backlogRowRemoved: outcome.backlogRowRemoved,
     indexRegenerated: outcome.indexRegenerated,
-    plan: outcome.plan
-      ? {
-          from: relative(root, outcome.plan.from),
-          to: relative(root, outcome.plan.to),
-        }
-      : null,
+    plans: planMovesFor(outcome.plans, root),
   }
 }

package/src/gate/measures.ts

@@ -101,12 +101,7 @@ const output = (text: string): Emission => ({ kind: 'output', text })
 /**
  * Rules no stack reaches, sorted the way `canon gov list` emits them.
  * `260-shadcn` and `320-tanstack-query` are opt-in libraries a project may not
- * want. `600-at-references` used to sit here too, shipping with no stack on
- * purpose since a rule under `claude/` would reach every base consumer through
- * the folder-whole entry there. Its own install channel, `canon snippets
- * install`, retired with nothing left to deliver it, so `base` now carries
- * `snippets` as a folder-whole entry of its own and the rule reaches every base
- * consumer through that instead.
+ * want.
  *
  * `130-go`, `140-php`, `335-testing-go`, and `336-testing-php` are opt-in by
  * `--add` until a Go or PHP stack ships, which `target-setup` reaches by

package/src/gate/stages.ts

@@ -107,6 +107,7 @@ const TESTS_SCOPE = new RegExp(
     '^vitest\\.config\\.ts$',
     '^tsconfig\\.json$',
     '^package\\.json$',
+    '^commitlint\\.config\\.(js|test\\.ts)$',
     ...TEST_CORPORA_PATTERNS,
   ].join('|'),
 )

package/src/gov/citations.ts

@@ -266,7 +266,7 @@ export function collectCitations(text: string): RawCitation[] {
  *
  * A rule spelling a whole path there is declaring that exact artifact, and a
  * body line naming it again is naming what the rule governs rather than
- * pointing a reader somewhere. `governance/rules/claude/560-diagrams.md` tells
+ * pointing a reader somewhere. `governance/rules/canon/660-diagrams.md` tells
  * its reader to convert a `.claude/DIAGRAMS.md` left by an older install, which
  * is correctly absent from this tree and correctly named in the rule.
  */

package/src/gov/list.ts

@@ -31,7 +31,7 @@ export interface GovCatalog {
 /**
  * Reports each stack's own entries expanded, so a folder entry reaches a
  * consumer as the rules it stands for. the `setup` skill dedupes `--add` extras
- * against this list, and a stack answering `core` there would re-add every
+ * against this list, and a stack answering `canon` there would re-add every
  * rule that folder already carries.
  *
  * The `extends` chain is deliberately not resolved, which is what the bash

package/src/gov/restated.ts

@@ -698,8 +698,8 @@ export function readRestated(root: string): RestatedReport {
 
   // Every candidate's rare set is invariant across the subject loop, so it is
   // built once here rather than per pair. The corpora multiply out to hundreds
-  // of thousands of pairings, and rebuilding a set inside that is the shape
-  // `.claude/rules/canon/core/040-performance.md` names.
+  // of thousands of pairings, and rebuilding a set inside that would dominate
+  // the run.
   const rareCandidates = candidates.map((candidate) => ({
     ...candidate,
     rare: distinctive(candidate.analysis),

package/src/init/steps.ts

@@ -5,7 +5,7 @@ import type { DomainStep } from '@/init/run'
 export type RunFactory = (args: readonly string[]) => () => Promise<boolean>
 
 /**
- * States the same fact as `docs/target-projects.md`'s backup section in its
+ * States the same fact as `docs/target-migrations.md`'s backup section in its
  * own words. Keep the two in step by hand; nothing compares them.
  */
 const RECORDS_SETUP_NOTICE =

package/src/labels/spelling.ts

@@ -8,7 +8,7 @@ import { execa } from 'execa'
  *
  * `no-binary` is the binary being absent anywhere from the root upward.
  * `cspell` is a devDependency of this repository alone, per
- * `075-dependencies.md`'s ban on importing a transitive-only package, so a
+ * `775-dependencies.md`'s ban on importing a transitive-only package, so a
  * target project that never adopted it gets no coverage from this check
  * rather than a network fetch or a forced new dependency.
  *

package/src/records/prune.ts

@@ -35,7 +35,7 @@ const LEGACY_MOVES: ReadonlyMap<string, string> = new Map([
  * Scratch-root names a different migration moves out of scratch for good,
  * derived from that migration's own table rather than duplicated in a second
  * hand-kept list. `RECORD_LAYOUT_MOVES` names `memory-archive`, the
- * retired-entry archive `045-memory` says never to delete, and `PROMOTED_FOLDERS`
+ * retired-entry archive `603-memory` says never to delete, and `PROMOTED_FOLDERS`
  * names an evidence folder a durable record cites by name. A project that has
  * not run either migration still carries these at the scratch root, where an
  * ordinary slug's own age test would eventually offer them.

package/src/shipped/references.ts

@@ -212,7 +212,7 @@ const PHASE_LABEL = /\bv\d+\.\d+(?!\.\d)\b/g
  * number, such as `create-rule`, `memory-review`, and `target-setup` already
  * write correctly, from matching. The segment group between `rules/` and the
  * numbered file admits both a governance-namespace path
- * (`canon/core/055-scratch.md`) and a project-namespace one
+ * (`canon/canon/604-scratch.md`) and a project-namespace one
  * (`project/<subdir>/<n>-<slug>.md`) without distinguishing them, since
  * either shape is the same broken citation.
  */