@erclx/canon 4.0.0

package/docs/agents/review-classification.md

@@ -0,0 +1,77 @@
+---
+title: Review classification
+description: Deciding whether a changed set needs the review pass, the two tests it runs, why an empty set refuses rather than skipping, and the written fallback a target on an older binary falls back to
+---
+
+# Review classification
+
+`canon autoship classify` answers the one decision the ship chain used to make by reading a bulleted list out of a skill body. It takes the names a branch changed and returns whether the review pass can be skipped, which file decided it, and which of the two tests that file failed.
+
+```bash
+canon autoship classify docs/index.md README.md
+canon autoship classify --json .claude/skills/deploy-check/SKILL.md
+```
+
+| Option   | Behavior                                                   |
+| -------- | ---------------------------------------------------------- |
+| `--json` | Add a machine-readable record on stdout, keeping the frame |
+
+Positional paths are the whole input. The verb never touches git, so it reads no baseline of its own and the caller hands over the set it already computed. A second read here could resolve a different range than the one the chain measured, which is the stale-baseline failure a prior row closed.
+
+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 two tests
+
+A branch skips review only when both hold across every changed name:
+
+- **Every path reads as prose.** The extension is `.md` or `.txt`, compared lowercased. Anything else is code, a config, or an asset.
+- **No path sits under a behavior path.** Markdown under one of those surfaces states what an agent does, so a change there is a behavior change wearing a prose extension.
+
+One failing file sends the whole branch to review. Documentation shipped beside a behavior change does not cancel it.
+
+The record names the first file to fail, tested in the caller's own order, and each file is read for its extension before its path. A set failing both tests reports one file and one test, which is all a caller needs to route.
+
+## The behavior paths
+
+Most carry two spellings, the one a surface authors at and the one it reaches a session at, so the rule reads the same in this toolkit and in a project that consumed one.
+
+| Surface           | Spellings                             |
+| ----------------- | ------------------------------------- |
+| Plugin skills     | `claude/skills/`, `.claude/skills/`   |
+| Governance rules  | `governance/rules/`, `.claude/rules/` |
+| Standards         | `standards/`                          |
+| Snippets          | `snippets/`                           |
+| Internal and seed | `internal/`, `tooling/`               |
+| Root instructions | `CLAUDE.md`                           |
+
+`standards/` and `snippets/` carry one spelling apiece. Neither installs into a project, reaching a reader by resolution and through the `claude/snippets` symlink respectively, so there is no consumed copy to name.
+
+`CLAUDE.md` is matched as a whole path rather than as a prefix, because a prefix reaches nothing that sits in no folder. A nested `docs/CLAUDE.md` stays informational.
+
+The set is data at `src/autoship/paths.ts`. That makes it permanently exempt from any later design that folds a machine-parsed list back into the surface citing it, per the machine-parsed clause in `.claude/ARCHITECTURE.md`.
+
+## Exit codes and refusals
+
+| Code | Meaning                                                      |
+| ---- | ------------------------------------------------------------ |
+| `0`  | prose-only, so the review pass can be skipped                |
+| `1`  | refused, with `reason` naming the cause                      |
+| `2`  | review is needed, with `file` and `test` naming what decided |
+
+Branch on the record's `decision` 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.
+
+An empty set refuses with `no-changes` rather than skipping. Both tests are universally quantified, so an empty set satisfies them vacuously, and reading that as prose-only would route a branch past review for having produced no output at all.
+
+## Why it is a verb
+
+The decision was three sentences in `claude-autoship` Step 5, applied by a session reading a bulleted list of paths. It failed three times. A driven arm on 2026-08-30 staged `.claude/skills/deploy-check/SKILL.md`, which that list names, and the chain skipped review and opened a draft pull request anyway. The rule was correct and the session did not apply it, and the two fixes before that one were each a rewrite of the same prose.
+
+A rule a session can talk itself out of moves into a verb. That is the same argument the quiz-order draw in `canon teach lesson` was decided on: an instruction is a hope where a verb is a check.
+
+## The written fallback
+
+The verb ships with the CLI and Step 5 ships with the plugin, so a target holding an older binary meets a missing subcommand. The skill body keeps the written list and applies it by hand there, naming which of the two decided the run.
+
+The fallback is never a skip. Failing open is the exact defect the verb closes, so a body that skips on anything other than a `skip` record would ship every branch unreviewed the moment the subcommand went absent.
+
+Two copies of the path set is what the fallback costs, and it stands until a release retires the written half.

package/docs/agents/routing.md

