@journeykit/canon 0.27.0 → 0.28.0

package/dist/skills/SKILL.src.md

@@ -1,14 +1,23 @@
 ---
 name: canon
-description: Use for every build, implement, add-a-feature, change-a-feature or fix request in a repo that has canon.yaml, including sites, apps and games; prefer it there over generic site, app or game builder skills. Runs canon's working loop (brief, subject, scenarios with failure paths, units, implement, evidence, independent review, status transition) split by role (planner, implementer, reviewer, orchestrator), and routes to the canon CLI reference for setup, specs, gates, storage, ingestion, retrieval and reports.
+description: Use for every build, implement, add-a-feature, change-a-feature or fix request in a repo that has canon.yaml, including sites, apps and games; prefer it there over generic site, app or game builder skills. Runs canon's working loop (brief, subject, scenarios with failure paths, units, implement, evidence, independent review, status transition) split by role (planner, implementer, reviewer, orchestrator). The full guide is `canon skills show canon`.
 ---
 
 # Canon
 
-Features in this repo are managed with canon. This skill is the shared core:
-the loop, how to drive the CLI, and how to find your role. What each role
-does lives in `reference/role-<role>.md`; the CLI manual lives in
-`reference/canon-*.md` and `canon <command> --help`.
+Features in this repo are managed with canon. This is the shared core guide:
+the loop, how to drive the CLI, and how to find your role. The guide is built
+into the `canon` binary, so it always matches the version you run:
+
+- `canon skills show canon` prints this guide.
+- `canon skills show <name>` prints one topic or role guide (the table at the
+  end lists every name); `canon skills show canon --full` prints this guide
+  followed by every topic.
+- Your role guide's **Commands** block lists every option of every leaf the
+  role uses. Ask `canon schema <command>` (or `--help`) only for a leaf it does
+  not list, or after a `USAGE` refusal. Never guess an option name.
+
+The `SKILL.md` your harness loaded is only a stub that sends you here.
 
 ## The working loop
 
@@ -24,8 +33,10 @@ a feature, a one-line request included. A human is needed once per scope:
   answer until you report: the brief is that report. The one answer
   approves the brief and the policy, `.canon/policy.yaml`, which is what
   the gate grades the work against. The human may also approve it on the `canon dashboard` briefs page; you never use that form.
-  Record it only from the human's answer:
-  `canon brief approve --change-id <slug> --by <the human> --note "<their words>"`.
+  The human records the answer, never you:
+  `canon brief approve <slug> --approver <their name> --note "<their words>"`
+  refuses every agent role (`HUMAN_ONLY`). Report that exact call, slug filled in, and
+  wait; never remove or unset your role (`env -u CANON_ROLE`, dropping `--as`) to run it yourself.
   Never edit the policy to make the gate pass: a policy that differs from
   the approved one fails closed (`POLICY_CHANGED_SINCE_APPROVAL`, not
   waivable); stop and ask the human. A brief edited after its
@@ -35,59 +46,96 @@ a feature, a one-line request included. A human is needed once per scope:
 - **Approval is scoped.** Evidence for a scenario needs the approval of the
   changes its `@flow:<change>.<F-id>` tags name, so a new unapproved change
   on a live subject waits on its own scenarios only; `change new` and
-  `subject adopt` warn when the subject is live. `canon subject unadopt
-  <change> --subject-id <id>` takes a draft change back off (refused once
-  approved). The subject's scope is its newest adopted change, walking back
-  past pending drafts (brief not approved, no scenario of the subject tagged
-  `@flow:<change>.*`): reopen, evidence and ship read the newest approved or
-  tagged change, and the transition prints one line naming every draft set
-  aside; a draft a scenario is tagged for blocks until it is approved. → `reference/canon-subject.md`
+  `subject adopt` warn when the subject is live. `canon subject unadopt <subject-id> --change-id <change>`
+  takes a draft change back off (refused once approved). The subject's scope
+  is its newest adopted change, walking back past pending drafts (brief not
+  approved, no scenario of the subject tagged `@flow:<change>.*`): reopen,
+  evidence and ship read the newest approved or tagged change, and the
+  transition prints one line naming every draft set aside; a draft a scenario
+  is tagged for blocks until it is approved. `canon skills show canon-subject`
 - **Inside an approved scope, never stop for a human.** Fixes, follow-ups,
   review rounds and re-reviews stay in the approved change (never
   `canon change new`: a new change is a new scope) and go straight on: scenario,
   implement, evidence, independent review. A follow-up that adds or changes
   a step of the brief edits the brief: that is a scope change and needs a
   new answer. A follow-up on a shipped subject reopens it
