@erclx/canon 5.32.0 → 5.33.0

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.32.0",
+  "version": "5.33.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/auto-ship/SKILL.md

@@ -12,7 +12,7 @@ Chain the post-plan pipeline in a single run. Every step but the UI checklist ha
 ## Guards
 
 - All `.canon/plans/` reads resolve at the main worktree root, not the current worktree. Resolve that root the way `session-worktree` does.
-- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. This skill takes the stop rather than the `latest` fallback, since it commits and opens a pull request. If empty, stop: `❌ Detached HEAD. Checkout the feature branch first.` This slug is provisional. It is superseded once `session-worktree` runs, whether at Step 0 or before this chain began. Every later step keys its output on the slug that run resolves, being the worktree and the branch, regardless of which plan Step 1 reads.
+- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`. This skill takes the stop rather than the `latest` fallback, since it commits and opens a pull request. If empty, stop: `❌ Detached HEAD. Checkout the feature branch first.` This slug is provisional. It is superseded once `session-worktree` runs, whether at Step 0 or before this chain began. Every later step keys its output on the slug that run resolves, being the worktree and the branch, regardless of which plan Step 1 reads.
 - Resolve `<plan>` in Step 1, ahead of any other read.
 - If the working tree has uncommitted changes unrelated to the plan, stop: `❌ Uncommitted changes outside the plan. Commit or stash before autoshipping.`
 

package/claude/skills/auto-ship/references/worktree-name.md

@@ -14,7 +14,7 @@ canon tasks plan-branch <argument> --json
 ```
 
 - `conforms: true`: pass the record's `branch`, which is already `<type>/<slug>`, and invoke nothing else to derive a name.
-- `conforms: false`: the plan's own filename breaks a cap in `${CLAUDE_SKILL_DIR}/../../standards/branch.md`. Pass `branch` anyway and say the cap it broke, since the alternative is a name this session shortened by hand, which is a second derivation and the thing this call exists to prevent. `git-branch` decides the rename at ship.
+- `conforms: false`: the plan's own filename breaks a cap in `${CLAUDE_SKILL_DIR}/../git-branch/references/branch.md`. Pass `branch` anyway and say the cap it broke, since the alternative is a name this session shortened by hand, which is a second derivation and the thing this call exists to prevent. `git-branch` decides the rename at ship.
 - Anything else, including a refusal, a record carrying no `branch` key, and an installed binary carrying no `plan-branch` subcommand: invoke `canon:session-worktree` bare and let its ladder derive the name. Say the verb did not answer, so a reader can tell a derived name from a fallback one.
 
 The dispatch runbook runs the same verb on the same plan to pick the branch its collision check clears, so calling it here is what makes the checked branch and the taken branch one string.

package/claude/skills/backlog-triage/REQUIREMENT.md

@@ -7,7 +7,7 @@ description: Why the backlog gets a measured verdict per row with a lean toward
 
 ## Gap
 
-Without this skill, the backlog only grows. `task-board` declines or archives one named task, and nothing reads the backlog as a whole, so a row stays until somebody happens to remember it and decides by hand. The orchestrator's backlog re-test only clears a row upward onto the board, so no sweep ever takes one off. A backlog past fifty rows had no surface that could say which of them still mattered.
+Without this skill, the backlog only grows. `task-board` declines one named task and `task-complete` archives one, and nothing reads the backlog as a whole, so a row stays until somebody happens to remember it and decides by hand. The orchestrator's backlog re-test only clears a row upward onto the board, so no sweep ever takes one off. A backlog past fifty rows had no surface that could say which of them still mattered.
 
 Four failure modes cost more than the rest. A pass that judges a row by what its task file says rather than by the tree keeps every row, since a task file reads as live the day it was written and every day after. A pass that applies its own verdicts decides rows on silence, which ships a decline nobody approved on a board with no history to restore it from. A keep that carries no measurement is the default nobody argues with, so a triage without a lean toward decline ends with the same backlog it started with. And a keep that measures only that the defect still exists keeps nearly everything, since a row filed against the tree almost always still reproduces. One pass suggested keeping 24 of 27 rows that way, where the operator kept 6 and promoted 1.
 