@@ -0,0 +1,61 @@
+---
+title: Routing report
+description: Reading per CLAUDE.md section how many bullets name a path, what counts as naming one, when a rule counts as covering it, the two refusals, and why the verb reports rather than gates
+---
+
+# Routing report
+
+`canon claude routing` reports, per `CLAUDE.md` section, how many top-level bullets name a path and how many of those a path-scoped rule already covers. It answers the firing axis of the tier test in `.claude/rules/claude/592-claude-md.md`, whether a fact applies every session or fires on one path, and which until this verb existed was a judgment nothing counted. `.claude/ARCHITECTURE.md` names two further axes, conditional presence and updatability, that this verb does not check.
+
+```bash
+canon claude routing
+canon claude routing --json
+canon claude routing ../my-app
+```
+
+| Option   | Behavior                                                     |
+| -------- | ------------------------------------------------------------ |
+| `[path]` | Repository root to read, defaulting to the current directory |
+| `--json` | Add a machine-readable record on stdout, keeping the frame   |
+
+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 root is the argument rather than the toolkit, matching the reach and drift verbs, so a linked worktree reads its own branch and a target reads its own file.
+
+## What it reads
+
+Every H2 and H3 owning at least one top-level bullet. An H3 is reported under the H2 containing it, as `Behavior / Scope discipline`, so a section and its subsections are counted apart rather than summed.
+
+Three things are read past. A nested bullet belongs to the one above it rather than to the section. A bullet inside a fenced block is example text rather than instruction. A heading carrying no bullet answers nothing the report asks, so it is dropped rather than listed at zero.
+
+## What counts as naming a path
+
+A bullet is path-scoped here when it names a path. That is evidence for the tier judgment rather than the judgment itself, and the gap runs both ways: a bullet naming a folder can still apply every session, and one firing on a path it never spells is invisible to the count. Read a section's number as a place to look rather than as a verdict on it.
+
+A backticked token counts when it carries a separator or an alphabetic extension, which admits `src/cli.ts` and `cspell.json` while leaving a flag, a bare word, and a version string out.
+
+A shape counts as the folder above its placeholder. `.claude/context/<domain>.md` names `.claude/context/` and nothing narrower, so dropping the token whole would report the section carrying it as naming no path at all. A placeholder opening the first segment has no openable prefix and is dropped.
+
+## When a rule counts as covering it
+
+A rule covers a named path only when its glob anchors to a location. 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.
+
+The corpus-wide markdown rules are what force that. Counting one reports every markdown path as covered, which collapses the column to a constant and tells a reader nothing about which folder somebody actually scoped a rule to.
+
+A folder is probed with a handful of extensions rather than matched literally, because a glob narrowed by file type reaches under a folder without ever matching the folder's own name. Globs are read from each rule's frontmatter block alone, so a rule quoting a path in its body does not register a scope it never declared.
+
+The paths a section names that no rule reaches are listed beside it, which is where a reader looks first when deciding what a new rule would cover.
+
+## Refusals
+
+Two, each naming what a reader does about it. `no-claude-md` is a tree with no always-loaded file. `no-rules` is a tree carrying no path-scoped rule under `.claude/rules/`, where every path would report as uncovered and the column would say nothing.
+
+An always-on rule declaring no `paths` is skipped rather than refused. It applies at the same priority as the always-loaded file, so it covers no path in particular.
+
+## Exit codes
+
+Exit codes are `0` when the file was read and `1` for a refusal. No finding moves the exit code.
+
+Nothing wires this into `bun run check` or into a hook. Whether a bullet belongs in a rule is a judgment, and gating a measure that counts a judgment forces an escape hatch for every deliberate case.
+
+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 JSON record's `sections` array rather than the exit when a skill consumes this.

package/docs/agents/rule-citations.md