-  (`canon subject status <id> --to verifying --reason "<why>"`); a fix
-  closed `fixed`, and an approved chore, then need the whole suite evidenced
-  again (`evidence add --all-scenarios`, for a chore after its approval)
-  before it ships, and a chore also needs one change-level review
-  (`review add --change-id <slug>`).
+  (`canon subject move <id> --to verifying --reason "<why>"`); a fix
+  closed `fixed`, and an approved chore, then need evidence again for every
+  scenario whose code changed (see "Evidence follows the code" below) before
+  it ships, and a chore also needs one change-level review
+  (`canon review change <slug>`).
 - When no human can answer one of the brief's questions, write your
   assumption into the brief's Questions and assumptions, build on it, and say
   so in your report. That covers the brief's questions and work inside an
   approved scope, never the approval itself.
 
-1. **Brief.** The planner writes the PRD brief (`.canon/changes/<slug>/brief.md`), checks it with `canon brief check`, and stops for the human. → `reference/role-planner.md`
-2. **Subject.** `canon subject new`, then `canon change new` (`--kind chore` for work that alters no behavior); the change writes the brief skeleton. → `reference/role-planner.md`
-3. **Scenarios.** `canon scenario new --flow <F-id> --case <case>` per behavior of a flow step, failure paths (`--case failure`) included. → `reference/role-implementer.md`
+1. **Brief.** The planner writes the PRD brief (`.canon/changes/<slug>/brief.md`), checks it with `canon brief check`, and stops for the human. `canon skills show role-planner`
+2. **Subject.** `canon subject new`, then `canon change new` (`--change-kind chore` for work that alters no behavior); the change writes the brief skeleton. `canon skills show role-planner`
+3. **Scenarios.** `canon scenario new --flow <F-id> --case <case>` per behavior of a flow step, failure paths (`--case failure`) included; many at once with `--input` (below). `canon skills show role-implementer`
 4. **Units.** Split the work; one unit is one flow step's slice with a named verify command, and each unit has its own actor id and session id, passed on everything it records. A unit never attests another unit's work.
-5. **Implement.** Code with tests named by scenario id (`game.run.01: …`). → `reference/role-implementer.md`
-6. **Evidence.** `canon evidence add` binds the test run to its scenarios. → `reference/role-implementer.md`
-7. **Independent review.** A different session, a separate process with its own session id, that can run the checks it signs off, records `canon finding add` and `canon review add`. Every change. → `reference/role-reviewer.md`
-8. **Transition.** `canon subject status <id> --to <state>` along `proposed → specced → building → verifying → shipped`, with `canon gate check` clean; fix a refused guard rather than overriding it. → `reference/role-orchestrator.md`
+5. **Implement.** Code with tests named by scenario id (`game.run.01: …`). `canon skills show role-implementer`
+6. **Evidence.** `canon evidence add` binds the test run to its scenarios; one `--input` array records many at once. `canon skills show role-implementer`
+7. **Independent review.** A different session, a separate process with its own session id, that can run the checks it signs off, records `canon finding add` and `canon review scenario`. Every change. `canon skills show role-reviewer`
+8. **Transition.** `canon subject move <id> --to <state>` along `proposed → specced → building → verifying → shipped`, with `canon gate check` clean; fix a refused guard rather than overriding it. `canon skills show role-orchestrator`
+
+**Done when:** `canon gate check` exits 0 with no violations, `canon subject show <id>` reports status `shipped`, and `canon status` names no next step for the subject (a human step left in `meta.next` is the one thing you report instead of doing).
 
 Every write command says whether the record is final (`written directly`,
 or `staged and promoted in this run`) or staged; only a staged record
 needs `canon gate promote`, and only `write.promote: manual` leaves one.
 
+### Commits and uncommitted code
+
+Records that are about code take `--rev <REV>`: any git revision (`HEAD~1`,
+a branch, a tag, a short sha), default `HEAD`, so you never copy a sha out of
+git. `finding add` also takes `--resolution-rev` (default HEAD when the
+finding is `fixed`) and `--introduced-rev` (no default: say where the defect
+came from). Evidence, a review or a finding of uncommitted work is allowed,
+never refused: the record carries `codeTree` (the git tree id of the code the
+command saw: `.canon/`, the spec roots and the `code.exclude` globs are left
+out, so editing a `.feature` file or a brief never changes it) and
+`worktreeDirty`. The commit made from a working tree has the same `codeTree`
+the record carries, so a review of a working tree survives the commit made
+from it; a review is judged by what it pins (the scenario and what its
+evidence says), never by the commit or the code tree. Outside a git work
+tree, or in a repo with no commits, a command that needs a commit refuses
+`NO_COMMIT`.
+
+### Evidence follows the code
+
+After a chore approval or a reopen, a scenario whose latest evidence was
+recorded on the current `codeTree` needs nothing new: a docs-only chore then
+needs its change-level review alone. What counts as code is `code.exclude` in
+`canon.yaml` (globs, default `docs/**` and `*.md`). When code did change,
+`canon status`, `meta.next` and the refusal hint lead with one batch over
+every report, for example
+`canon evidence add --all-scenarios --report junit:a.xml --report junit:b.xml --role implementer`
+(with the real report paths, and `--project-id <id>` when the repo has several
+spec roots), never a loop per scenario. With a `--report`, `--class` defaults
+to `test-run` and `--ref` to the report paths, and the bound cases decide the
+verdict: any failed case `divergent`, a skipped one and none failed
+`not-applicable`, else `faithful`.
+
+### State
+
 The ledger is latest-only. It holds the current record of each key; writing a
 newer version moves what it supersedes to `.canon/archive`, and `status`,
 `gate check`, the guards and `query` read the ledger only. Earlier versions