@@ -42,6 +42,6 @@ Four failure modes cost more than the rest. A pass that judges a row by what its
 
 - Filing a brain dump, which `plan-intake` owns
 - Answering the filed items, which `plan-intake-answer` owns
-- Creating a task, or archiving and declining one named task outside a triage, which `task-board` owns
+- Creating or declining one named task outside a triage, which `task-board` owns, and archiving one, which `task-complete` owns
 - Ordering the rows a promote lands under `## Needs a plan`, which the orchestrator's refill sweep owns
 - Skipping rows kept at a recent triage, which waits on a second triage measuring the re-read cost

package/claude/skills/backlog-triage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: backlog-triage
-description: Files a measured verdict for every backlog row into an intake folder, suggesting decline, archive, keep, or promote and leaning toward decline, then applies the verdicts the operator approved through the task verbs. Use when asked to "triage the backlog", "prune the backlog", "which backlog rows are still worth doing", "clear out the backlog", or "apply the backlog triage". Do NOT use to file a brain dump, which is `plan-intake`, to answer the filed items, which is `plan-intake-answer`, or to create, archive, or decline one named task, which is `task-board`.
+description: Files a measured verdict for every backlog row into an intake folder, suggesting decline, archive, keep, or promote and leaning toward decline, then applies the verdicts the operator approved through the task verbs. Use when asked to "triage the backlog", "prune the backlog", "which backlog rows are still worth doing", "clear out the backlog", or "apply the backlog triage". Do NOT use to file a brain dump, which is `plan-intake`, to answer the filed items, which is `plan-intake-answer`, or to create or decline one named task, which is `task-board`, or archive one, which is `task-complete`.
 metadata:
   family: decide
 ---

package/claude/skills/canon-cli/REQUIREMENT.md

@@ -1,39 +1,42 @@
 ---
 name: canon-cli
-description: Why a session is pointed at the verb catalog, the reference docs, and the overwrite contract from one place, and why the skill reads rather than writes
+description: Why a session is routed from a job to its canon verb from one place, why the verbs that can lose its edits are flagged before they run, and why the skill reads rather than writes
 ---
 
 # Canon cli requirement
 
 ## Gap
 
-Without this skill, a session runs a `canon` sync and finds out afterward what it did. The command names give nothing away. `install` and `sync` differ per domain, some surfaces overwrite unconditionally, some merge, some are written once and never touched again, and none of that is visible from the command line the user typed.
+Without this skill, a session guesses at a verb from its name and runs a `canon` sync to find out afterward what it did. The command names give nothing away. `install` and `sync` differ per domain, some surfaces overwrite unconditionally, some merge, some are written once and never touched again, and none of that is visible from the command line the user typed.
 
-The damage lands on the files a project owns. A golden config carrying local edits is replaced without a warning anyone saw, and a standards install overwrites every standard in a project that only needed the two it had drifted on. The user learns which category a file was in by losing the edit.
+The damage lands on the files a project owns. A golden config carrying local edits is replaced without a warning anyone saw, and a governance sync takes back a rule the project had edited. The user learns which category a file was in by losing the edit.
 
 The inverse failure is quieter. A session that assumes a sync will pick up a change edits a seed and waits for an update that never comes, because the seed is copy-once and no sync command writes it again. Both failures are one missing fact available before the command runs.
 
-Being reachable is a separate problem from being right. This is a pure reference whose moment happens inside another skill's run, so nothing brings it up unless a body names it. Three sibling requirement files named it and routed nothing, because Claude Code loads `SKILL.md` as the entry and never opens the sibling. A route lives in a body or it does not exist, and a fourth requirement mention would repeat the same defect.
+A third gap is the route itself. `canon --help` lists every top-level verb with a partial hint, and a session with a job in hand pays a `--help` read per candidate to find the one that does it, or picks by name and lands on the wrong one. The job-to-verb mapping is the fact the session needs and no verb answers.
 