@@ -0,0 +1,98 @@
+---
+title: Rule citations
+description: Resolving every path a governance rule cites and every frontmatter glob the internal corpus declares, the three forms a citation is written in, the shapes that look like citations and are not, the two classes where an absent path is correct, why the glob half reads one corpus, and why this one gates
+---
+
+# Rule citations
+
+`canon gov citations` resolves every path a rule cites and every frontmatter glob the internal corpus declares, naming the ones reaching nothing. It answers a failure no other stage sees: a rule points a reader at a file, the file moves, and nothing reports it until a session opens the path and finds an absence.
+
+A glob fails the same way and more quietly. A rule scoped at a directory that moved stops matching, so it never loads again, and a rule that never fires looks exactly like a rule nobody violated.
+
+```bash
+canon gov citations
+canon gov citations --json
+canon gov citations --root ../my-app
+```
+
+| Option          | Behavior                                                   |
+| --------------- | ---------------------------------------------------------- |
+| `--root <path>` | Tree to read, defaulting to the current directory          |
+| `--json`        | Add a machine-readable record on stdout, keeping the frame |
+
+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.
+
+## What the drift check cannot see
+
+`bun run check` asserts that an authored rule and its consumed copy agree, and a dead citation passes that assertion because both copies carry it. `governance/rules/claude/561-teach.md` told its reader to open a `references/glossary.md` inside the teach skill that had never existed at that path. The rule shipped, survived a release, and fired during a real teach run before anyone noticed.
+
+Two files agreeing is what a drift check measures. Whether either one is right about the tree is a different question, and this is the stage that asks it.
+
+## The three forms
+
+A citation reaches a reader in one of three shapes, and each resolves against a different root.
+
+| Form       | Shape                    | Resolves against                   |
+| ---------- | ------------------------ | ---------------------------------- |
+| `standard` | `canon standards <name>` | `standards/<name>.md`              |
+| `path`     | a backticked path        | the root                           |
+| `sibling`  | a bare `<nnn>-<slug>.md` | the folder the citing rule sits in |
+
+`standard` is the live form and carries most of the corpus, which is what makes scoping this check to the two path shapes a check over almost nothing.
+
+A standard name resolves against the authoring root and nowhere else, matching `standardRoots` in `src/standards/read.ts`, which reads `standards/` at the working root and then the package corpus. The stage refuses a tree holding no rule corpus, so it runs only where those two roots are one directory. `internal/standards/` is deliberately not tried: `canon standards <name>` never reaches it, so admitting it would pass a citation that refuses for the session opening it, which is a gate failing open.
+
+A `path` is anchored on the whole backticked span rather than on a trailing pattern inside it. Cutting `standards/tooling-reference.md` out of `internal/standards/tooling-reference.md` and resolving that against the standards root reports a file that exists as missing, which is a mistake made by hand while measuring this corpus before the stage was written.
+
+## What is not a citation
+
+A rule body is full of backticked spans carrying a slash, and almost none of them names a file in this tree. The stage declines four shapes outright.
+
+- A placeholder or glob segment describes a shape rather than naming a file: `.claude/context/<domain>.md`, `standards/<name>.md`, `app/**/route.ts`, `${CLAUDE_SKILL_DIR}/../../standards/<name>.md`.
+- A bare filename names a convention: `route.ts`, `manifest.toml`, `components.json`, `playwright.config.ts`. A bare name is read as a citation only when it matches a rule filename, which is how `562-session.md` points at `555-tasks.md`.
+- A span carrying no file extension is a folder or a module specifier: `src/pages/`, `next/font`, `try/except`, `react-hooks/set-state-in-effect`, `oven-sh/setup-bun@v2`, `@/lib/utils`.
+- A fenced block displays a path rather than pointing at one.
+
+The extension test is what carries most of the separation, and it costs one real path: `claude/standards` is a symlink this stage declines to check because nothing in the span says it is a file. Declining is the right direction for a gate, where a guess that goes wrong fails a push over prose.
+
+## Where an absent path is correct
+
+Two classes resolve to nothing and are right to. Both are reported by name rather than dropped, so a reader can see what the verdict declined to judge.
+
+**Governed.** A rule spelling a path in its own frontmatter `paths:` is naming an artifact a target holds rather than a file here. `governance/rules/claude/560-diagrams.md` declares `.claude/DIAGRAMS.md` and then tells its reader to convert one an older install left behind, so the file is correctly absent from this tree and correctly named in the rule.
+
+Only an exact declaration exempts, never a glob match against one. A glob declares a shape, so a body path sitting inside it is still a citation and a stale one is still a defect. A rule scoped at `docs/**` citing a `docs/agents/renamed.md` that moved is exactly the class this stage exists to catch, and matching the glob would excuse it.
+
+**Ignored.** A path git ignores is session scratch no clone is expected to hold. `governance/rules/claude/555-tasks.md` cites `.claude/tasks/index.md`, which is real in a live project and absent from a fresh clone and from every linked worktree. Resolving against the filesystem alone would make the verdict depend on which tree the stage ran in, so the unresolved paths go to one batched `git check-ignore` and an ignored one is excused. A read git cannot answer refuses rather than reporting those paths dead.
+
+## Why the glob half reads one corpus
+
+Bodies are read across both corpora and frontmatter globs across `internal/rules/` alone.
+
+A rule under `governance/rules/` installs into a target, and its `paths:` entries name the shape that project holds rather than anything here. Measured over that corpus, 32 of its 72 globs match nothing in this tree and every one of them is correct. `src/pages/**` in the Astro rule cannot be told by pattern from a path this repository might hold, so a check cannot separate the two, and gating them would ship an exemption list the length of the corpus. Nothing reads the shipped globs, and the measurement is the reason rather than a gap left for someone to close.
+
+`internal/rules/` ships nowhere. The tree it governs is the tree present, which makes the question answerable, and all 14 of its globs across 7 rules match at the commit this shipped on.
+
+What that leaves unreached is a glob that matches real files and still reaches none of the work it was scoped at. `governance/rules/lib/305-e2e-reliability.md` scopes itself at `e2e/*.ts` and `e2e/**/*.ts`, and no probe in this repository is written under `e2e/`, so the rule asking a session to watch a new guard fail never fired for the session writing guards. Resolution is mechanical and reach is a judgment about where the work happens, so only the first is here.
+
+## The exemption marker
+
+Everything the classifier can separate mechanically is separated there. For the residue, a line carries `canon-allow-citation: <reason>` on itself or the one directly above, which moves it into the report's `Exempt` section. Only a marker naming a reason counts, since a bare token is a line that meant to say something and did not. This is the `canon-allow-superseded` shape, and both read the same placement rule through one helper.
+
+## The blind spots
+
+A citation that resolves and points at the wrong file passes. Resolution is mechanical and correctness is a reading, and only the first is a gate's business.
+
+A path written into running prose without backticks is not read at all. Matching one would report every sentence that happens to name a file, and the backticks are what separate a reference a reader follows from a name in a sentence.
+
+A folder or a path carrying no extension is declined rather than guessed at, which is stated above as the cost of the test that carries the separation.
+
+A glob under `governance/rules/` is not read, and a glob that resolves while reaching none of the work it was scoped at is a reading rather than a resolution. Both are stated above.
+
+## Exit codes
+
+Exit codes are `0` when every citation resolves or is excused and every glob read matches, `1` for a refusal, and `2` for at least one cited path reaching nothing or one glob matching nothing. It refuses a tree holding neither rule corpus, since a tree with no rules passes each of its zero rules, and a `git check-ignore` read that fails.
+
+This gates, and `bun run check` runs it as the `Rule citations` stage. The sibling sweeps report rather than gate because a value appears for reasons unrelated to the convention, so their output is a reading. A path resolving to nothing carries no judgment: either the file is there or the citation is stale, and the two classes where absence is correct are separated before the verdict rather than left for a reader to settle. The corpus is clean at the commit this shipped on, so the gate starts green and stays that way until something breaks.
+
+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 JSON record's `citations` array and filter on `status` rather than the exit when a skill consumes this.

