@erclx/canon 4.0.0

package/docs/agents/install-and-sync.md

@@ -0,0 +1,385 @@
+---
+title: Install and sync
+description: What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project
+---
+
+# Install and sync
+
+The behavior notes behind the verbs listed in `commands.md`. Each one records what the verb writes, what it refuses, and what it deliberately leaves alone.
+
+## Domain sync
+
+`canon gov sync` updates only rules already present under `.claude/rules/` and
+never adds new ones. A rule the toolkit does not ship is left alone, which is
+how project-authored rules survive, and one under `.claude/rules/project/`
+is left alone regardless of its name, since that subfolder is project-authored
+by location. It also removes a stale `.claude/GOV.md`
+from the retired build. Use `canon gov install` to add rules.
+
+A rule the toolkit finds no source for, sitting in a shared subdirectory rather
+than under `.claude/rules/project/`, is reported with the path under that
+subfolder it would take. The offer is conditional on the project having written
+the rule, since a rule the toolkit shipped and later renamed reaches the same
+line, and moving one there would mark it the project's for good. Nothing is
+moved either way, because a rule's installed path is one the project's own
+rules, skills, and docs may cite. `canon standards rule` carries the reserved
+number bands behind that placement, where `900-999` is the range a
+project-authored rule takes and everything below it belongs to the toolkit.
+
+`canon sync --check` does not report an orphaned entry. It skips every one, so
+the destination reaches `canon gov sync` alone, the one domain sync verb left.
+
+When the target's install recorded a stack, `canon gov sync` also reports a
+rule that stack lists and `.claude/rules/` does not hold, as a `missing` entry
+carrying no change. This is what makes a target whose recorded sync point
+postdates a rule joining its stack still see that rule: the report reads the
+target's current entitlement against its current tree rather than diffing
+from an anchor a later sync could advance past the rule's own commit. A
+target whose install predates the recorded chain falls back to the same
+band-inference `newRules` uses in `canon sync --check`.
+
+There is no `canon standards sync` and no `canon standards install`. The corpus
+installs into no project, so the domain has nothing in a target to reconcile.
+`canon standards <name>` prints one, resolving `standards/` at the working root
+and then the corpus inside the package, and `canon standards list --json` carries
+the catalog.
+
+There is no `canon snippets sync` and no `canon snippets install` either, on the
+same ground: `claude/snippets` in the plugin cache symlinks live to the
+toolkit's own `snippets/`, so a session reaches one at its `@` reference with
+no copy to reconcile. `canon snippets list --json` carries the catalog and
+`canon snippets create` is the one verb left that still writes a file.
+
+## Install guards
+
+`canon gov install` requires its first argument under
+`CANON_NON_INTERACTIVE=1`. It used to fall back to an interactive picker that
+resolved to its first option headlessly, so a call with no stack installed
+whichever stack sorted first. It now reports the valid names on stderr and
+exits 1.
+
+Every documented agent path already passes the argument, including
+`canon init`. The confirm-then-apply prompt after it still resolves to `Yes`
+headlessly, so a call that names its stack is unchanged.
+
+`canon gov install` also refuses the toolkit root as a target. It resolves the
+target before anything else, so a path that does not exist fails rather than
+being scaffolded.
+
+## Standards resolution
+
+`canon standards <name>` writes the document to stdout and the root it answered
+from to stderr, so a caller capturing with `$(...)` receives the document alone.
+A name resolves with or without its `.md` extension, and one that matches no
+standard exits 1 after listing the catalog on stderr.
+
+Two roots answer, in order: `standards/` at the working directory, then the
+corpus inside the package. A project that authors standards of its own uses the
+first, and this repository's own authoring root is the same path. `.claude/standards/`
+is not among them, and no repository writes one any more. A copy an older
+toolkit installed into a target resolves nothing.
+
+There is no citation closure to compute, since nothing is copied. A standard
+that hands a concern to a sibling names it in `Does not govern:` and a reader
+runs the verb again for that name.
+
+## Governance regen
+
+`canon gov regen` is the one governance verb that runs against the toolkit root,
+because the `.claude/rules/` it writes there is produced output rather than an
+operator's working copy. It reads the stack recorded in `internal/governance.toml`,
+installs it alongside anything under `internal/rules/`, and clears the
+destination first so a rule the record stopped naming disappears.
+
+It takes `--root <path>` and defaults to the toolkit root, prints nothing on success, and
+reports the reason on stderr with exit 1 when the record names a stack or rule
+that does not resolve. `scripts/core/regen-claude-copies.sh` calls it, and the
+Consumed copies stage of `bun run check` asserts the result is committed.
+
+## Whole-project sync
+
+`canon sync` runs every installed domain sync, then offers to commit the result
+and open a pull request. Under `CANON_NON_INTERACTIVE=1` it applies the domain
+syncs and then refuses the git workflow, reporting the branch and commit it
+would have created and exiting 0. Nothing is staged, committed, or pushed
+headlessly.
+
+Run it interactively to reach the commit and pull request options.
+It also refuses a target whose working tree is dirty, so commit or stash first.
+
+## Drift reporting
+
+`canon sync --check` reports drift and writes nothing, so it needs no clean tree
+and is safe to run at any time. Each file is classified as `stale` when it still
+matches what the toolkit installed, `customized` when the project edited it,
+`stranded` when it sits at a path the toolkit no longer installs to, `orphaned`
+when the project authored it, or `drifted` when no stamp covers it. Governance
+also reports `missing`, for a rule the target's recorded stack lists that its
+tree does not hold at all.
+
+Use `--json` for the machine-readable report and `--exit-code` to fail a CI job. Orphaned
+and missing files are both excluded from that exit code: a project-authored
+rule never converges, and a sync that added a missing one silently changes
+what the project is governed by, which stays a separate command an operator
+chooses to run. Attribution reads `.claude/canon/config.json`, which every
+install and sync writes.
+
+A target installed before stamping shipped has no such file, and neither does
+that fallback do anything to migrate it. A target stamped before the file
+moved into `.claude/canon/` still carries it at the retired
+`.claude/canon.json`, and `canon sync --check` reads that path when the current
+one is absent, reporting it rather than moving it. Only a target carrying
+neither path falls back to the toolkit's own git history.
+Installed content matching any
+version that history ever published proves the file is untouched, so it reports
+`stale` naming the commit it came from, and content matching no published
+version stays `drifted`. A toolkit reached outside a git clone, which is what a
+registry install is, cannot run that fallback and reports
+`historyUnavailable` alongside the unattributed files.
+
+Each domain carries its own toolkit anchor in that file, so syncing one domain
+never advances the revision another measures from, and each reports the upstream
+commits touching its own source path. The `covers` field names the domains a
+target has actually stamped, so a domain that was never stamped is legible
+rather than reading as a clean one.
+
+### Tooling
+
+Tooling records the stack chain an install resolved rather than per-file hashes,
+since `src/tooling/` runs its own inject machinery and has no walk to attribute.
+The chain is ordered nearest stack first, which is what a `--skip` run needs:
+recording the leaf alone would send the next report measuring against a layer the
+target deliberately does not carry. The report loads exactly those stacks, scans
+them the way `canon tooling sync` would, and counts what differs per category
+under `tooling.counts`.
+
+`measured` is the field the section exists for. A target carrying no chain
+reports `measured: false`, which separates tooling nobody has ever looked at from
+tooling that is current. Both produce zero changes otherwise. Every target
+installed before the record shipped starts unmeasured and leaves on its next
+`canon tooling sync`, since backfilling would mean inferring the chain from
+installed files, which is the guess the record replaces.
+
+A workspace root records nothing, because each package resolves its own chain and
+one written at the root would be that same guess. Run the check against a package
+to measure it. Tooling never counts toward `--exit-code`, on the grounds seeds
+are already excluded on, since it reports golden configs a project is expected to
+edit and a job counting those stays red with no remedy.
+
+### Surfaces reported beside the domains
+
+Six sections sit outside the per-domain scan, because each names something
+that walk cannot see: `seeds`, `superseded`, `unmigrated`, `newSkills`,
+`newRules`, and `reverse`. None of them produces a change, and no sync command
+applies any of them. The headings below group the first three together and give
+`newSkills` its description under `newRules`, which answers the same question
+about a different corpus.
+
+All six report only against a toolkit-managed target, which is one carrying a
+`.claude/` directory, a `CLAUDE.md`, or a domain still at the root layout. The
+report says so through `managed` in the JSON and routes an unmanaged directory to
+`canon init`. Seeds are why the gate exists, since they enumerate from the toolkit
+source rather than from what a target installed, so an unmanaged directory would
+otherwise report every seed as `missing`.
+
+A root-layout domain counts as a marker on its own, because the detection fires
+only on root files the toolkit ships and a project in the old layout is one the
+toolkit installed. When `managed` is false every section comes back empty rather
+than the render alone going quiet, so a consumer reading `--json` never acts on a
+finding the rendered half withheld.
+
+#### Seeds, superseded artifacts, and unmigrated domains
+
+`seeds` classifies every seed the toolkit ships against the target's copy, as
+`matching`, `stale`, `drifted`, or `missing`. `missing` has no per-domain
+equivalent, since the domain walk lists what a target installed and cannot see a
+file that never arrived. There is no `customized` verdict here, because that one
+needs a stamp and seeds carry none, so a file history cannot attribute stays
+`drifted`. Reconcile the section with `claude-seed-sync`, which merges one
+section at a time rather than replacing a file the project edits.
+
+A markdown seed installs rewritten rather than copied, since the `stub: true`
+marker the toolkit's own seed gate reads is stripped on the way in. The
+comparison above runs against what the install would write, so a marked seed a
+target never touched still reports `matching`. Every other seed copies byte for
+byte.
+
+`superseded` names a file a newer seed folder replaced, such as `.claude/TASKS.md`
+against the `.claude/tasks/` that now ships. The entry carries `replacedBy` and
+nothing else, and the file is never deleted, since the content belongs to the
+project and only its author can decide where it moves. The list derives from the
+seed tree rather than from a fixed set of filenames, so a folder added later is
+covered without a code change. Only an exact stem matches, which leaves a
+suffixed variant such as `TASKS-ARCHIVE.md` unreported.
+
+Route it to `migration-superseded`. That skill resolves the standard governing
+`replacedBy` from the `appliesTo` the standards catalog declares, reads the
+destination shape with `canon standards <name>`, and proposes the split without
+writing. Where a folder has no governing standard, the entry earns a named
+refusal rather than a shape nobody stated.
+
+`unmigrated` names a domain sitting at the root layout an older toolkit installed
+to, with nothing at the path the current one reads. It carries `rootPath`,
+`installPath`, and a file count. Without it a project holding `standards/` at its
+root reports zero entries for that domain and reads as clean, which is the most
+misleading state the report can produce.
+
+The field currently names no domain. Standards and snippets are the two the
+toolkit ever installed at a project root, and both closed their install channel,
+so a project still holding a root `standards/` or `snippets/` folder is carrying
+its own authoring surface rather than an unfinished install. Nothing proposes
+moving either, and no command relocates the content. Move it yourself.
+
+#### Rules the target never received
+
+`newRules` names a rule the target could receive and its tree does not hold. A
+sync refreshes the files a target already holds and adds none, so without this
+section a project's rule set freezes at its install date while every file it
+does hold reports as current. That is the report's most confident wrong
+answer, since a clean result reads as a target holding everything the toolkit
+publishes.
+
+The list rides beside `newSkills`, which asks the same question about the plugin
+catalog. Both are names rather than paths, and neither queues a change, because
+the two remedies differ: a skill loads live from the plugin directory and needs
+nothing run, while a rule reaches a target only when someone runs
+`canon gov install`.
+
+Read a clean section as reporting rather than as delivering. Nothing here
+installs, nothing counts toward `--exit-code`, and a target can read the list and
+act on none of it. The value stops at an operator reading it, which is the same
+contract the skills list already sets.
+
+Since `canon gov install` records the stack it resolved, a target carrying that
+record answers this by comparing its current entitlement against its current
+tree, with no anchor and no git diff involved. That is what lets the section
+name a rule that shipped before the target's last sync: the anchor a sync
+advances plays no part in the read, where an anchor-bound diff can never see a
+rule on the far side of a window a later sync moved past it. The per-file
+`missing` state `canon gov sync` reports comes from the same comparison, so a
+rule the chain lists reaches both surfaces the same way.
+
+A target stamped before governance recorded a chain falls back to the older
+band-inference read below. The measurement there anchors on governance's own
+stamp rather than on the oldest anchor across domains, since rules are
+domain-scoped and a shared anchor would let another domain's sync move the
+revision rules are measured from. A target carrying no chain and no governance anchor
+reports nothing at all: it has no date to measure against, and diffing from the
+start of history would read the whole catalog as new.
+
+An anchor this toolkit cannot resolve reports nothing by the same route, and that
+one is not visible. A stamp naming a revision the running clone has never seen,
+which is what a registry install without history or a shallow clone produces,
+fails the read and yields an empty list rather than a stated absence. It looks
+identical to a target holding every rule the toolkit publishes. `newSkills`
+behaves the same way, and neither carries the `historyUnavailable` flag the
+per-domain scan uses to separate the two. Treat an empty section on a toolkit
+that is not a full clone as unmeasured rather than clean. This gap does not
+reach the chain-based read above, since it consults no anchor at all.
+
+In the fallback, entitlement is filtered, because a stack does not receive
+every rule. The base stack takes the `core` and `claude` folders whole and
+every other stack extends it with individually named rules, so an unfiltered
+list would tell a base consumer about rules it can never receive and train the
+reader to skip the section.
+
+The filter accepts a band on either of two grounds. A folder the base stack takes
+whole is entitled to every target, read from the stack file so a folder added to
+base later needs no code change. Every other band is read off the folders the
+target already carries, which is the fallback's only evidence of what a target
+was entitled to before it recorded a chain. One band can be reached by more than
+one stack, so the test over-reports inside a folder the target holds, which
+costs a line where under-reporting would cost the section its point.
+
+A rule the target already holds is dropped by name. That is what keeps a rule the
+toolkit moved between band folders out of the list, since a rename reaches this
+read as an addition and only the name tells the two apart.
+
+This closes the dangling-citation case as a side effect rather than checking for
+one. The live instance is a rule citing a sibling authored after the target's
+install, and the section names the sibling as new rather than naming the citation
+as broken. That is enough for an operator to act on, and it is not a citation
+check.
+
+#### The reverse walk
+
+`reverse` is the one section built by walking the target rather than the
+catalog. Every other surface enumerates toolkit-owned keys and asks whether the
+target matches, so a folder the toolkit deleted appears in none of them. It
+carries `unclaimed`, `migrations`, and `historyUnavailable`.
+
+`unclaimed` names a folder the target holds at a top-level path the toolkit once
+shipped and has since deleted. The candidate roots come from the toolkit's own
+history rather than from a list, so a root dropped later is covered without a
+code change. Scoping to those roots is what keeps the walk useful: walking the
+whole tree reports every project folder as unclaimed, which is true and says
+nothing.
+
+The managed gate above applies here too, and it is the one place it surprises.
+A directory holding a dropped folder and nothing else reports an empty `reverse`
+rather than the folder, because it carries none of the three markers. Read an
+empty section on an unmanaged target as a walk that never ran rather than as a
+clean result.
+
+Each entry carries `rel`, a file count, and an `attribution` of `dropped`,
+`project`, or `unattributed`. A dropped folder and one the project wrote are the
+same bytes at the same path, so the verdict is traced from history rather than
+guessed from the filesystem.
+
+Content matching a version the toolkit published reads as `dropped` and carries
+the `since` commit that published it. Names the toolkit shipped holding content
+it never published read as `unattributed`, which is a state in its own right
+rather than a soft yes. No overlap at all reads as `project`, and the render
+drops those while the JSON keeps them.
+
+Only files whose path the toolkit once held are hashed, so a project folder
+colliding on a retired name costs the walk no reads. The cost is that a file the
+toolkit shipped and the target renamed goes unmatched, the same limit the
+`unmigrated` count carries.
+
+`migrations` names a proposal-only skill with a live case in this target. It
+fires on a `CLAUDE.md` past 250 lines for `migration-claude-md`, and on a `docs/` folder
+holding markdown with no populated `.claude/context/` for `migration-context`.
+Each entry carries the skill name and the measurement behind it, so a consumer
+can check the proposal before running it. Without the field both skills are
+documented and unreachable from any report.
+
+#### What counts toward the gate
+
+`unmigrated` counts toward `--exit-code`, since running the relocation closes it.
+`superseded` and every seed state are excluded, for the reason `orphaned` already
+is: only the user can move content they wrote, so failing a job on it leaves the
+job red with no mechanical remedy.
+
+`newRules` is excluded on a different ground, since a command does close it. What
+excludes it is that installing a rule changes what a project is governed by, so
+gating on the count would pressure a target into adopting rules nobody chose.
+`newSkills` is excluded because it needs no command at all.
+
+The whole `reverse` section is excluded on the same grounds, and more strongly.
+Every entry in it is a judgment about a file the project may own, and one of its
+three verdicts is a labelled unknown by design. The unmigrated detection shipped
+that exact false positive once, failing a push with no action that cleared it,
+so this section reports and gates nothing.
+
+## Bootstrap
+
+`canon init` installs up to four core domains and reports each one independently. A
+domain that fails does not abort the run, so the command finishes the rest and
+exits 1 naming the failures. Passing any flag skips the confirmation prompt,
+which is what makes it scriptable.
+
+`--stack` defaults to `base`, and the default
+does not read as a passed flag, so a bare `canon init` installs governance and
+still prompts. `--skip` takes `wiki` and `governance`, and warns
+without aborting on any other value. There is no `--standards` and no
+`--snippets`, since no run writes either corpus into the target.
+
+## Unguarded tooling primitives
+
+`canon tooling inject` and `canon tooling prune-gitignore` are the unguarded
+primitives beneath `sync`. They apply one stack with no scan and no prompt, and
+they deliberately skip the check that rejects `claude`, which is how `canon
+claude` drives its own stack through them. Use `sync` unless you are scripting
+provisioning. Both frame their own output, so pass `--nested` when calling from
+inside an already-open frame.