-A third gap sits beside the first two, aimed at a different question. `canon --help` lists every top-level verb and `canon docs` emits the toolkit's own reference corpus, but no reference skill pointed a session at either. No skill does now. A session guessing at a verb's name, or restating what a doc already answers, is the same missing-fact failure the overwrite gap names.
+Being reachable is a separate problem from being right. This is a pure reference whose moment happens inside another skill's run, so nothing brings it up unless a body names it. A route lives in a body or it does not exist, and a mention in a sibling's requirement file is not one.
 
 ## Must
 
-- State per surface and per command whether an existing file is overwritten, merged, written once, or left alone
-- Warn about a destructive run before it happens, naming the surface that will be lost
-- Name the section-preserving path for a standard or seed the project has customized
-- Defer to the toolkit's own context docs when they and this summary disagree, since the summary is a copy and they are the source
-- Point to `canon docs agents` for the verb catalog and to `canon docs` for the reference corpus, rather than restating either
+- Name each target-usable top-level verb by its job, never its subcommands or flags
+- Route an author-and-render verb to the skill that owns it rather than describing it
+- Warn about a verb that can lose the project's edits before it runs, naming what it replaces
+- Point each destructive verb at `canon docs install-and-sync`, which owns the overwrite detail
+- Point to `canon <verb> --help` and `canon docs agents` for subcommands, flags, and the invocation contract
+- Defer to `canon docs install-and-sync` when it and this summary disagree, since the summary is a copy and the doc is the source
 
 ## Must not
 
 - Run, or send the session to run, a `canon` command that writes or installs. The skill is read before acting on a sync.
-- Restate the verb catalog or a reference doc's content. Point to `canon docs agents` or `canon docs <topic>` instead. The overwrite table is this skill's one authored exception, and it too is a target-session summary, with the detail living with its owner.
-- Take a mention in a sibling's requirement file as an inbound route. The three bodies named in the gap above carry the pointer, and adding a fourth means editing that body rather than its requirement.
+- List a subcommand, a flag, or a JSON shape. That restates the docs and is the drift the one-name-per-verb rule removes.
+- List a verb that only works inside the toolkit repository. A named exemption set in the coverage test holds that boundary.
+- Take a mention in a sibling's requirement file as an inbound route. The pointer lives in the body that needs it.
 
 ## Guards
 
-- A surface or command the contract does not cover routes to the context docs rather than to an inference from a similar row
+- A test fails naming each top-level verb in `COMMAND_GROUPS` that the body neither carries as `canon <verb>` nor exempts, and fails again when an exemption names something that is no longer a verb
+- A verb or surface the skill does not cover routes to `canon docs` rather than to an inference from a similar row
 
 ## Out of scope
 

package/claude/skills/canon-cli/SKILL.md

@@ -1,53 +1,96 @@
 ---
 name: canon-cli
-description: Reference for what a canon verb does before you run it. Run `canon docs agents` for the full command catalog, `canon docs` for any other reference doc, and read this skill's own table for what a sync or install command overwrites, merges, or leaves untouched in a target project. Use when asked "which canon command do I run", "is there a doc for X", "will this overwrite my changes", or before running `canon tooling`, `canon standards`, `canon claude sync`, or `canon init`. Do NOT use to execute a sync, an install, or a docs lookup, only to know which command answers the question.
+description: Routes a job to the `canon` verb that does it, and warns which verbs can lose a project's edits before one runs. Use when asked "which canon command does X", "is there a verb for X", "which command tells me if X", "will this overwrite my changes", or before running `canon sync`, `canon gov sync`, `canon tooling sync`, `canon design sync`, `canon migrate`, or `canon indexes regen`. Do NOT use to execute a verb, only to pick one and know what it costs.
 metadata:
   family: answer
 ---
 
-# Toolkit CLI contract
+# Toolkit CLI router
 
-Consult before running an unfamiliar `canon` verb, before a sync or install, or when asked "will this overwrite my changes". This skill is reference only. It never runs a sync or an install.
+Consult to pick the `canon` verb for a job, and before running a verb that writes. This skill is reference only. It never runs a verb.
 