package/docs/agents/sandbox.md

@@ -0,0 +1,71 @@
+---
+title: Sandbox
+description: Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
+---
+
+# Sandbox
+
+`canon sandbox` provisions isolated project states, scores a provisioned one against a declared expectation, and reports which scenarios declare an expectation at all.
+
+## Scenarios
+
+Scenarios live under `scripts/sandbox/`, one folder per category. `scripts/sandbox/fixtures/` is the exception, holding file content that scenarios stage rather than scenarios of its own, so both pickers filter it out. `files` in `package.json` excludes that tree, so an installed `canon` carries the command, reports it as toolkit-only on one line, and exits 1 rather than failing on the missing directory. Route non-interactively with `SANDBOX_SCENARIO`:
+
+```bash
+SANDBOX_SCENARIO=sync canon sandbox infra:tooling
+```
+
+Scenario categories: `infra:*` (domain flows), `git:*`, `scaffold:*`. `create` scenarios require interactive input and loop on empty input, so skip them in automated runs.
+
+## Scenario expectations
+
+`canon sandbox check <category>:<command> [arm]` scores a provisioned sandbox against the arm's `expect.toml`, printing a verdict on stderr and, with `--json`, the same verdict as a record on stdout.
+
+```bash
+canon sandbox check claude:docs drift --json
+```
+
+| Flag                | Effect                                                                      |
+| ------------------- | --------------------------------------------------------------------------- |
+| `--envelope <file>` | Read `is_error`, `num_turns`, denials, and the reply text                   |
+| `--writes <file>`   | Newline-delimited paths the session wrote, for write scope                  |
+| `--escapes <file>`  | Newline-delimited paths written to a watched toolkit root, for escape scope |
+| `--escapes-watched` | At least one watched root held a target this run                            |
+| `--json`            | Emit the verdict record on stdout                                           |
+| `--strict`          | Exit 1 on `unchecked` instead of 0                                          |
+
+The verdict `state` is `pass`, `fail`, or `unchecked`. An arm with no `expect.toml` is `unchecked` and exits 0, so the harness stays usable while expectations roll out. A declaration that exists but asserts nothing is a failure, since an expectation file that asserts nothing passes every run.
+
+Omitting `--writes`, `--escapes`, or `--envelope` does not silently drop the assertion kinds that need them. Write scope, escape scope, the turn ceiling, and the reply assertion report as unchecked and appear in the count, so the standalone command cannot claim more coverage than it had. Supplying `--escapes` without `--escapes-watched` reports the same way: a zero-escape result with no root confirmed watched is unmeasured rather than a pass. A verdict never reports `pass` with zero assertions.
+
+An arm declaring `escape_scope` asserts a bound on `run.sh`'s own escape watch rather than on the sandbox tree. `write_scope` skips when the run wrote nothing, since a required output missing is itself a finding, but `escape_scope` passes on zero escapes outright, since a clean run producing none is the expected outcome for a destination nothing requires a skill to touch, provided `--escapes-watched` confirms a root held something to watch. Declaring `escape_scope = []` asserts that a correct run reaches none of the watched destinations at all. `.claude/context/sandbox/overview.md` names what the watch reaches and what it cannot.
+
+An envelope that parses but carries no `result` field skips the reply assertion the same way an absent file does. An envelope carrying an empty `result` fails it, since a run that returned no text is a finding rather than a gap in the input.
+
+Exit 0 means `pass` or `unchecked`. Exit 1 means `fail`, or a caller error: a malformed target, or a sandbox that was never provisioned. A missing sandbox reports as an error rather than a failed verdict, because failing every path assertion would read as a skill that did nothing. `--strict` moves `unchecked` to exit 1 for a caller that has finished arming its scenarios.
+
+## Scenario coverage
+
+`canon sandbox coverage` reports which scenarios declare expectations and which only provision a state. It reads the fixture tree, so it needs no provisioned sandbox and runs nothing. Where that tree does not ship it exits 1 and prints no percentage, since a denominator nobody looked at is not a coverage result. A tree that is present and holds no scenarios is a real zero and still reports one.
+
+```bash
+canon sandbox coverage --json
+```
+
+| Flag       | Effect                                                      |
+| ---------- | ----------------------------------------------------------- |
+| `--json`   | Emit the coverage record on stdout                          |
+| `--strict` | Exit 1 while any scenario declares no expectation           |
+| `--skills` | Add a per-skill asserted, should-be-asserted, exempt census |
+
+The record carries every scenario with the arms that declare, plus `totalScenarios`, `armedScenarios`, and `armedArms`. Scenarios and arms count separately, since several arms can share one scenario and dividing one by the other overstates the rollout.
+
+### The skills census
+
+`--skills` answers what the scenario count cannot, which is whether anything can fail a given skill. It adds `skills`, `totalSkills`, `asserted`, `shouldBeAsserted`, `exempt`, `staleExemptions`, and `supersededExemptions` to the record, and keeps the scenario view rather than replacing it. The two denominators disagree on purpose: an armed scenario under `infra/` or `tooling/` exercises a CLI domain and pairs with no skill at all.
+
+A skill pairs to a scenario by filename, `<category>-<command>` first and bare `<command>` second, so `claude/setup-init.sh` reaches the `setup-init` skill. `should-be-asserted` is the default rather than a queue to drain, and which of those skills earns an arm is a project decision the census does not make.
+
+`exempt` means no arm should be written and holds only with a reason, declared in `scripts/sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
+
+`scripts/sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.claude/.tmp/sandbox-runs/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit. Stdout carries the same bytes it did before the record existed.