-are one flag away: `canon query --kind <k> --history`. A ledger written
+are one flag away: `canon query --kind evidence --history`. A ledger written
 before 0.23, or one whose move was interrupted, is brought to one file per
 key by `canon ledger compact` (`canon migrate` runs it). A record binds only
 what its own write names: evidence carries nothing forward from an earlier
 record, and a review stays current while the verdict and checks of the
-evidence it saw are unchanged.
+evidence it saw are unchanged and the code tree is the one it saw.
 
 Where artifact bytes live is the repo's choice: `canon.yaml`'s `artifact_store:`
 block defaults to the local, git-tracked `.canon/artifacts/sha256/`, or names
-an object-store tier, in which case `evidence add`, `review add` and
-`evidence vault` upload by digest and keep nothing locally. The gate and
-`canon artifacts verify [--full]` ask the store and refuse, never pass, when
-it cannot be reached. Moving an existing store with `canon artifacts migrate`
-is the repo owner's decision, not a step of the loop.
+an object-store tier, in which case `evidence add`, `review scenario`, `review change` and
+`artifacts store` upload by digest and keep nothing locally. The gate and
+`canon artifacts verify` (`--full` re-hashes every blob) ask the store and
+refuse, never pass, when it cannot be reached. Moving an existing store with
+`canon artifacts move --tier <tier>` is the repo owner's decision, not a step
+of the loop.
 
 ## Know your role
 
@@ -96,52 +144,122 @@ canon cannot detect a role; you declare it. Pass `--as <role>` or set
 variable, and an unknown value is refused (`UNKNOWN_ROLE`).
 
 - **A role is set, or you were spawned as one:** load only
-  `reference/role-<role>.md` and do that role's steps. `canon status`,
-  `meta.next` and `canon schema` then show only your role's steps and
-  commands, and count the others in `waitingOn`. Do not load another role's
-  reference.
+  `canon skills show role-<role>` and do that role's steps. `canon status`
+  and `meta.next` then show only your role's steps, and count the others in
+  `waitingOn`; `canon schema --as <role>` lists only your role's commands.
+  Do not load another role's guide.
 - **No role (one agent doing everything):** follow `canon status` and load
-  each role reference as its phase starts: planner for steps 1–2,
+  each role guide as its phase starts: planner for steps 1–2,
   implementer for 3–6, reviewer for 7 (in a separate session), orchestrator
   for 8.
 
 A role is guidance, not enforcement: `--role` on `evidence add` and
-`review add` defaults to it.
+`review scenario` defaults to it. `CANON_ROLE` never filters or fails
+`canon schema`, `canon context` or `canon skills show`; only `--as` filters.
 
 ## Driving the CLI
 
 - Start a session with `canon status`: where each subject stands and the next
   commands. After that, do not call it only to learn the next step: every
-  write returns `meta.next` (`[{command, why, actor, role}]`), the same steps
-  `status` would give, narrowed to what the write touched. `actor: human`
+  write returns `meta.next` (`[{command, argv, why, actor, role}]`), the same
+  steps `status` would give, narrowed to what the write touched. `actor: human`
   marks a step only the human takes.