-## Verb catalog and reference docs
+## Find the verb
 
-- Run `canon docs agents` for the full command catalog and invocation contract, rather than guessing at a verb from its name.
-- Run `canon docs list` for every other reference doc, then `canon docs <topic>` by name.
-- State neither list here. Both read live off the CLI, and a copy in this body ships on a different cadence than the commands it names.
+- Each row below names a verb by its job. Subcommands and flags are not listed here, so read them where they are kept.
+- Run `canon <verb> --help` for a verb's subcommands and flags.
+- Run `canon docs agents` for the invocation contract behind every verb, and `canon docs list` for every other reference doc, then `canon docs <topic>` by name.
 
-## Overwrite contract
+## Project setup
 
-| Surface                                                                                       | Command              | Effect on existing files                                                    |
-| --------------------------------------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------- |
-| Golden configs                                                                                | `canon tooling sync` | Overwritten once `--write` is passed. Local edits are lost.                 |
-| Dictionary seeds (`.cspell/*.txt`)                                                            | `canon tooling sync` | Merged and sorted. Existing terms preserved.                                |
-| Other seeds (`cspell.json`, `.lintstagedrc`, base's `verify.yml` and PR template, state docs) | `canon tooling sync` | Copy-once. Dropped on first install, untouched after.                       |
-| Standards                                                                                     | none                 | Nothing installs. `canon standards <name>` reads and never writes.          |
-| Seed docs and `CLAUDE.md`                                                                     | `canon claude init`  | Skipped when present. Never overwritten.                                    |
-| Seed docs                                                                                     | `canon claude sync`  | Never touched. Only `.gitignore` is written.                                |
-| Stack references                                                                              | none                 | Nothing installs. `canon tooling reference <stack>` reads and never writes. |
-| `.gitignore`, deps, scripts                                                                   | any sync             | Additive. Existing entries preserved. Deps re-pin on major skew.            |
-| Generated `index.md`                                                                          | any sync or regen    | Rewritten from target state. Hand edits are lost.                           |
+| Job                                          | Verb            |
+| -------------------------------------------- | --------------- |
+| Bootstrap a project with toolkit domains     | `canon init`    |
+| Bring every installed domain current         | `canon sync`    |
+| Reinstall the CLI itself                     | `canon upgrade` |
+| Move a project off a retired name or layout  | `canon migrate` |
+| List the projects the toolkit installed into | `canon targets` |
 
-## What a tooling sync can overwrite
+## Domains
 
-A golden config is any file a stack ships under `configs/`, and the category is wider than its name suggests. It carries the phase-label gate workflow, the web stack's CI workflow, the git hooks, the end-to-end harness, the shell scripts under `scripts/`, and the editor settings, alongside the linters and compilers a reader expects. A stack inherits its parent's configs, so syncing `astro` also writes everything `web` and `base` hold.
+| Job                                                             | Verb              |
+| --------------------------------------------------------------- | ----------------- |
+| Install or sync governance rules                                | `canon gov`       |
+| Read an authoring standard by name                              | `canon standards` |
+| Sync a tooling stack's configs and seeds, or read its reference | `canon tooling`   |
+| Set up or sync the Claude workflow                              | `canon claude`    |
+| Scaffold a wiki                                                 | `canon wiki`      |
+| Regenerate the `index.md` files                                 | `canon indexes`   |
+| Read a toolkit reference doc                                    | `canon docs`      |
 
-No list of those paths ships in this body, since a copy would go stale on a different cadence than the stacks. Run `canon tooling diff <stack> <target>` for the list resolved against a real target. It reports every path, writes nothing, and exits 1 when any differs. A binary older than that verb answers the same question through `canon tooling sync <stack> <target> --check`, which names each file it would replace.
+## Author and render
 
-## Rules
+Each verb here has a skill that owns the job. Load the skill rather than driving the verb by hand.
 
-- `canon tooling sync` writes nothing until `--write` is passed. A headless run without it reports and exits 1, so a script that forgets the flag fails rather than silently skipping the sync.
-- Run `--check` first when the project carries local edits to a config the stack ships. The report names each file it would replace, which is the warning the user needs before the write.
-- An interactive run still prompts. `--write` skips the prompt, and `--check` refuses to write even with a TTY.
-- Seeds are user-owned. Dictionary `.txt` files merge and sort. Other seeds are copy-once, so re-seeding a structured file means deleting it and syncing again.
-- No command writes a standard into a project. A `.claude/standards/` folder from an older toolkit is inert, and deleting it costs nothing.
-- For section-level customizations of a seed doc, merge by hand against the toolkit copy, not through `canon ... sync`.
+| Job                                          | Verb                | Skill                       |
+| -------------------------------------------- | ------------------- | --------------------------- |
+| Render the design system                     | `canon design`      | `canon:draft-figure`        |
+| Render a slide deck                          | `canon slides`      | `canon:draft-slides`        |
+| Render an HTML source to a PNG               | `canon capture`     | `canon:draft-identity`      |
+| Serve a directory and print the link         | `canon serve`       | none                        |
+| Record a running app                         | `canon demo`        | `canon:draft-screencast`    |
+| Report one computed property across routes   | `canon inventory`   | `canon:target-check`        |
+| Walk a page through interactions and measure | `canon drive`       | `canon:ux-measure`          |
+| Fetch a YouTube transcript                   | `canon transcripts` | `canon:youtube-transcripts` |
+| Open a learning workspace                    | `canon teach`       | `canon:teach-workspace`     |
+| Work on the local canvas                     | `canon canvas`      | `canon:canvas-board`        |
 
-## CLAUDE.md
+## Session and ship
 
-- `CLAUDE.md` is a copy-once seed. No `canon` sync command ever updates it. Merge it by hand against the toolkit copy, keeping the project's customizations.
+| Job                                            | Verb              |
+| ---------------------------------------------- | ----------------- |
+| Read and close tasks on the board              | `canon tasks`     |
+| Read and answer intake folders                 | `canon intake`    |
+| Validate, size, and move session records       | `canon records`   |
+| Resolve live sessions to a worktree and branch | `canon sessions`  |
+| Reclaim worktrees whose branches merged        | `canon worktrees` |
+| Read a pull request                            | `canon pr`        |
+| File toolkit feedback as an issue              | `canon feedback`  |
+
+## Reports
+
+| Job                                       | Verb             |
+| ----------------------------------------- | ---------------- |
+| Scan the tree for credentials             | `canon secrets`  |
+| Read the dependency set for advisories    | `canon deps`     |
+| Check a changed set against the label map | `canon labels`   |
+| Measure comment density                   | `canon comments` |
+| Report context folder health              | `canon context`  |
+| Check markdown against the standards      | `canon markdown` |
+| Count files, extensions, and lines        | `canon census`   |
+
+## Verbs that can lose your edits
+
+Read the doc each line names before running one of these. `canon docs install-and-sync` covers the governance and design verbs, `canon docs sync` covers tooling, `canon docs indexes` covers regeneration, and `canon docs migrate` covers the migrate verbs. Run the `--check` or `--dry-run` form first where the verb has one.
+
+- `canon sync` runs every installed domain's sync, so it carries each risk below.
+- `canon gov sync` replaces a rule you edited and deletes a rule the toolkit retired, edited or not.
+- `canon tooling sync --write` replaces every golden config a stack ships. Seeds are copy-once and dictionaries merge. Nothing writes without the flag. See `canon docs sync`.
+- `canon design sync` replaces the shipped design files and leaves `.claude/design/project/` alone.
+- `canon migrate --write` rewrites files that cite a retired name or layout. It reports and writes nothing without the flag. See `canon docs migrate`.
+- `canon indexes regen` rewrites each generated `index.md` from the folder's current state, so a hand edit there is lost. See `canon docs indexes`.
+
+No command writes a standard into a project, so `canon standards` is safe to run. `CLAUDE.md` and the other seed docs are copy-once, and no sync updates them. Merge those by hand against the toolkit copy.
 
 ## Source of truth
 
-- Full semantics live in the toolkit's own context entries. This skill is the target-session summary. When they disagree, the context docs win.
+- `canon docs install-and-sync` states what each install and sync verb writes, refuses, or leaves alone. `canon docs indexes` and `canon docs migrate` state the same for their verbs. When a doc and this skill disagree, the doc wins.

package/claude/skills/canon-feedback/SKILL.md

@@ -73,7 +73,7 @@ command -v canon >/dev/null 2>&1
 
 The destination is a public GitHub issue on the toolkit repo, so the report leaves the machine. Hold it and ask when the operator has marked it sensitive, and never send it on a guess.
 
-Before the pipe below, run the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against the composed block, phase-label half included. Nothing else checks what reaches the remote, so this scan is the only gate.
+Before the pipe below, run the scan in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md` against the composed block, phase-label half included. Nothing else checks what reaches the remote, so this scan is the only gate.
 
 ```bash
 cat <<'EOF' | canon feedback

package/claude/skills/{canvas → canvas-board}/REQUIREMENT.md

@@ -1,9 +1,9 @@
 ---
-name: canvas
+name: canvas-board
 description: Scope boundary for driving the local design canvas, and the line between a drafted frame and the design it feeds
 ---
 
-# Canvas requirement
+# Canvas board requirement
 
 ## Gap
 

package/claude/skills/{canvas → canvas-board}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: canvas
+name: canvas-board
 description: Drives the local design canvas, where pages hold HTML frames the operator sees, drags, selects, and edits in the browser. Starts the canvas when it is not running, confirms the live shell loads, makes pages and frames, edits a frame through its file, reads what the operator selected or restyled, captures finished frames, and carries a picked direction into the project's design document. Use when asked to "open the canvas", "put this on the canvas", "draw a frame for X", "change the one I selected", "what did I pick", "capture this frame", or "move that frame on the canvas". Do NOT use to draft candidates for a taste decision, which is `draft-and-pick`.
 metadata:
   family: decide
 ---
 
-# Canvas
+# Canvas board
 
 Drive the canvas the operator is looking at. A page is a folder of HTML frames and a frame is one file, so a session draws by writing files and the operator sees each write land in the browser. The content format is fixed by `${CLAUDE_SKILL_DIR}/references/canvas.md`. Read it before writing a frame.
 

package/{standards → claude/skills/canvas-board/references}/design.md

@@ -1,14 +1,23 @@
 ---
 title: Design reference
 description: Shape and content rules for canon/DESIGN.md
-paths:
-  - 'canon/DESIGN.md'
 ---
 
 # Design reference
 
 Applies to `canon/DESIGN.md`. Captures visual intent and the decisions behind how things look, not a style guide, component spec, or framework reference. Update when a visual decision is made or a rule changes.
 
+## Contents
+
+- [Scope](#scope)
+- [What goes in](#what-goes-in)
+- [What does not go in](#what-does-not-go-in)
+- [Format](#format)
+- [Prose budget](#prose-budget)
+- [The uncertainty tag](#the-uncertainty-tag)
+- [Sections](#sections)
+- [Template](#template)
+
 ## Scope
 
 Governs the visual-intent document at `canon/DESIGN.md`: tokens described as intent, layout constraints, and the omissions that keep visual scope closed.

package/claude/skills/context-fold/REQUIREMENT.md

@@ -1,67 +1,59 @@
 ---
 name: context-fold
-description: What the planning-doc reconcile is for, the gaps it closes, and why the diff decides completion alone
+description: What the context-entry fold is for, the gaps it closes, and why it audits its own writes before it reports
 ---
 
 # Context fold requirement
 
 ## Gap
 
-Without this skill, the planning docs describe the scope the session opened with. An outcome the diff shipped stays unchecked, so the board reports finished work as open and the next session re-plans it. A decision a plan settled mid-cycle lives only in the conversation and dies with it. Plans for closed tasks accumulate in the live folder, so the folder stops indicating what is in flight.
+Without this skill, the context entries describe the repository the session opened with. A decision a plan settled mid-cycle lives only in the conversation and dies with it, and an entry naming a module the diff rewrote keeps stating what the module used to do.
 
-A handoff file has the same shape of gap as an unmarked outcome. A page a learning workspace produced and an operator already picked a destination for sits in gitignored scratch until something lands it, and the session that produced it is gone by the time a branch exists to carry the write. Left unfolded it reads as promoted while the destination holds nothing.
-
-The receipt half of that sweep was missing entirely. A review receipt was deleted per shipped branch while another kind of receipt was skipped, because the exclusion protecting the checklist and audit prefixes caught a third by accident. Nothing but an operator asking collected it, and a collection that waits on someone remembering to ask is one a folder outgrows, so the skipped population grew per shipped branch and never shrank until it was most of the folder.
-
-The trigger side carries a gap of its own. "Sync the docs" names either corpus to the person saying it, so a description leaving its corpus to the opening clause alone competes with its public-facing sibling on nothing the routing field states, and the planning surface the request was about goes untouched.
+The trigger side carries a gap of its own. "Sync the docs" names either corpus to the person saying it, so a description leaving its corpus to the opening clause alone competes with its public-facing sibling on nothing the routing field states, and the context folder the request was about goes untouched.
 
 The opposite gap opened from the same write. A fold allowed to touch the requirements record on every ship rewrote it one reasonable edit at a time, and nothing read it for whether it still stated the project's identity. Each ship looked correct and the sum drifted.
 
-This skill writes canonical docs at the end of a long build and never reviews what it wrote. An appended figure or a branch-narrated re-measurement lands unchecked the same way a session's own edits do, so what the fold produces carries the exact defect the standards it cites already ban.
+A fold that did everything at ship time hid its own job. It marked board outcomes, swept receipts, wrote the design record, and landed promoted pages, so a session invoking it to refresh the context entries ran ten steps and could not tell which one it had asked for.
+
+This skill writes canonical docs at the end of a long build. An appended figure, a branch-narrated re-measurement, or an entry pushed past its length lands unchecked the same way a session's own edits do, so what the fold produces carries the exact defect the standards it cites already ban.
 
 ## Must
 
-- Name the context entries and the task board in a trigger phrase rather than in the opening clause alone, so a bare request to sync the docs separates this skill from `docs-sync` on something both descriptions state
-- Take completion from the diff and everything else from the session, since completion is a fact about the repository rather than about the conversation
-- Match an outcome on the behavior it names, never on a filename or a commit subject
-- Leave an outcome unchecked when the diff is ambiguous. An unmarked shipped outcome costs one manual edit and a wrongly marked one hides work that never happened.
-- Write tracked docs at the current worktree root and the task board at the main root, since only the first commits with the branch
-- Count every other citation before archiving a plan, comparing resolved targets rather than raw strings or bare filenames
-- Retarget a closed task at the archived plan, so the reasoning behind finished work stays reachable
+- Name the context entries in a trigger phrase rather than in the opening clause alone, so a bare request to sync the docs separates this skill from `docs-sync` on something both descriptions state
+- Take decisions from the session and the refresh scope from the diff
+- Write tracked docs at the current worktree root, since only that copy commits with the branch
 - Write a decision to the domain context entry it constrains, whatever other domains its reasoning touches, so a decision has one home that loads on demand
 - Report a requirements or direction change in one line naming `document-health`, rather than writing it, so the identity record changes only when the operator reviews it
-- Leave the current branch's review receipt alone, since its branch is still live
-- Land each block of a promotion handoff at the destination its heading names, then delete the file so a later run does not fold it twice
-- Take a promotion destination as already decided, since the operator confirmed it where the page was produced
+- Close on an audit of what the fold touched, running `canon context audit` and reporting the findings on files this run wrote or the diff carries
 - Classify the fold's whole diff baseline through `canon context classify diff`, calling the verb rather than reimplementing its pattern or its prompt in the skill body, since an earlier commit on the branch carries a doc edit the fold is equally responsible for
 - Apply a `REPLACE` or `HISTORY` finding against the quote it names, report a `MOVE` finding naming the surface it belongs on rather than cutting it, or keep a finding with a one-line reason, rather than leaving a finding unanswered
-- Rewrite a restated or superseded statement in place rather than appending the replacement beside it, on every canonical doc type this skill writes
-- Report a refusal or a missing `context classify` subcommand as one line and continue the fold either way, since a check that cannot run is not a reason to leave the fold's own output unshipped
+- Rewrite a restated or superseded statement in place rather than appending the replacement beside it
+- Report a refusal or a missing `context audit` or `context classify` subcommand as one line and continue the fold either way, since a check that cannot run is not a reason to leave the fold's own output unshipped
 
 ## Must not
 
-- Infer a new task from the diff. Only outcomes already on the board get marked.
-- Touch task files the session did not change
-- Widen what a writing step reads when the baseline is unusable. Widening a read is safe and widening a write stubs a surface for every file in the repository.
+- Write the task board, the design record, `CLAUDE.md`, or a page from a promotion handoff. Each has its own owner, and a fold that writes them hides its job behind theirs.
+- Widen what the refresh reads when the baseline is unusable. Widening a read is safe and widening a write stubs a surface for every file in the repository.
 - Write the requirements record. It states identity, and a fold reads one session where a review reads the whole project.
-- Edit `CLAUDE.md` inline. Every change there goes through a diff-and-approve gate, so this skill only flags.
-- Create a context entry, or move or delete a plan. A plan is settled by the merge, and `canon tasks archive` carries it.
-- Overwrite a file a promotion block routes to. A destination that already holds a page is a merge for a person, and folding over it discards work this skill never read.
+- Create a context entry for a domain the catalog does not list
+- Report an audit finding on an entry this run never touched, which belongs to whoever next edits it
+- Add a path flag to the audit verb from this skill. It takes a project root, so the skill filters the record.
 - Pick or configure a classifier backend. The project setting decides it, and this skill reports the resolved `modelLayer` as returned.
-- Stop the fold on a classify finding, a refusal, or a missing subcommand. All three report and continue.
+- Stop the fold on an audit or classify finding, a refusal, or a missing subcommand. All of them report and continue.
 - Apply a finding against a quote found more than once or not found at all. Report that it could not be located instead of guessing.
 - Re-run the classifier after applying a finding, which loops it over its own edit
 - Cut a `MOVE` finding. The verdict means correct content sitting on the wrong surface rather than a deletion candidate, so cutting one can discard content that belongs elsewhere rather than removing detail that never belonged at all.
-- Scope Step 8 to the files Steps 3 and 5 wrote this run. An earlier commit on the branch carries a doc edit the fold is equally responsible for, and the verb's own extraction already answers whether anything in range qualifies.
+- Scope the classifier to the files Step 3 wrote this run. An earlier commit on the branch carries a doc edit the fold is equally responsible for, and the verb's own extraction already answers whether anything in range qualifies.
 
 ## Guards
 
 - Neither a `canon/` nor a `.claude/` directory: stop and name the command that sets one up
-- No session divergence and no queued outcome the diff shipped: stop with a pass, since both conditions have to hold
+- No session divergence and no diff a context entry could describe: stop with a pass, since both conditions have to hold
 
 ## Out of scope
 
-- Creating a task file or moving one off the board, which `task-board` owns
-- Public-facing docs, which `docs-sync` owns, apart from landing a page a promotion handoff already carries a confirmed destination for. This skill reconciles the context entries, the planning records, and the task board, and both descriptions name their corpus in the trigger so a request saying only "sync the docs" lands on one of the pair rather than on either.
-- Deciding where a promoted page belongs, which is settled with the operator by the surface that produced the page
-- Regenerating the task index, owned by a hook
+- Marking a shipped task's outcomes, sweeping review receipts, and archiving a task, which `task-complete` owns
+- Landing a page a teach promotion handoff carries, which `teach-workspace` owns in its fold mode
+- Creating or declining a task file, which `task-board` owns
+- Public-facing docs, which `docs-sync` owns. Both descriptions name their corpus in the trigger so a request saying only "sync the docs" lands on one of the pair rather than on either.
+- Regenerating the context catalog, which a commit hook runs