package/docs/agents/intake.md

@@ -0,0 +1,81 @@
+---
+title: Intake
+description: Reading intake folder counts and items, the three read states an item can be in, landing a batch of selections in one cluster, the refusal reasons, and why a call is scoped to one file
+---
+
+# Intake
+
+## List
+
+`canon intake list` reports the intake folders under `.claude/intake/`, or the items one folder holds. It reads and never writes, because an answer belongs to the operator and a verb that filled one would decide what the folder exists to ask.
+
+A folder carries a two-digit ordinal ahead of its slug, as in `21-toolkit-overview`, so a listing sorts by when each opened. A bare slug still resolves: passing `toolkit-overview` matches the one folder whose name is an ordinal ahead of it, and the folder's real name is what every command reports back.
+
+```bash
+canon intake list
+canon intake list toolkit-overview --unread --json
+```
+
+| Option          | Behavior                                                                  |
+| --------------- | ------------------------------------------------------------------------- |
+| `--unread`      | Keep only what is unread: folders carrying one, or a folder's empty slots |
+| `--json`        | Emit a machine-readable record on stdout                                  |
+| `--root <path>` | Intake root, defaulting to the main worktree                              |
+
+With no slug it reports per-folder counts. With one it reports every item grouped by the cluster file holding it, each carrying its label, title, open question, suggestion, and answer.
+
+An item sits in one of three read states, and the counts keep them apart:
+
+| State     | What it means                                           |
+| --------- | ------------------------------------------------------- |
+| unread    | The slot is present and empty, so nobody has reached it |
+| answered  | The slot carries text, which is a decision already made |
+| malformed | The item carries no slot, so no verb here can answer it |
+
+The third is counted apart from both rather than folded into either. Counted as answered it hides a file that needs fixing behind a folder reading as fully worked through, and counted as unread it joins a list whose every entry `answer` then refuses.
+
+The index is skipped, since it points at items and answers nothing itself. So is any item a file displays inside a fence, which is how a folder copying the item format into its own overview is read as the sample it is rather than as an item offering a slot no reader owns.
+
+## Answer
+
+`canon intake answer` writes selections into the answer slots of one cluster file.
+
+```bash
+canon intake answer toolkit-overview --cluster 05-coverage.md --set 3=ok
+canon intake answer toolkit-overview --cluster 11-intake-skill.md --set 3d=ok --set 9="not worth it" --json
+```
+
+| Option                | Behavior                                              |
+| --------------------- | ----------------------------------------------------- |
+| `--cluster <file>`    | Cluster file the items live in, with or without `.md` |
+| `--set <item=answer>` | Answer to land on an item, repeatable                 |
+| `--json`              | Emit a machine-readable record on stdout              |
+| `--root <path>`       | Intake root, defaulting to the main worktree          |
+
+Items are labeled per cluster file, so a selection names the cluster and the label together. A label alone names an item in every cluster at once.
+
+A label may carry a letter suffix, as in `3a` beside `3`, which is how a pass records a finding split after the fact rather than renumbering every item below it. Pass it exactly as the heading spells it.
+
+One call writes one cluster. A call per selection is the alternative, and several of those against the same file read it before any of them writes, so every answer but the last is lost with nothing reporting it. The selections split on the first `=`, so an answer carrying its own survives intact.
+
+An item already carrying an answer refuses rather than being overwritten, and one filled item refuses the whole batch, so a partly applied write never lands. Drop the named item and send the rest.
+
+Exit codes: `0` every named item now carries its answer, `1` refused. The `reason` field carries `no-intake`, `no-folder`, `ambiguous-slug`, `no-cluster`, `no-item`, `answered`, or `bad-input`. A bare slug matching more than one ordinal-prefixed folder refuses as `ambiguous-slug` rather than `no-folder`, naming every match in `detail`.
+
+An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's `reason` rather than the exit when a skill consumes this, which matters most here because the verb writes.
+
+`bad-input` covers a malformed command line: no cluster, no selection, a selection that parses to no label and answer, an empty answer, an answer carrying a line break, or two answers for one item. It is separate from the reasons describing the folder, so a caller that mistyped a flag is not sent to repair a file that is fine.
+
+An empty answer refuses rather than writing an empty slot. The slot means unread while it is empty, so writing one back would report an item as answered that nobody decided.
+
+An answer occupies one line, and one carrying a line break refuses before anything is read. Writing it splices a bare continuation into the item that matches none of the patterns the reader tests, so the slot reads back as the text before the break while the item counts as answered, and the refusal on an already-answered item then leaves hand-editing the file as the only correction. The whole batch refuses, so a good selection beside a broken one never lands half applied.
+
+The folder is shared scratch at the main worktree root, so `--root` defaults to the first entry of `git worktree list` rather than the working directory. The write is an edit inside a file that already exists, which `Edit` and `Write` refuse from a linked worktree and a shell stream editor may not do, so the verb resolves the root in-process and rewrites whole lines.
+
+Skills branch on the reason rather than on the exit code:
+
+```bash
+canon intake list toolkit-overview --unread --json | jq -r '.clusters[] | .cluster'
+```
+
+For the folder layout, the item format, the answer contract, and retrieval, see `standards/intake.md`.