-- Your role reference's **Commands** block (`reference/role-<role>.md`) is
-  your complete command set. Run `canon schema <command> --json` only for a
+- Your role guide's **Commands** block (`canon skills show role-<role>`) is
+  your complete command set, every option of every leaf included. Run `canon schema <command> --json` only for a
   command it does not list, or after a `USAGE` refusal (read `error.field`
-  and `expected` first). `canon schema` alone lists every command.
-- Pass `--json` and read stdout as one document. On failure it is
-  `{"error":{"code","message","hint","retryable","field","expected"}}`: branch
-  on `error.code`, fix the option `field` names using the `expected` values,
-  and follow `error.hint`. Every refusal carries a concrete `hint`: follow
-  it. The codes are stable; `canon schema --errors --json` lists them.
+  and `error.expected` first). `canon schema` alone lists every command.
+- Pass `--json` and read stdout as one document, nothing on stderr. Success is
+  `{"ok":true,"data":…,"meta":…}`; failure is
+  `{"ok":false,"error":{…},"meta":…}` (a check that fails keeps its report in
+  `data`). `meta` carries `command`, `schemaVersion`, `canonVersion`, `next`,
+  `warnings` and, for a repeated write that changed nothing, `unchanged: true`.
+  On failure branch on `error.code`, fix the option `error.field` names
+  using the `error.expected` values (`field` is an option name, or a JSON
+  pointer such as `/items/2/scenarioId` into an `--input` document), and
+  follow `error.hint`: every refusal carries a working invocation. The codes
+  are stable; `canon schema --errors --json` lists them and
+  `canon schema --error <CODE>` explains one.
+- **Exit codes:** 0 ok; 1 the command's own finding (a failed check, a
+  violation, or `unverifiable` when nothing was examined); 2 refused (usage,
+  `CONFIG_MISSING`, an id or file that does not exist, an invalid argument).
+  A refusal leaves the tree unchanged.
+- Repeating a write is safe: a record that already exists with identical
+  content is reported `unchanged` (`meta.unchanged`), not duplicated.
 - Flags that name an id are spelled `--<noun>-id` everywhere (`--change-id`,
   `--project-id`, `--subject-id`, `--scenario-id`, `--actor-id`,
-  `--session-id`), and `--kind` values carry no `_record` suffix
-  (`--kind evidence`).
+  `--session-id`), the primary object of a command is its operand
+  (`canon subject move <id> --to verifying`, `canon change new <slug>`), and
+  `--kind` values carry no `_record` suffix (`--kind evidence`).
 - `canon status` sends the planner to write the brief while `brief check`
   has blockers; the human stop appears only when the brief is clean and
   unapproved.
 - Page long lists with `--limit <n>` and `--cursor <nextCursor>` (`--all`
   for everything), and project fields with `--fields a,b` (`status`, `export`,
-  `query`, `finding list`, `divergence status`, `context`).
-- `canon purge` deletes only in two steps: `--plan` prints the removal set
-  and a `planDigest`; then `--confirm <planDigest>`.
+  `query`, `finding list`, `divergence list`, `context`).
+- `--override-reason <text>` is the only way to proceed past a waivable
+  refusal; it is recorded, echoed in `data.overrides[]` and listed by `status`
+  for the human. There is no `--force`. `brief approve`, `policy approve` and
+  `divergence accept` are human-only and refuse every agent role: report the
+  exact call, ids filled in, and wait; never unset your role to run one.
 
-## Command reference
+### Many records at once: `--input`
 
