@erclx/canon 5.38.0 → 5.40.0

package/docs/agents/routing.md

@@ -1,61 +0,0 @@
----
-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 `canon/context/context-model/overview.md`, whether a fact applies every session or fires on one path, and which until this verb existed was a judgment nothing counted. The tier test 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 `tsconfig.json` while leaving a flag, a bare word, and a version string out.
-
-A shape counts as the folder above its placeholder. `canon/context/<domain>.md` names `canon/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

@@ -1,90 +0,0 @@
----
-title: Rule citations
-description: Resolving every path a governance rule cites and every frontmatter glob the internal corpus declares, the one form 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. The teach rule 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 one form
-
-A citation reaches a reader as a backticked path, reported under the form `path`, and it resolves against the root. A bare filename is never a citation, since with no folder around it nothing tells a rule from a convention such as `index.md`. A rule pointing at another rule writes its repository path.
-
-A call to the retired standards verb is no form here. A rule holding one fails the shipped-references stage of `canon gate run`, which reads every shipped file for it.
-
-A `path` is anchored on the whole backticked span rather than on a trailing pattern inside it. Cutting `tooling-reference.md` out of `internal/standards/tooling-reference.md` and resolving that against the root alone 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: `canon/context/<domain>.md`, `app/**/route.ts`, `${CLAUDE_SKILL_DIR}/../references/<name>.md`.
-- A bare filename names a convention: `route.ts`, `manifest.toml`, `components.json`, `playwright.config.ts`.
-- 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 the real paths that name a folder or a symlink, which 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, so the file is correctly absent from this tree and correctly named in the rule. No shipped rule declares one today, and the stage's test fixtures carry the instance that keeps the class exercised.
-
-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/canon/tasks.md` cites `.canon/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/e2e-reliability.md` scoped itself at `e2e/*.ts` and `e2e/**/*.ts` and now reads `**/e2e/**/*.ts`. 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

@@ -1,126 +0,0 @@
----
-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 `sandbox/`, one folder per category and one file per command, each a TypeScript module. `sandbox/fixtures/` is the exception, holding file content that scenarios stage rather than scenarios of its own, so the picker and the coverage report both filter it out. That tree sits outside `files` in `package.json`, 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:context-fold 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                                                                  |
-| `--concurrent-sessions <file>` | Newline-delimited sessions live in the registry both before and after this run, a witness for an unbounded escape |
-| `--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 the headless runner'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. `canon/context/sandbox/isolation.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.
-
-## Headless runs
-
-`canon sandbox run` provisions a scenario, drives one `claude -p` session over it, and scores the result with `canon sandbox check`.
-
-```bash
-canon sandbox run <category>:<command> "<prompt>" [arm]
-canon sandbox run claude:plan-feature "/canon:plan-feature add a widget" small
-```
-
-Every run bills a real session through the `claude` binary on `PATH`. The session runs with `--plugin-dir` pointed at this checkout's `claude/`, so it loads the branch's skills rather than an installed copy, and provisioning injects no skill into the tree for the same reason. Four variables override the flags it hands to `claude -p`:
-
-| Variable                           | Default                          |
-| ---------------------------------- | -------------------------------- |
-| `CANON_SKILL_TEST_MODEL`           | `sonnet`                         |
-| `CANON_SKILL_TEST_TOOLS`           | `Bash,Read,Glob,Grep,Edit,Write` |
-| `CANON_SKILL_TEST_MAX_TURNS`       | `30`                             |
-| `CANON_SKILL_TEST_PERMISSION_MODE` | `bypassPermissions`              |
-
-The max-turns value is the only budget a run has. An arm's `max_turns` is asserted after the run and cannot raise it.
-
-Stdout carries one JSON record: the session's envelope with `verdict`, `escapes`, and `sessions` merged in, described under the skills census below. Stderr carries the framed timeline, the provisioning output, the session's own stderr, the verdict report, and a warning for each escape, new session record, or reaped process. An envelope that does not parse still prints its verdict, under `is_error: true`.
-
-Exit codes follow whichever step stopped the run. Provisioning's code ends a run before the session starts, and a session that exits non-zero ends it with that code after writing a dead-run record, `{is_error, exit_code, raw_output}`, to the same runs folder the merged record uses. Otherwise the verdict's code stands, except that an envelope that does not parse forces 1. An interrupt reaps the session's process group before the runner exits.
-
-## Provisioning equivalence
-
-`canon sandbox equivalence` proves a change moved nothing in what scenarios provision. It provisions every arm of the named targets on a base ref and on the working checkout, builds a manifest of each tree, and names what differs. It runs offline and never calls `canon sandbox run` or a `claude` binary, so no arm it runs bills a model.
-
-```bash
-canon sandbox equivalence claude --base origin/main --json
-canon sandbox equivalence claude:plan-feature/full --base HEAD
-```
-
-A target is `<category>`, `<category>:<command>`, or `<category>:<command>/<arm>`, defaulting to every category.
-
-| Flag               | Effect                                                                                             |
-| ------------------ | -------------------------------------------------------------------------------------------------- |
-| `--base <ref>`     | Ref the baseline is provisioned from, `main` by default                                            |
-| `--include-anchor` | Also run the arms that push to the shared GitHub anchor, one at a time, for an attended run        |
-| `--stub-remote`    | Run the anchor arms against a local bare repository and a stub `gh`, writing nothing to the anchor |
-| `--out <dir>`      | Keep the provisioned trees, logs, and per-side manifests in this folder                            |
-| `--no-masks`       | Compare every path, which lists what each mask would hide                                          |
-| `--json`           | Emit the record on stdout                                                                          |
-
-The baseline is a detached worktree with full history, removed on exit including after `SIGINT`. Each arm provisions on the base side, is read into a manifest, is deleted, then provisions on the head side at the same path with the run id pinned. A manifest holds every file's mode and hash, every symlink's target, the exit status, the narration, and for the outer repository and each nested one the commit subjects, the staged index, and the branch.
-
-The record lists per arm `identical`, `differs` with the manifest keys that differ, `red-on-base` when both sides fail the same way, or `skipped-anchor`. It also carries `canonVersion`, `baseCommit`, `masksApplied`, `errors`, and `counts`. A declared arm adds a `check` entry from `canon sandbox check` on the head tree, whose `asserted` count shows its `expect.toml` resolved from `sandbox/fixtures/`.
-
-Exit 0 means every compared arm is identical or red the same way on both sides. Exit 1 means any `differs`, a base and head exit that disagree, an armed arm that `canon sandbox coverage` lists and enumeration lacks, or a `.ts` scenario that fails to load.
-
-## 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/target-setup.ts` reaches the `target-setup` 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 `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.
-
-`canon sandbox run` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.canon/tmp/runs/sandbox/<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.
-
-Two more fields ride alongside the verdict rather than inside it. `escapes` lists what the run wrote under a watched toolkit root, which the verdict cannot assert over because those files sit outside the sandbox tree. `sessions` reports the nested-dispatch bound, carrying `watched` for whether the client's session registry was there to read, `new` for the records that appeared while the run was in flight, `concurrent` for the records present both before and after, and `reap` for what the run found in the session's process group afterwards. Neither field fails a run on its own.
-
-`canon sandbox run` passes `concurrent` through `--concurrent-sessions` to `sandbox check`, and `checkEscapeScope` appends a witness count to an `unbounded escape:` message rather than lets it soften the verdict.