package/docs/agents/key-changes.md

@@ -0,0 +1,103 @@
+---
+title: Key Changes bijection
+description: Comparing the files a pull request body's Key Changes names against its own diff, the two directions and why they are graded apart, the span rules the extractor was measured into, and the three refusals that separate a clean pass from a read that produced nothing
+---
+
+# Key Changes bijection
+
+`canon pr key-changes` reads the `## Key Changes` section of a pull request body, lifts the paths its bullets claim, and compares that set against the files the pull request actually changed. This repository squash-merges, so the body becomes the commit message and the record on the trunk once the branch is gone.
+
+```bash
+canon pr key-changes
+canon pr key-changes 1265 --json
+canon pr key-changes --body .claude/.tmp/pr/body.md --base origin/main
+```
+
+The positional is the pull request to read, defaulting to the one open on this branch.
+
+| Option          | Behavior                                                           |
+| --------------- | ------------------------------------------------------------------ |
+| `--body <path>` | Read the body from a file, taking the changed set from git instead |
+| `--base <ref>`  | Far side of the range when `--body` supplies the body              |
+| `--root <path>` | Repository to read, defaulting to the cwd                          |
+| `--json`        | Add a machine-readable record on stdout, keeping the frame         |
+
+`--body` decides where both halves come from, so a number passed beside it is never read. The body comes off disk and the changed set from the local range, which is the shape a fixture and a body still being drafted both need.
+
+Without `--body` the body, the file list, and the head commit come back from one `gh pr view` call, because the three have to describe the same commit and reading them apart leaves a window where a push between them compares a body against another head's files.
+
+That view caps its file list at 100 rows and says nothing about having done so, which was measured against `#1250`: the pull request carries 101 files and the view reports 100. A pull request at the cap therefore takes a second read through the paginated endpoint, and a failure there refuses with `gh-truncated` rather than comparing against a set known to be short. A set silently one file short is the worst input this takes, since the missing file is exactly what a correct bullet would then be accused of inventing.
+
+## The two directions
+
+They are reported apart because they want different tolerances.
+
+- **`unmet`** is a whole path the body claims and the diff does not carry. This is the graded direction and it sets the exit code. A bullet naming an untouched file is wrong more often than not, and it corrupts the record that reaches the trunk.
+- **`unnamed`** is a changed file no bullet reached. Reported with no grade, since the class covers a real omission and equally a lockfile, a generated asset, or a regenerated index that earns no bullet. Grading it would fire on nearly every branch.
+- **`unresolved`** is a path written partially, such as `claude-worker/SKILL.md` for a file under `claude/skills/`. It is judged in neither direction.
+
+A partial path can credit a changed file and can never accuse one. Nothing separates a path written short from a path written wrong, so the asymmetry keeps the accusing direction to spans the tree can anchor.
+
+## What counts as a claim
+
+Only `## Key Changes` is read. `## Technical Context` legitimately names files a branch never touched, such as an install stamp inside a target, so widening the read manufactures a finding out of every argument an author made for the change.
+
+Inside the section, the claim region of a bullet ends at its first comma outside a backticked span. That one lever was chosen by measurement. Over the 23 merged pull requests in this repository carrying the section, reading whole bullets reported 16 paths as claimed-but-untouched and every one was a file the body named for context. Cutting at the comma left 110 claims of the original 149 and took the false reports to 2. A list of sixteen clause-opening words tried beside it removed nothing the comma had not already removed, because this corpus punctuates every one of them.
+
+A span inside the claim region has to survive all of these:
+
+| Rule                                              | What it keeps out                                      |
+| ------------------------------------------------- | ------------------------------------------------------ |
+| No whitespace, `<`, `>`, `$`, `*`, `\|`, `?`, `^` | A backticked command, a placeholder, a glob, a pattern |
+| No `://` and no leading `/`, `~`, `@`, `#`, `!`   | A URL, an absolute path, a module alias                |
+| Contains `/`                                      | A bare filename with no folder around it               |
+| Extension starts with a letter, or ends with `/`  | A dotted number such as an address                     |
+| Not a single top-level folder                     | `src/`, which nobody claims to have rewritten whole    |
+| A `file:line` span leads its bullet               | A citation into a file the bullet is describing        |
+| The region carries no no-change marker            | A bullet recording a file it deliberately left alone   |
+
+The last three rows earn their place from the corpus rather than from a rule. Every body that spelled a lone top-level folder was naming where something lives, and a line citation that follows another claim in the same bullet points into the file being described rather than naming a second one. A line citation leading its bullet stays a claim, which is how a body names the exact line it rewrote.
+
+The no-change marker is the one rule the region cut cannot substitute for. A body writes "Leave `x` untouched, since the decision keeps it" to record a change it declined, and the path sits ahead of the first comma, so a stricter cut would not reach it and a looser one would find more. Since `keep` and `leave` each open a real claim often enough, the marker decides it rather than the leading verb. Three words carry the set: `untouched`, `unchanged`, and `as written`. `in place` was measured and dropped, because rewriting a file in place is an ordinary claim, and `no other line` was dropped because a correct bullet writes "as one insertion that touches no other line" about a change it did make. `alone` shipped in the set too, until review found every corpus occurrence sitting past the first comma, where the cut already excludes it, so the word voided no true claim there. Restrictive use is the more common one in this repository's own prose, and a comma-free bullet exposed it: "Move the threshold read into `src/gate/stages.ts` alone" asserts an edit, and the marker voided it while the word was still in the set. Over the 40-pull-request corpus the rule still voids no true claim.
+
+A folder claim covers every changed file beneath it. A bare filename drops outright: resolved as a sibling of a path earlier in its bullet it produced seven wrong paths across this corpus against two right ones, because a compound bullet names a sibling folder as often as a sibling file.
+
+## Anchoring
+
+A claim is anchored when its first segment names a folder the tree holds. The roots come from the tracked file list joined with the first segment of every changed path, and the second half is what admits a folder the branch created. Reading the tree alone would mark every claim under a new top-level directory unanchored, and an unanchored claim never accuses, so the first branch to open one would lose the graded direction with nothing reporting it.
+
+## Exit codes and refusals
+
+| Code | Meaning                                           |
+| ---- | ------------------------------------------------- |
+| `0`  | every claimed path is in the diff                 |
+| `1`  | refused, with `reason` naming the cause           |
+| `2`  | at least one claimed path is absent from the diff |
+
+Branch on the record rather than on the exit code. A shell function wrapping `canon` takes its status from whatever it runs last, so every non-zero exit can reach a caller as zero.
+
+Three refusals separate a clean pass from a read that produced nothing:
+
+- `no-section`. The body carries no such heading, so it claims nothing.
+- `no-claims`. The heading is there and no span resolved, which is the extractor failing over prose rather than the body being wrong. Nothing is raised.
+- `no-changes`. The pull request changed no files, so no claim has anything to answer.
+
+An empty extraction read as a clean pass is the failure shape this repository has recorded twice, which is why the middle one is its own reason rather than a zero count.
+
+`gh-missing`, `gh-failed`, `gh-truncated`, `unreadable-body`, `unreadable-tree`, `no-base`, `bad-base`, and `unreadable-changes` cover the reads that never reached a comparison.
+
+## What it was measured against
+
+Driven over the 40 most recent merged pull requests in this repository, 23 of which carry the section, the shipped verb reported zero unmet paths and one `no-claims` refusal. The naive extractor it replaced reported 16.
+
+The first body written after that corpus closed produced two, which is what the no-change marker and the open class above come from. One was the disclaiming bullet and the rule now covers it at no cost to the corpus. The other is the definition-site class, left open with the report naming it.
+
+The bound is that the corpus is one repository writing to one house style. A project that punctuates differently loses claims to the comma cut rather than gaining false ones, since every rule above drops rather than invents, so the check degrades toward silence rather than toward noise.
+
+What it cannot see is a bullet claiming a change to a file the branch did touch for another reason, a path written without backticks, and a claim in a second coordinated clause after the comma. The last of those falls to the ungraded direction rather than out of the reading.
+
+One class stays open and is named rather than closed. A bullet can cite where something is defined while claiming an edit somewhere else, as `#1274` does with "Name the slug transform in `standards/slug.md` inline in the same step". The path is a definition site, the edit target is the step, and separating the two needs the sentence parsed rather than cut. A finding on such a bullet is this class rather than a stale claim, and a reader weighing an `unmet` path checks whether the bullet's real target is a locative the path does not name.
+
+## Where it runs
+
+`claude-pr-review` Step 3 calls it and files an `unmet` path as a `should-fix` finding under the `**PR body**` block the stale ticked box already takes, since what both corrupt is the merge record rather than a file in the diff. A body is edited between pushes, so a finding names the head the comparison ran at.