-Load only the reference the current step needs.
+Every write leaf takes `--input` instead of flags: inline JSON, a file, or `-`
+for stdin. The keys are the option names in camelCase, and `operands` holds
+the positional arguments. An object is one invocation; a JSON array (or NDJSON
+from a file or stdin) is a batch, run in order and answered with
+`data.items[]` (`index`, `status` of `written`, `unchanged`, `failed` or
+`skipped`, and that element's `data` or `error`). A batch is validated whole
+before anything is written: an invalid element writes nothing and exits 2,
+`error.field` pointing at `/items/<i>/<key>`; a write that fails stops there
+(exit 1) and re-running the same batch reports the finished elements
+`unchanged`. A typo in a key is refused (`INPUT_UNKNOWN_FIELD`), never dropped.
+`canon schema <command> --json` shows the leaf's input schema and an example.
 
-### Setup and provider projection
+```text
+canon scenario new --input '[{"operands":["auth.login.01"],"title":"Logs in","case":"happy"},{"operands":["auth.login.02"],"title":"Wrong password","case":"failure"}]'
+canon evidence add --input '[{"scenarioId":"auth.login.01","class":"test-run","ref":"npm test","role":"implementer"},{"scenarioId":"auth.login.02","class":"test-run","ref":"npm test","role":"implementer"}]'
+canon finding add --input '[{"changeId":"add-login","round":1,"seq":1,"severity":"note","actorId":"reviewer-1","summary":"Token is logged"},{"changeId":"add-login","round":1,"seq":2,"severity":"blocker","actorId":"reviewer-1","summary":"No rate limit"}]'
+```
+
+`--input` never carries `--commit` or `--plan-digest`, and the destructive
+leaves below take one object only.
+
+### Preview, then `--commit`
+
+The five commands that delete or rewrite existing data (`canon purge`,
+`canon tier age`, `canon ledger compact`, `canon artifacts move`,
+`canon migrate`) act in two steps. The bare run previews: it writes nothing,
+exits 0 and prints the effects and a `planDigest`. Read the effects, then act
+with `--commit --plan-digest <planDigest>`. It refuses (`PLAN_CHANGED`) when
+the plan differs from the one you previewed, so run the preview again. Appends
+and state transitions (`gate promote`, `subject move`) run directly. Where a
+preview helps elsewhere (`init`, `skills install`, `export`, `inventory sync`,
+`subject adopt`, …) `--dry-run` validates fully and writes nothing.
+
+```bash
+canon purge --kind session --before 2026-01-01
+```
+
+## Upgrading a repo from 0.27
+
+0.28 changed the CLI grammar with no aliases: an old spelling fails with exit 2
+and an `error.hint` naming the replacement. `canon status`, `canon gate check`
+and `canon context` warn when the repo holds 0.27-era state and put
+`canon migrate --json` first in `meta.next`. Then:
+
+1. `canon migrate` previews and prints the `planDigest`.
+2. `canon migrate --commit --plan-digest <digest>` with that digest applies it.
+   It moves the layout, rewrites canon's own hooks and scripts, compacts the
+   ledger, replaces an old full skill with the stub, and backs up every file it
+   rewrites under `.canon/migrate-backup/`. It refuses uncommitted changes
+   under a path it moves.
+3. `canon skills install` refreshes the stub and the scripts; `canon skills check`
+   confirms them.
+
+**Done when:** `canon migrate` reports nothing left to move, `canon skills check` exits 0, and `canon status` and `canon gate check` no longer warn about 0.27 state.
+
+## Setup and provider projection
 
 ```bash
 canon init                                   # canon.yaml, starter policy (--policy light|standard|strict, default strict; see canon-policy), AGENTS.md block, commented plans examples
@@ -152,40 +270,78 @@ canon skills check                           # read-only drift check; exit 1 (SK
 canon skills doctor                          # diagnostics, incl. a stray canon projection for an unselected provider and a projection a formatter rewrote, and `orphan:` lines for projected files the bundle no longer ships; never deletes user files
 ```
 
+`install` writes, per selected harness, a short `SKILL.md` stub (this file's
+frontmatter plus a pointer to `canon skills show canon`) and the `scripts/**`
+sidecars; the guides themselves are not copied, they come from the binary.
+Claude gets `.claude/skills/canon/`, Codex `.agents/skills/canon/`, OMP
+`.omp/skills/canon/`, Pi `.pi/skills/canon/` (the retrieve script is a sidecar,
+not an installed hook). `check` reports a stub written by another canon
+version; `install` rewrites it. The harness list lives in `canon.yaml` as
+`skills: { providers: [...] }`; change it with `canon skills install --providers=<list>`,
+never by assuming a default.
+
 `install` and `doctor` end with `owned-paths:`, the globs of every path
 canon writes. Add them to the repo's formatter and linter ignore lists; a
 formatter that rewrites a projection or a ledger record makes canon read
 drift (`doctor` reports it as `formatter-rewritten` and names the entry to
 add). Specs, `policy.yaml` and the changes are written by hand and are not
-on the list. The harness list lives in `canon.yaml` as
-`skills: { providers: [...] }`; change it with `canon skills install --providers=<list>`,
-never by assuming a default. The projection is a read-only copy: Claude
-`.claude/skills/canon/`, Codex `.agents/skills/canon/`, OMP
-`.omp/skills/canon/`, Pi `.pi/skills/canon/`, each with `reference/**` and
-`scripts/**` sidecars (the retrieve script is a sidecar, not an installed hook).
-
-### Route by task
-
-- **Fix a bug:** the approved change if there is one, else the planner (`canon change new`); first a failing run of the scenario (`canon scenario new --case failure`, then `canon evidence add`), then the fix. `reference/role-implementer.md`.
-- **Add or change a feature:** `canon subject new`, `canon change new`, then the brief. `reference/role-planner.md`.
-- **Pure refactor, dependency, build, CI or infra:** `canon change new <slug> --subject-id <id> --kind chore`; data or interface changes are not chores. `reference/role-planner.md`.
-- **Review someone's change:** `CANON_ROLE=reviewer`, `canon brief check --change-id <slug>`. `reference/role-reviewer.md`.
-- **Resume:** `canon status --json`, then follow `meta.next`. `reference/role-orchestrator.md`.
-- **Plan more work on a live subject:** `canon change new <slug> --subject-id <id>` (it warns until the brief is approved; `canon subject unadopt` parks a draft). `reference/canon-subject.md`, `reference/role-planner.md`.
-- **Upgrade canon in a repo:** `canon migrate --dry-run`. `reference/role-orchestrator.md`.
-- **Your role's steps:** `reference/role-planner.md`, `role-implementer.md`, `role-reviewer.md`, `role-orchestrator.md`.
-- **Where the repo stands, subjects and changes:** `reference/canon-subject.md` (`canon status`, `canon subject new|adopt|status`, `canon change new`).
-- **Write or reorganize `.feature` specs:** `reference/canon-authoring.md` before editing; use the scaffold.
-- **Fields, enums, policy bindings:** `reference/canon-context.md` and `reference/canon-vocab.md`.
-- **Replayable run inputs / versioned prompts:** `reference/canon-context.md`, then `canon context-pack new|show|verify` and `canon prompt add|show` with repository-relative JSON manifests.
-- **Validate or index specs:** `reference/canon-fmt.md` and `reference/canon-inventory.md`.
-- **Evidence, gates, imported-plan task checkboxes, hooks:** `reference/canon-gate.md`.
-- **Findings and reviews:** `reference/canon-review.md`.
-- **Ingest artifacts, sessions or plans:** `reference/canon-artifact-ingest.md`, `canon-session-ingest.md`, or `canon-plan-import.md`.
-- **Storage, policy, plugins, strategy learning:** `reference/canon-storage.md`, `canon-policy.md`, `canon-plugins.md`, or `canon-learn.md`.
-- **Dispatch guidance:** `reference/canon-retrieve.md`; load `scripts/canon-retrieve-pre-dispatch.sh` when wiring hooks.
-- **Reports and dashboards:** `reference/canon-report-dashboard.md`.
-
-### Safety contract
-
-`canon status`, `canon format <root>`, `canon skills check`, and `canon gate check` are read-only. Do not hand-edit generated reports, provenance lines, locks, or task evidence. Inspect `canon context` before authoring typed artifacts, and treat every failure class as actionable evidence rather than bypassing the gate.
+on the list.
+
+**Done when:** `canon skills check` exits 0 and `canon skills doctor` lists no `orphan:`, `stray:` or `outdated:` line.
+
+## Route by task
+
+- **Fix a bug:** the approved change if there is one, else the planner (`canon change new`); first a failing run of the scenario (`canon scenario new --case failure`, then `canon evidence add`), then the fix. `canon skills show role-implementer`.
+- **Add or change a feature:** `canon subject new`, `canon change new`, then the brief. `canon skills show role-planner`.
+- **Pure refactor, dependency, build, CI or infra:** `canon change new <slug> --subject-id <id> --change-kind chore`; data or interface changes are not chores. `canon skills show role-planner`.
+- **Review someone's change:** `CANON_ROLE=reviewer`, `canon brief check <slug>`. `canon skills show role-reviewer`.
+- **Resume:** `canon status --json`, then follow `meta.next`. `canon skills show role-orchestrator`.
+- **Plan more work on a live subject:** `canon change new <slug> --subject-id <id>` (it warns until the brief is approved; `canon subject unadopt` parks a draft). `canon skills show canon-subject`, `canon skills show role-planner`.
+- **Upgrade canon in a repo:** `canon migrate` (previews), then `canon migrate --commit --plan-digest <digest>`, then `canon skills install`. See "Upgrading a repo from 0.27" above and `canon skills show role-orchestrator`.
+
+**Done when:** you have named your role and loaded its guide, and `canon status --json` lists your next step in `meta.next`.
+
+## Safety contract
+
+`canon status`, `canon format`, `canon skills check`, `canon skills show` and
+`canon gate check` do not change the repo's records. Do not hand-edit generated
+reports, provenance lines, locks, or task evidence. Inspect `canon context`
+before authoring typed artifacts, and treat every failure class as actionable
+evidence rather than bypassing the gate.
+
+## Guides: `canon skills show <name>`
+
+Every name below is a guide built into the binary. Load only the one the
+current step needs.
+
+| Name | What it is for |
+| --- | --- |
+| `canon` | This core guide: the loop, driving the CLI, routing. |
+| `role-planner` | Planner steps 1–2: subject, change, PRD brief, the human stop. |
+| `role-implementer` | Implementer steps 3–6: scenarios, units, code, evidence. |
+| `role-reviewer` | Reviewer step 7: findings and signed reviews in a separate session. |
+| `role-orchestrator` | Orchestrator step 8: dispatch, transitions, resuming, upgrading. |
+| `brief-shape` | Brief pass: the structure `canon brief check` expects. |
+| `brief-clarify` | Brief pass: turn open points into questions a human answers in one reply. |
+| `brief-harden` | Brief pass: make flow and step detail agree, with failure paths. |
+| `brief-align` | Brief pass: scenarios cover the brief's flow and the brief still says what they prove. |
+| `brief-polish` | Brief pass: make the brief readable once (clears `prose.*` advisories). |
+| `canon-subject` | Status, subjects and changes: `canon subject new|adopt|show|move`, `canon change new`. |
+| `canon-authoring` | Write or reorganize `.feature` specs; the scaffold. |
+| `canon-context` | `canon context`: fields, enums, policy bindings, context packs and prompts. |
+| `canon-vocab` | Typed authoring vocabulary and the handoff template. |
+| `canon-fmt` | `canon format`: validate a spec or artifact corpus. |
+| `canon-inventory` | `canon inventory sync`: index specs into scenario records. |
+| `canon-gate` | Evidence, gates, task checkboxes, hooks. |
+| `canon-review` | Findings and reviews. |
+| `canon-artifact-ingest` | `canon ingest records`: artifacts into verdict trajectories. |
+| `canon-session-ingest` | `canon ingest sessions`: agent transcripts into session records. |
+| `canon-plan-import` | `canon ingest plans`: plan state into change and task records. |
+| `canon-storage` | Storage rungs, tiers, retention, export, purge. |
+| `canon-policy` | The policy and the CEL expressions behind it. |
+| `canon-plugins` | Plugin overlays on core records. |
+| `canon-learn` | Strategy memory: promote, approve, roll back. |
+| `canon-retrieve` | Dispatch-time guidance (`canon retrieve`); `scripts/canon-retrieve-pre-dispatch.sh` is the hook sidecar. |
+| `canon-report-dashboard` | `canon report build|check|snapshot` and `canon dashboard`. |
+
+**Done when:** `canon skills show <name>` prints the guide you needed; a name that is not in the table is a usage error (exit 2) whose `error.expected` lists the valid ones.

package/dist/skills/reference/brief-align.md

@@ -29,9 +29,11 @@ A chore adds no scenarios and has no flow: this pass does not apply to it.
 
 `canon brief check` no longer lists the coverage rules; `canon status` shows every step with a failure scenario.
 
+**Done when:** `canon brief check <slug> --json` lists neither `brief.flow-uncovered` nor `brief.flow-no-failure` (read `data.findings[]`), and `canon status` shows each flow step with a scenario and a failure scenario.
+
 ## Next
 
-Implement, evidence and review (loop steps 5 to 7). If the brief had to change, the human answers again.
+Implement, evidence and review (loop steps 5 to 7). If the brief had to change, the human answers again with `canon brief approve` (theirs; agent roles are refused).
 
 ## Invariants (every brief pass)
 
@@ -39,4 +41,4 @@ Implement, evidence and review (loop steps 5 to 7). If the brief had to change,
 - Explaining writes nothing. Asked what a finding means or what a pass would do, answer in chat and leave the brief untouched.
 - No pass requires another as a prerequisite. Run the one the findings or the human point at, in any order.
 - A pass closes only the findings it rechecked: rerun `canon brief check` after the edit and report a finding as closed only when it is gone from that run. Never claim a rule you did not rerun.
-- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and `canon brief approve` again.
+- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and the human's `canon brief approve` again (agent roles are refused).

package/dist/skills/reference/brief-clarify.md

@@ -1,8 +1,8 @@
 # Brief pass: clarify
 
 Turn what is unresolved into questions a human can answer in one reply, and
-make every assumption explicit. Run it when `canon brief` says lines under
-the questions section are still open, or the request left a decision the
+make every assumption explicit. Run it when `canon brief show` names lines under
+the questions section that are still open, or the request left a decision the
 brief quietly made.
 
 ## Scope
@@ -27,11 +27,13 @@ brief that decides something the request did not say.
 
 ## Verify
 
-Every open line is a question with a proposed default or a stated assumption. `canon brief check` still has no blockers (the pass changes no structure). `canon brief` still counts the lines left open, and those go in the report to the human, not away.
+Every open line is a question with a proposed default or a stated assumption. `canon brief check` still has no blockers (the pass changes no structure). `canon brief show` still counts the lines left open, and those go in the report to the human, not away.
+
+**Done when:** `canon brief check <slug>` exits 0 and every open line under Questions and assumptions is a question with a proposed default or a stated assumption; read the count of lines left open in the `clarify` step of `canon brief show <slug> --json` (it is absent when none are open) and put it in the report to the human.
 
 ## Next
 
-`harden` if the flow changed; otherwise report to the human, who answers the questions with the approval.
+`harden` if the flow changed; otherwise report to the human, who answers the questions and approves (`canon brief approve` is theirs; agent roles are refused).
 
 ## Invariants (every brief pass)
 
@@ -39,4 +41,4 @@ Every open line is a question with a proposed default or a stated assumption. `c
 - Explaining writes nothing. Asked what a finding means or what a pass would do, answer in chat and leave the brief untouched.
 - No pass requires another as a prerequisite. Run the one the findings or the human point at, in any order.
 - A pass closes only the findings it rechecked: rerun `canon brief check` after the edit and report a finding as closed only when it is gone from that run. Never claim a rule you did not rerun.
-- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and `canon brief approve` again.
+- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and the human's `canon brief approve` again (agent roles are refused).

package/dist/skills/reference/brief-harden.md

@@ -30,9 +30,11 @@ brief has none of them: harden its Invariants and Checks instead.
 
 `canon brief check` no longer lists `brief.flow-duplicate-id` or `brief.detail-mismatch`; every flow id has a detail subheading and an acceptance line with a failure path.
 
+**Done when:** `canon brief check <slug> --json` lists neither `brief.flow-duplicate-id` nor `brief.detail-mismatch` (read `data.findings[]`) and every flow id has a detail subheading and an acceptance line with a failure path.
+
 ## Next
 
-`align` once scenarios exist; `polish` for prose; otherwise report to the human.
+`align` (`canon skills show brief-align`) once scenarios exist; `polish` (`canon skills show brief-polish`) for prose; otherwise report to the human.
 
 ## Invariants (every brief pass)
 
@@ -40,4 +42,4 @@ brief has none of them: harden its Invariants and Checks instead.
 - Explaining writes nothing. Asked what a finding means or what a pass would do, answer in chat and leave the brief untouched.
 - No pass requires another as a prerequisite. Run the one the findings or the human point at, in any order.
 - A pass closes only the findings it rechecked: rerun `canon brief check` after the edit and report a finding as closed only when it is gone from that run. Never claim a rule you did not rerun.
-- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and `canon brief approve` again.
+- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and the human's `canon brief approve` again (agent roles are refused).

package/dist/skills/reference/brief-polish.md

@@ -99,7 +99,7 @@ and the result.
 ### `prose.paragraph-length`
 
 Normative sections. Catches a paragraph of more than five sentences. Fix: the
-compression pass in `role-planner.md`: keep the sentences that state a
+compression pass in `canon skills show role-planner`: keep the sentences that state a
 condition, an action, a result or a number; make three or more parallel
 items a list; delete or move the rest.
 
@@ -199,7 +199,7 @@ states the measured value and the budget. Section budgets (ko / en
 characters): Intent 400 / 700, Outcome 500 / 900, Flow 800 / 1500, Detail
 2500 / 3500, Acceptance 1000 / 1800, Questions 800 / 1200, Invariants and
 Checks 800 / 1500 each (Out of scope has none); whole brief 4000 / 6000. Fix: the
-compression pass in `role-planner.md`: delete sentences that restate another
+compression pass in `canon skills show role-planner`: delete sentences that restate another
 section, turn parallel items into a list or table, move assumptions to
 Questions and assumptions and a not-doing list to Out of scope. A brief this
 long usually says several things twice. A waiver for the whole-brief budget
@@ -216,7 +216,7 @@ uses the section key `brief`.
 ## The loop
 
 1. Fix the mode problems above, then the findings, section by section.
-2. Run `canon brief check --change-id <slug> --json`.
+2. Run `canon brief check <slug> --json`: the findings are in `data.findings[]`.
 3. Repeat until no advisory remains, or each remaining one is waived with a reason.
 4. Stop and report to the human, in the brief's language. Do not loop further: a clean run says nothing about whether the brief is good, only that these counts are within budget.
 
@@ -232,9 +232,11 @@ uses the section key `brief`.
 
 `canon brief check` no longer lists the `prose.*` findings you rewrote, or lists them as waived with a reason; no blockers appeared.
 
+**Done when:** `canon brief check <slug> --json` lists no `prose.*` finding (read `data.findings[]`) except those waived with a reason (`data.waivers[]`), and `data.counts` shows no blocker.
+
 ## Next
 
-Report to the human and `canon brief approve` from their answer.
+Report to the human, who approves with `canon brief approve` (theirs; agent roles are refused).
 
 ## Invariants (every brief pass)
 
@@ -242,4 +244,4 @@ Report to the human and `canon brief approve` from their answer.
 - Explaining writes nothing. Asked what a finding means or what a pass would do, answer in chat and leave the brief untouched.
 - No pass requires another as a prerequisite. Run the one the findings or the human point at, in any order.
 - A pass closes only the findings it rechecked: rerun `canon brief check` after the edit and report a finding as closed only when it is gone from that run. Never claim a rule you did not rerun.
-- Write in the brief's language (detected from the text, or `language:` in `canon.yaml` when set). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and `canon brief approve` again.
+- Write in the brief's language (detected from the text, or `language:` in `canon.yaml` when set). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and the human's `canon brief approve` again (agent roles are refused).

package/dist/skills/reference/brief-shape.md

@@ -34,9 +34,11 @@ marker, never by heading text.
 
 `canon brief check` reports none of the rules above. Report only the ones it no longer lists.
 
+**Done when:** `canon brief check <slug> --json` lists none of the rules above (read `data.findings[]`); report only the ones it no longer lists.
+
 ## Next
 
-`clarify` if the Questions section still has open lines; `harden` if flow and detail disagree; otherwise report to the human and `canon brief approve` from their answer.
+`clarify` if the Questions section still has open lines; `harden` if flow and detail disagree; otherwise report to the human, who approves with `canon brief approve` (theirs; agent roles are refused).
 
 ## Invariants (every brief pass)
 
@@ -44,4 +46,4 @@ marker, never by heading text.
 - Explaining writes nothing. Asked what a finding means or what a pass would do, answer in chat and leave the brief untouched.
 - No pass requires another as a prerequisite. Run the one the findings or the human point at, in any order.
 - A pass closes only the findings it rechecked: rerun `canon brief check` after the edit and report a finding as closed only when it is gone from that run. Never claim a rule you did not rerun.
-- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and `canon brief approve` again.
+- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and the human's `canon brief approve` again (agent roles are refused).