package/docs/agents/scripting.md

@@ -0,0 +1,149 @@
+---
+title: Scripting
+description: The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
+---
+
+# Scripting
+
+What a skill or script reads to discover names at runtime, and how each domain is invoked with no TTY.
+
+## Runtime catalogs
+
+Use these to discover what's available instead of hardcoding names.
+
+| Command                           | Returns                                                          |
+| --------------------------------- | ---------------------------------------------------------------- |
+| `canon tooling list --json`       | Stacks, extends chain, dep and script counts                     |
+| `canon snippets list --json`      | Presets and categories with their slugs                          |
+| `canon standards list --json`     | Standards docs and the paths each governs                        |
+| `canon gov list --json`           | Governance stacks, rule sets, and unreferenced rules             |
+| `canon claude seeds list --json`  | Seed doc sources with content                                    |
+| `canon claude skills list --json` | Plugin skills, descriptions, requirement flag                    |
+| `canon docs list --json`          | Consumer docs plus per-domain context                            |
+| `canon audits list --json`        | Audits the set runs, the corpus each reads, and whether it gates |
+
+### Catalog fields
+
+Every catalog serializes through `JSON.stringify`, so a name carrying a quote
+emits valid JSON. `canon tooling list` and `canon snippets list` previously built
+their output with `printf` and no escaping.
+
+`canon standards list` carries `appliesTo` per standard, the paths that standard's
+`## Scope` statement declares. It holds the backticked paths from the first
+sentence of the statement, the single entry `*` for a standard governing an
+attribute rather than a document type, and an empty array when the statement
+declares nothing a parser can read. A consumer mapping a file to its governing
+standards reads this rather than holding a table of its own, and reports an empty
+array rather than skipping the standard behind it.
+
+`canon claude seeds list` reads the same plan `canon claude init` applies, so the
+listing and the install cannot disagree. It now reports
+`.claude/context/index.md`, which `init` has always installed and the listing
+never named, and it emits the project-level `CLAUDE.md` last rather than first.
+
+`canon gov list` reports each stack's rules already expanded. A stack entry names
+either a rule or a whole rule folder under `governance/rules/`, and the folder
+form reaches this listing as the rules it stands for rather than as the folder
+name. A consumer deduping `--add` extras against a stack therefore reads the same
+set the install writes, whichever form the stack file uses.
+
+It also carries `unreferenced`, the rules no stack reaches, on every invocation
+rather than behind a flag. These install only through `--add`, so the key answers
+what a stack leaves out without a caller resolving every stack itself. The key is
+present alongside `stacks` and `rules` and survives `--stacks` or `--rules`
+narrowing the other two.
+
+### The skills catalog
+
+`canon claude skills list` reads `claude/skills/*/SKILL.md` and reports the folder
+name with the frontmatter description, sorted by name. Internal skills under
+`.claude/skills/` are excluded, since they never install into a target and a
+count spanning both overstates what ships. A skill whose frontmatter is missing
+or unparseable returns an empty description rather than failing the listing, so
+one malformed file cannot hide the rest of the catalog. `--names` emits skill
+names one per line.
+
+Each entry also carries `requirement`, whether the folder holds a sibling
+`REQUIREMENT.md`. Every skill is meant to carry one, so a `false` is a gap to
+close rather than a recorded exemption, and the flag answers which skills are
+missing theirs without a caller listing the directory itself. `canon claude skills
+audit` gates that rule across both corpora, so read this flag for the state of
+the shipped catalog and the audit for whether a working tree conforms. Its
+surface is in `skills-audit.md`.
+
+## Non-interactive examples
+
+```bash
+# Create a new tooling stack
+CANON_NON_INTERACTIVE=1 canon tooling create astro
+
+# Report what a stack would change, writing nothing
+CANON_NON_INTERACTIVE=1 canon tooling sync astro /path/to/project --check
+
+# Sync a stack into a target project, overwriting its golden configs
+CANON_NON_INTERACTIVE=1 canon tooling sync astro /path/to/project --write
+
+# Install a governance stack (the stack argument is required headlessly)
+CANON_NON_INTERACTIVE=1 canon gov install astro --add 260-shadcn /path/to/project
+
+# Update installed governance rules, dropping a retired .claude/GOV.md
+CANON_NON_INTERACTIVE=1 canon gov sync /path/to/project
+
+# Concatenate installed rules into a paste payload
+CANON_NON_INTERACTIVE=1 canon gov build /path/to/project
+
+# Sync a monorepo subtree, skipping the base layer the repo root already owns
+CANON_NON_INTERACTIVE=1 canon tooling sync vite-react /path/to/repo/frontend --skip base --write
+
+# Verify a stack end-to-end in a throwaway scaffold
+canon tooling verify vite-react
+
+# Apply one stack without scanning or prompting, for scripted provisioning
+canon tooling inject base /path/to/project
+canon tooling inject base /path/to/project --configs --seeds
+
+# Drop managed gitignore entries a manifest no longer declares
+# Prints the number removed on stdout, diagnostics on stderr
+canon tooling prune-gitignore base /path/to/project
+
+# Print one standard. Nothing installs the corpus, so this is how a target reads one
+CANON_NON_INTERACTIVE=1 canon standards slug >slug.md
+
+# Bootstrap a project. Any flag suppresses the confirmation prompt
+CANON_NON_INTERACTIVE=1 canon init --stack astro --skip wiki /path/to/project
+
+# Run every domain sync. The git workflow is refused headlessly, so nothing is pushed
+CANON_NON_INTERACTIVE=1 canon sync /path/to/project
+
+# Scaffold .claude/wiki/ with a stub index. The target must already exist
+CANON_NON_INTERACTIVE=1 canon wiki init /path/to/project
+
+# Run a sandbox scenario non-interactively
+SANDBOX_SCENARIO=sync canon sandbox infra:tooling
+
+# Read every audit as one record. Exit 2 is a fact, 3 an audit that did not report
+canon audits run --json
+
+# Read committed state rather than an arriving change. Exit 2 carries findings
+canon secrets scan --json
+canon deps audit --json
+```
+
+The two state-scoped verbs both exit 2 on findings and mean different things by
+it. A credential in the shipped tree is a fact and fails `canon audits run`, while
+a published advisory is a judgment that reports and moves no verdict. Neither
+reads a diff, so a consumer already running a review surface gets no overlap.
+
+Both refuse rather than report clean when they have no corpus, and the refusal
+reason is the field to branch on. A project publishing nothing refuses the secret
+scan with `no-manifest`, and one whose dependencies are not installed refuses the
+advisory check with `no-lockfile`. The aggregate reads those as an absent corpus
+rather than a broken run, so neither pins its verdict at `incomplete`.
+
+`canon tooling sync` is the one verb above whose flag is mandatory headlessly. It
+overwrites every golden config a stack ships, which reaches the CI workflow, the
+git hooks, the end-to-end harness, and the shell scripts under `scripts/`, so a
+headless run carrying neither `--check` nor `--write` reports what it would
+replace and exits 1 rather than applying it. Run `--check` first to read the
+list, then `--write` to apply it. `canon tooling sync --help` names both, and the
+full per-stack path list sits in the `canon-cli` skill.