package/docs/agents/label-coverage.md

@@ -0,0 +1,73 @@
+---
+title: Label coverage
+description: Reading a changed set against the pull request label map, the two tables it matches, how a gap is separated from a decision, and why an absent map is an answer
+---
+
+# Label coverage
+
+`canon labels audit` resolves the paths a branch changed against the label map a project declares, reports the labels the set earns, and names every path no row reaches. It closes a gap the map's own comment had predicted since the map shipped: nothing detected a surface added after the rows were written, so such a branch merged carrying no label and nobody heard about it.
+
+```bash
+canon labels audit
+canon labels audit --json
+canon labels audit --base origin/main
+canon labels audit src/cli.ts docs/index.md --json
+```
+
+| Option          | Behavior                                                          |
+| --------------- | ----------------------------------------------------------------- |
+| `--base <ref>`  | Far side of the range, defaulting to the merge base against trunk |
+| `--root <path>` | Repository to read, defaulting to the current directory           |
+| `--json`        | Add a machine-readable record on stdout, keeping the frame        |
+
+Positional paths replace the range entirely. A caller holding a changed set already passes it rather than paying for a second git read, and the record then omits `base` to say the range was never resolved.
+
+Under `--json` the record holds stdout alone and the frame still renders on stderr, refusals included, which is the split `output-shape.md` fixes for every mode.
+
+## The map it reads
+
+The map sits at `.claude/canon/pr-labels.toml` and carries two tables. `[domains]` keys a label name to the path prefixes that earn it, and `[declined]` keys a reason to the prefixes that earn no label on purpose.
+
+```toml
+[domains]
+api = ["services/api/"]
+web = ["apps/web/", "packages/ui/"]
+
+[declined]
+release-managed = ["CHANGELOG.md", "package.json"]
+generated = ["build/manifest.json"]
+```
+
+Matching is prefix-anchored, so a row written for an authoring root reaches nothing under the copy a project consumes. A path claimed by rows in both tables takes the label, since it already has a subject and reporting it as deliberately unlabelled would contradict the label the same run applies.
+
+## A gap and a decision are different findings
+
+The verb sorts every changed path into three buckets and keeps two of them apart:
+
+- **Labelled.** At least one `[domains]` row reaches the path. It contributes its label and nothing else.
+- **Declined.** A `[declined]` row reaches it. Somebody already decided the path earns no label, so the run names it and moves no exit code.
+- **Uncovered.** Neither table reaches it. This is the finding, and it wants either a prefix on the row that owns its subject or a `[declined]` row carrying the reason.
+
+Folding the last two together was the shape this replaced. A report that cannot tell a surface nobody has gotten to from one somebody refused is useful about neither, which is why the declined half moved out of the map's trailing comment and became data the command reads.
+
+## The range it reads
+
+The default range is the branch against the trunk, resolved as the merge base against `origin/main` and then local `main`. The changed set is that base diffed against the working tree, plus untracked files git does not ignore, rather than against `HEAD`.
+
+Reading the working tree is what lets the check run before the branch commits, which is the moment a session adds the surface nobody covered. The set is a superset of `base..HEAD`, so a caller running after the commits still sees the whole branch.
+
+## Exit codes and refusals
+
+| Code | Meaning                                        |
+| ---- | ---------------------------------------------- |
+| `0`  | every changed path is labelled or declined     |
+| `1`  | refused, with `reason` naming the cause        |
+| `2`  | at least one changed path is reached by no row |
+
+It reports and never gates. Whether an uncovered surface deserves a label is a judgment only whoever owns that surface can make, and a push failing on one teaches a contributor to route around the check while nothing about the surface has changed.
+
+A project declaring no map refuses with `no-map`, which is an answer rather than a fault. Such a project is labelled silently by design, and treating the absence as a break would make the map mandatory for every target. `canon audits run` reads that one reason as an expected absence and every other refusal as a measure that did not run.
+
+## What it does not measure
+
+A prefix reaching no path is invisible here. A row left behind by a deleted folder stays in the map forever, and this verb has nothing to say about it. That is the map going stale from the other side and a second measure rather than this one.