package/docs/agents/scripting.md

@@ -1,142 +0,0 @@
----
-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 gov list --json`           | Governance stacks, rule sets, evidence, and unreferenced rules   |
-| `canon gov detect --json`         | Opt-in rules a target's dependencies and paths propose           |
-| `canon claude seeds list --json`  | Seed doc sources with content                                    |
-| `canon claude skills list --json` | Plugin skills, descriptions, requirement flag, family vocabulary |
-| `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` previously built
-its output with `printf` and no escaping.
-
-`canon claude seeds list` reads the same plan `canon claude init` applies, so the
-listing and the install cannot disagree. It now reports
-`canon/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 skill in `--json` carries `family`, the `metadata.family` its frontmatter
-declares, or `null` where it declares none. A top-level `families` array holds
-the vocabulary as `{ key, group }` entries in skill map order, where `group` is
-the map heading the family's rows sit under. Read a new skill's family from it
-rather than from the map. `--by-family` prints the human listing as one step per
-family, with a trailing step for any skill whose family is missing or unknown.
-
-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
-# Report what a stack would change, writing nothing
-CANON_NON_INTERACTIVE=1 canon tooling diff astro /path/to/project
-
-# 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 node --add astro,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
-
-# Bootstrap a project. Any flag suppresses the confirmation prompt
-CANON_NON_INTERACTIVE=1 canon init --stack node --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
-`canon tooling diff <stack> <target>` reports the per-stack path list resolved
-against a real target.

package/docs/agents/sessions.md

@@ -1,128 +0,0 @@
----
-title: Sessions
-description: Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, what each session surface can see, and where moving a session to another machine is described
----
-
-# 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.
-
-Resolution reads a session's registered `cwd`, taken at whatever `locate()` finds there rather than wherever it has since worked. That registration updates whenever the harness enters a worktree: a worker dispatched onto `main` re-registers at its own branch once `auto-ship` Step 0 runs. What stays fixed is a session moved by shell command, `cd` or `git -C` against another root, with no worktree entry behind it, so it answers only for the branch its last registered `cwd` sits in.
-
-A session whose `cwd` reflects a harness worktree entry, at launch or mid-session, resolves fully, covering every dispatched worker once Step 0 runs. A zero for a different branch it is genuinely working on is not evidence the branch is unclaimed, only that a shell-moved registration cannot see 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.
-
-## Export and import
-
-`canon sessions export <id>` packs one session into a bundle and `canon sessions import <bundle>` places it on another machine. Both are in `sessions-transfer.md`.
-
-## 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.