package/docs/agents/sessions.md

@@ -0,0 +1,120 @@
+---
+title: Sessions
+description: Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, and what each session surface can see
+---
+
+# Sessions
+
+## List
+
+`canon sessions list` reports every live Claude Code session on the machine with the working directory and branch it holds.
+
+```bash
+canon sessions list
+canon sessions list --json
+canon sessions list --branch feat/parser --json
+canon sessions list --branch chore/agents --repository ../caret --json
+canon sessions list --self --json
+```
+
+| Option                | Behavior                                              |
+| --------------------- | ----------------------------------------------------- |
+| `--json`              | Add a machine-readable record on stdout               |
+| `--branch <name>`     | Report the sessions holding this branch               |
+| `--repository <path>` | Answer about this project rather than the working one |
+| `--self`              | Report the caller's own row                           |
+
+It reads and never writes. The question it answers is which session to address when work has to reach the one holding a given branch, which a session listing cannot answer on its own.
+
+Exit codes: `0` the roster was read, `1` refused. The refusal carries a `reason` of `no-registry`, `no-repository`, `no-self-identity`, or `no-self-row`.
+
+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.
+
+## Scope and count
+
+`--branch` scopes the match to one repository, and refuses when none resolves. A branch name identifies a branch inside a repository and nothing across a machine, so an unscoped match reaches a session working in a different project, and `main` collides on every machine running two of them.
+
+Which repository that is defaults to the one the command runs in, and `--repository <path>` names another. Every reading moves with it, the session match and the worktree and ref reads alike, because the answer is about that project rather than about where the caller stands. The roster underneath is machine-wide already, so the flag removes a filter rather than widening a search.
+
+That is what a dispatcher reaching outside its own project needs. Without it a check run from the toolkit against a branch held by a live session in a consuming project answered unclaimed, and two sessions were sent onto branches other sessions were holding. One refused on the worktree lock and one cut a second worktree on the same branch, which would have put two sessions pushing to one ref.
+
+A bare run reports every repository and carries a `repository` field on each row, holding the shared git directory that a main checkout and all its linked worktrees agree on. That is what a caller filters on when it wants a scope of its own.
+
+The match can return more than one session. Read the count rather than the first row, since nothing stops two sessions holding one branch, and a caller that treats the result as singular picks among candidates without knowing it.
+
+## Whether a branch is already claimed
+
+With `--branch`, the JSON record also carries `worktree` (the path of any worktree already checked out to it, or `null`), `refs` (the refs that already name the branch, the local head and the `origin` remote-tracking ref alike), and `claimed` (`true` when any of the three holds it).
+
+Read `claimed` rather than composing the three fields by hand. A worktree can outlive the session that made it, and a session can hold a branch before any worktree exists for it. A branch sitting behind a merged pull request has neither and is taken all the same, which is the reading that was missing when a dispatcher cleared a merged branch and told a worker to build on it.
+
+The ref read covers the local head and the remote-tracking ref, which means it sees the remote at whatever the last fetch left behind. A branch pushed from another machine since then reads absent. Closing that gap needs `git ls-remote`, and it is left open deliberately: the remote read costs 0.438s against 0.001s for the local one, on a check that runs before every dispatch.
+
+`worktree`, `refs`, and `claimed` are `null` on a bare run with no `--branch`, since none of the three questions has a branch to answer about. A refusal (`no-registry` or `no-repository`) carries none of the keys at all, which a caller should read as unverified rather than as clear.
+
+Two flags say which reading came up short. `sessionsReadable` is `false` when the session roster could not be read, and `refsReadable` is `false` when the ref read failed. Either one leaves `claimed` covering the readings around it alone, so a `false` there is a report that ran short of evidence rather than a report that the branch is clear. They stay separate fields because a caller told the roster failed goes and looks at the roster, and folding both into one flag would send it to the wrong place.
+
+## Which row is the caller
+
+`--self` narrows the report to the row belonging to the session making the call. A dispatcher reads it to learn the `sessionId` it carries into a launch, because the roster returns every field on every row and marks none of them as the caller.
+
+Three identifier namespaces reach a session and two of them join to a row. Four variables spell them:
+
+- `CLAUDE_CODE_SESSION_ID` holds the roster's own `sessionId`, and is read first because it survives a rename.
+- `CLAUDE_PID` holds the caller's process id, which every row already carries as `pid`.
+- `CLAUDE_CODE_MESSAGING_SOCKET` spells that same pid in its basename. It is read last, since the spelling is a client convention rather than a published interface and a client that moves the socket drops this rung alone.
+- `CLAUDE_CODE_HOST_SESSION_ID` is never read. It carries a `local_`-prefixed value from the harness namespace that matches no row, and it is the variable a reader searching the environment for a session id finds first.
+
+The read refuses rather than returning an empty roster, on the same ground as `no-registry`. A `no-self-identity` refusal means the environment stated none of the three, which is a client identifying its sessions some other way. A `no-self-row` refusal means it stated one and no live row carries it, which is what a session running outside a local process gets.
+
+## What each surface can see
+
+The roster this verb reads and the channel a session sends messages on enumerate different populations, and neither contains the other. Read at one moment, `canon sessions list` returned 6 rows against the 13 peers plus caller the agent listing reported. The roster held a background session at confirmed confidence on two reads a minute apart that the listing never carried, so a live session sat here with no way to reach it. Nine Remote Control sessions ran the other way, reachable there with no row here at all, since they leave no local process for the registry to record.
+
+That bounds what a carried identifier buys. Resolving a `sessionId` to a name here can produce a name the send channel rejects, and `--self` answers nothing for a controller driving from Remote Control, which is the operator working from their phone rather than an edge case. A caller that cannot resolve an addressee reports the failed resolution instead of falling back to a guess.
+
+The `name` field is what both surfaces agree on, and that agreement is what makes the resolution work. `SendMessage` takes a name and carries no identifier parameter, so the carry runs id to name to send rather than sending an id anywhere.
+
+Agreement is not uniqueness, and the last hop is where that bites. Two live sessions can hold one name, the roster carries no field that separates them, and a send to the bare name reaches whichever the channel resolves first. The agent listing prints a ref beside each row and the roster does not, so a name resolving to more than one live row is completed from that listing rather than from anything this verb returns.
+
+## Why the verb exists
+
+A session listing reports a name, a kind, a status, and how long each session has been running. None of those names a branch. Resolving a branch to a session therefore meant ordering the roster by start time and matching it against the order the worktrees were created, which is an inference that fails whenever two sessions start inside the same minute.
+
+Each session writes its own record on disk carrying its working directory beside its own name. This verb reads those records, so a name joins to a branch by an exact match on one file rather than by a guess across two orderings.
+
+## What a row carries
+
+Every row names the session, the process holding it, its working directory, and the branch checked out there. The status field repeats what the session listing reports, so a caller picking a target reads one output instead of two.
+
+A field the record did not carry is reported as null rather than as a value, so an absent start time never reads as a session launched in 1970 and an absent identifier never reads as an empty one.
+
+A row whose branch cannot be read is kept and marked rather than dropped. A caller has to be able to tell a session holding no branch from one the resolver never saw, and the second is the failure the verb replaces. The `unresolved` field carries the reason:
+
+- `detached-head`: the session holds a worktree with no branch name
+- `not-a-repository`: the session is working outside any git repository
+- `git-unavailable`: git is not on the path, so nothing could be read
+
+## The confidence field
+
+Every report states how liveness was decided, on a pass as well as a failure.
+
+`confirmed` means each row's process was matched against the start time its own record stamped at launch, so the process holding the pid is the session that wrote the file. A caller can address a row of that kind directly.
+
+`unverified` means only that the pid answers a probe. That cannot separate the original session from an unrelated process that inherited its pid after the session ended, so the roster is a candidate list rather than an identity. Treat the mapping as inferred and open the message by naming the branch the reader is believed to hold, asking to be corrected.
+
+The registry holds one record per session and is never pruned, so it accumulates thousands of entries. On the `unverified` path a stale record whose pid has been reused reads as live, which is why the field is reported rather than assumed.
+
+## The status dwell
+
+Every row carries `statusUpdatedAt`, the stamp a client writes beside `status` at the moment it last changed, and `statusDwellMs`, the elapsed milliseconds since that stamp. Measured over the live registry, 23 of 341 usable records carry `statusUpdatedAt`, so `null` is the ordinary answer rather than an edge case, and the absence tracks a client version rather than a record's age alone: the one record ever measured carrying `status: "waiting"` is among the 318 without it.
+
+`statusDwellMs` falls back to the coarser `updatedAt` stamp when `statusUpdatedAt` is absent, so it is `null` only where a record carries neither. `statusUpdatedAt` itself is never backfilled from the fallback and stays `null` in that case, since it names the exact stamp rather than an estimate. A stamp ahead of the reading clock clamps the dwell to zero rather than reporting a negative one.
+
+The dwell is what separates a status that resolves on its own from one that does not. `busy` and `idle` transition without help, so a long dwell there is ordinary. `waiting` does not: a session in that state is blocked on something outside itself, and a dwell that keeps growing past the ordinary span of a prompt is a session stalled rather than paused. `canon sessions list` renders the dwell beside the status at the coarsest unit that keeps it a whole number, and the JSON record carries both fields on every row.
+
+## What the read depends on
+
+The records live under the Claude Code configuration directory, which the verb resolves from `CLAUDE_CONFIG_DIR` and falls back to `~/.claude`. Their location, their filenames, and the fields inside them are a client implementation detail rather than a published interface, so a client change can move them. The verb reports an absent registry as a refusal rather than as a machine running no sessions, which is what surfaces the move instead of burying it in an empty roster.
+
+The start-time comparison reads the process filesystem and exists only on some platforms. Where it does not, the verb still answers and marks the confidence, so a target without it keeps a working roster rather than losing the command.