@journeykit/canon 0.34.0 → 0.35.0

package/dist/skills/SKILL.src.md

@@ -221,20 +221,20 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
   `{"ok":true,"data":…,"meta":…}`; failure is
   `{"ok":false,"error":{…},"meta":…}` (a check that fails keeps its report in
   `data`). `meta` carries `tool`, `toolVersion`, `contract` (`atip/1`),
-  `contractVersion` (`1.1`), `schemaVersion`,
+  `contractVersion` (`1.2`), `schemaVersion`,
   `command`, and when present `next`, `warnings` (`[{code, message}]`) and
   `page`; a repeated write that changed nothing reports `data.unchanged: true`.
   Absent members are omitted, never `null` or `[]` (a value you sent empty comes back as `received: ""`).
   Read the members you know and ignore the ones you do not: a later canon
   adds members, and a value of a closed set you have not seen (a `severity`, an
   `outcome`, a `reason`) is one item to leave out, never a reason to reject the document. A paged list puts
-  `meta.page.nextCursor` on the call's `meta.next` as `--cursor <nextCursor>`;
-  no `nextCursor` means no more.
+  `meta.page.nextCursor` in the first entry of the call's `meta.next` as `--cursor=<nextCursor>`
+  (run that entry as it is); no `nextCursor` means no more.
   On failure branch on `error.code`, and on `error.reason` where the code has
   reasons (`INPUT_INVALID` says `NOT_JSON`, `UNKNOWN_KEY`, `STDIN_TTY`, … so you
   know whether to fix the JSON or the shell); fix the option `error.field` names
   using the `error.expected` values (`field` is an option name, or a JSON
-  pointer such as `/items/2/scenario` into an `--input` document), and
+  pointer such as `/2/scenario` into an `--input` document, `/<index>/<key>` in a batch), and
   follow `error.hint`: it is one runnable command line that starts with `canon`, the
   same with `<PLACEHOLDER>`s you fill in, or one sentence. The codes
   are stable; `canon schema --errors --json` lists them with their reasons and
@@ -258,7 +258,7 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
   has blockers; the approval step appears only when the brief is clean and
   unapproved.
 - Page long lists with `--limit <n>` and `--cursor <nextCursor>` (`--all`
-  for everything); a cursor holds only for the call that issued it, so change nothing but `--limit`, `--all` and `--fields` (`CURSOR_INVALID` with `error.reason` `ARGUMENTS_CHANGED` otherwise). Project fields with `--fields a,b`
+  for everything); a cursor holds only for the call that issued it, so change nothing but `--limit`, `--all`, `--fields` and `--json`, and keep `CANON_ROLE` as it was (`CURSOR_INVALID` with `error.reason` `ARGUMENTS_CHANGED` otherwise; `FOREIGN` for a cursor of another command or another canon version: start again from the first page). `--limit`, `--cursor`, `--all` and `--fields` are flags: an `--input` document key of that name is `INPUT_INVALID` with `reason` `FLAG_ONLY_KEY`. Project fields with `--fields a,b`
   (`status`, `export`, `query`, `finding list`, `divergence list`, `context`): the paths `canon schema <command> --json` lists under `outputs[].fields`, spelled as the answer spells them; `meta.fields` lists what was kept.
 - `--override-reason <text>` is the only way to proceed past a waivable
   refusal; it is recorded, echoed in `data.overrides[]` and listed by `status`
@@ -277,10 +277,11 @@ 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, `BATCH_INCOMPLETE`) and re-running the same batch reports the finished elements
-`unchanged`. A typo in a key is refused (`INPUT_INVALID`, `field` naming the key), never dropped.
+before anything is written, and that check reads no state: an invalid element writes nothing and exits 2 with
+its own code, `error.field` pointing at `/<i>/<key>` and no `data`. An element that fails when it runs (the object
+it names does not exist) stops the batch: exit 1, `BATCH_INCOMPLETE`, `error.field` exactly `/<i>`, the element
+`failed` with its own `error` (no `data`), the later ones `skipped`, and the earlier ones done (not undone). Re-running the same batch reports the finished elements
+`unchanged`. A typo in a key is refused (`INPUT_INVALID`, `field` naming the key), never dropped; a document with several problems reports them all, the first as the error and every one in `error.details` in the order the document wrote its keys, and a value outside a closed set is `INPUT_INVALID` too (`reason` `INVALID_VALUE`, `field` the key), not `USAGE`. Every non-empty line of an NDJSON file is a document (a `#` line is not a comment). Integers compare by number: `1`, `"1"` and `--round +1` are one value, and `"+1"`, `"0x1"` and `1.0` in a document are `INVALID_VALUE`.
 `canon schema <command> --json` shows the leaf's `input`: the schema of one document and a complete `example`.
 
 ```text
@@ -329,12 +330,18 @@ and `canon context` warn when the repo holds 0.27-era state and put
 ## 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
-canon init --providers=claude,codex          # harnesses for the canon skill; without it init asks on a terminal, else takes the detected .claude/.codex/.omp/.pi
-canon skills install                         # follows canon.yaml skills.providers (else the install lock's, else the detected ones; none detected installs nothing); prunes projected files the bundle no longer ships when their bytes match the lock, keeps a modified one and reports `kept:`
-canon skills install --providers=claude,codex,omp,pi   # any subset or none; rewrites skills.providers
-canon skills check                           # read-only drift check; exit 1 (SKILLS_DRIFT) names each orphan, a projected file the bundle no longer ships
-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
+# canon.yaml, starter policy (--policy light|standard|strict, default strict; see canon-policy), AGENTS.md block, commented plans examples
+canon init
+# harnesses for the canon skill; without it init takes the detected .claude/.codex/.omp/.pi (it never asks)
+canon init --providers=claude,codex
+# follows canon.yaml skills.providers (else the install lock's, else the detected ones; none detected installs nothing); prunes projected files the bundle no longer ships when their bytes match the lock, keeps a modified one and reports `kept:`
+canon skills install
+# any subset or none; rewrites skills.providers
+canon skills install --providers=claude,codex,omp,pi
+# read-only drift check; exit 1 (SKILLS_DRIFT) names each orphan, a projected file the bundle no longer ships
+canon skills check
+# 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
+canon skills doctor
 ```
 
 `install` writes, per selected harness, a short `SKILL.md` stub (this file's

package/dist/skills/reference/canon-artifact-ingest.md

@@ -9,9 +9,12 @@ verdicts, and writes idempotently.
 ## `canon ingest records [--repo <dir>] [--watch]`
 
 ```bash
-canon ingest records                # one pass over the repo's artifacts
-canon ingest records --repo ../svc  # a specific repo
-canon ingest records --watch        # poll loop
+# one pass over the repo's artifacts
+canon ingest records
+# a specific repo
+canon ingest records --repo ../svc
+# poll loop
+canon ingest records --watch
 ```
 
 Source roots resolve from `canon.yaml`'s `artifacts.sources` config

package/dist/skills/reference/canon-authoring.md

@@ -92,11 +92,14 @@ a scoped gate.
 ## The commands — and the one thing you never type
 
 ```bash
-canon feature new checkout.cart --title "Cart"                       # once per surface
+# once per surface
+canon feature new checkout.cart --title "Cart"
+# once per behavior
 canon scenario new checkout.cart.01 --title "Adding an item raises the count" \
-  --subject checkout-core --lane behavior --case happy               # once per behavior
+  --subject checkout-core --lane behavior --case happy
+# and its failure path
 canon scenario new checkout.cart.04 --title "Adding an out-of-stock item is refused" \
-  --subject checkout-core --lane behavior --case failure             # and its failure path
+  --subject checkout-core --lane behavior --case failure
 ```
 
 There is no format or sync step after these: the scaffold writes a

package/dist/skills/reference/canon-context.md

@@ -13,9 +13,12 @@ deterministic authoring surface.
 ## `canon context [--repo <dir>] [--json]`
 
 ```bash
-canon context                 # compact human outline (prompt-injectable)
-canon context --json          # the full machine-readable surface
-canon context --repo ../other # resolve a specific repo's surface
+# compact human outline (prompt-injectable)
+canon context
+# the full machine-readable surface
+canon context --json
+# resolve a specific repo's surface
+canon context --repo ../other
 ```
 
 The outline opens with a short header, then a blank line, then the

package/dist/skills/reference/canon-fmt.md

@@ -9,7 +9,8 @@ rewrites or mutates the corpus — it only validates and reports.
 ## Running
 
 ```bash
-canon format spec   # e.g. a consumer repo's spec/
+# e.g. a consumer repo's spec/
+canon format spec
 ```
 
 With no operand, `canon format` validates every `specs.roots[]` entry of

package/dist/skills/reference/canon-gate.md

@@ -42,8 +42,10 @@ corpus and runs them, printing every violation grouped by failure class.
 when `--release` is passed.
 
 ```bash
-canon gate check --repo .            # ordinary evaluation
-canon gate check --repo . --release  # + trust-below-required
+# ordinary evaluation
+canon gate check --repo .
+# + trust-below-required
+canon gate check --repo . --release
 ```
 
 Exit `0` clean, `1` gate-red (any violation), `2` usage/load failure
@@ -314,8 +316,8 @@ check `canon status` and the ship guard use; see
 `--task`:
 
 ```stderr
-canon evidence add: unreviewed-promotion demo-subject — evidence for world.demo.01: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line, so the human has not answered it; once they do, record their words with `canon brief approve c-demo --approver <the human> --note "<their words>"`
-canon evidence add: refused — stop and get the human's answer to the brief: nothing is built or attested for a subject before its brief is approved. Show it (`canon brief show --body`), ask with the harness question tool, and on their explicit approval record it with `canon brief approve --approver <their name> --note "<their words>" --relayed-via <the question tool> --actor <your actor id> --digest <change>=<the digest shown>` (or they approve on `canon dashboard`); never unset your role to run it; to attest anyway, pass --override-reason <text>, which is recorded on the evidence record
+stderr: canon evidence add: unreviewed-promotion demo-subject — evidence for world.demo.01: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line, so the human has not answered it; once they do, record their words with `canon brief approve c-demo --approver <the human> --note "<their words>"`
+stderr: canon evidence add: refused — stop and get the human's answer to the brief: nothing is built or attested for a subject before its brief is approved. Show it (`canon brief show --body`), ask with the harness question tool, and on their explicit approval record it with `canon brief approve --approver <their name> --note "<their words>" --relayed-via <the question tool> --actor <your actor id> --digest <change>=<the digest shown>` (or they approve on `canon dashboard`); never unset your role to run it; to attest anyway, pass --override-reason <text>, which is recorded on the evidence record
 ```
 
 For a change from an external plan with no canon brief yet, the first
@@ -553,7 +555,7 @@ current pinned review saw, `canon evidence add` prints one line per
 review it makes stale (its verdict or checks differ from what the review saw), with the command that re-pins it:
 
 ```stderr
-canon evidence add: review by `reviewer-2` of cart.add.01 is now stale (this record's verdict or checks differ from what it saw); re-pin it: canon review scenario cart.add.01 --project root --actor reviewer-2 --role reviewer --original-spec-ref specs/kind=feature/area=cart/add.feature
+stderr: canon evidence add: review by `reviewer-2` of cart.add.01 is now stale (this record's verdict or checks differ from what it saw); re-pin it: canon review scenario cart.add.01 --project root --actor reviewer-2 --role reviewer --original-spec-ref specs/kind=feature/area=cart/add.feature
 ```
 
 The decision is the gate's own (the same stale-review rule `canon gate
@@ -737,8 +739,10 @@ prints the plan (target path + assigned `run_seq` per candidate) without
 writing or deleting.
 
 ```bash
-canon gate promote --repo .            # land every staged candidate
-canon gate promote --repo . --dry-run  # preview only
+# land every staged candidate
+canon gate promote --repo .
+# preview only
+canon gate promote --repo . --dry-run
 ```
 
 Which writes need this step: `evidence add`, `finding add` and `finding

package/dist/skills/reference/canon-inventory.md

@@ -14,7 +14,7 @@ same code this command runs, scoped to the changed files, and say so in one
 stderr line:
 
 ```stderr
-canon artifacts store: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
+stderr: canon artifacts store: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
 ```
 
 `canon status` and `canon gate check` are read commands and write nothing:
@@ -76,14 +76,14 @@ author .feature corpus (canon scenario new)
 scenario index                  # refreshed by the writers; `canon inventory sync` rebuilds it
         │
         ▼
-canon review scenario           # attests a review — see canon-inventory downstream / canon-gate
-canon divergence add|resolve|defer|accept|list   # tracks/resolves a divergence
-canon gate check [--release]    # trust-ladder / staleness / coverage — see canon-gate
+review:   canon review scenario           # attests a review — see canon-inventory downstream / canon-gate
+diverge:  canon divergence add|resolve|defer|accept|list   # tracks/resolves a divergence
+gate:     canon gate check [--release]    # trust-ladder / staleness / coverage — see canon-gate
         │
         ▼
-canon ingest records            # with artifacts.native_records: true in canon.yaml —
-                                # feeds review/divergence verdicts into the flywheel
-                                # (see canon-artifact-ingest)
+ingest:   canon ingest records            # with artifacts.native_records: true in canon.yaml —
+                                          # feeds review/divergence verdicts into the flywheel
+                                          # (see canon-artifact-ingest)
 ```
 
 Every stage after the index joins on the SAME `(project_id, scenario_id)`
@@ -92,9 +92,12 @@ pair it materializes — one identity scheme, no second one.
 ## `canon inventory sync [--repo <dir>] [--spec-root <dir>]`
 
 ```bash
-canon inventory sync                        # every canon.yaml specs.roots[] entry
-canon inventory sync --repo ../svc          # a specific repo
-canon inventory sync --spec-root ./specs    # ad hoc: ignore canon.yaml entirely
+# every canon.yaml specs.roots[] entry
+canon inventory sync
+# a specific repo
+canon inventory sync --repo ../svc
+# ad hoc: ignore canon.yaml entirely
+canon inventory sync --spec-root ./specs
 ```
 
 Per configured root, in order:

package/dist/skills/reference/canon-plan-import.md

@@ -64,9 +64,12 @@ canon ingest plans --dialect openspec --plan-source ../other-repo
 ## 2. Run the import
 
 ```bash
-canon ingest plans                 # .canon/changes/ + every configured source
-canon ingest plans --json          # machine-readable outcome
-canon ingest plans --repo ../svc   # a specific repo root
+# .canon/changes/ + every configured source
+canon ingest plans
+# machine-readable outcome
+canon ingest plans --json
+# a specific repo root
+canon ingest plans --repo ../svc
 ```
 
 Per source the summary reports `changes_parsed`/`tasks_parsed`,

package/dist/skills/reference/canon-plugins.md

@@ -49,9 +49,12 @@ overlays:
 Drive it through the sync command (never hand-write records):
 
 ```bash
-canon plugin sync porting                       # every canon.yaml specs.roots[] entry
-canon plugin sync porting --repo ../svc         # a specific repo
-canon plugin sync porting --spec-root ./specs   # ad hoc: ignore canon.yaml
+# every canon.yaml specs.roots[] entry
+canon plugin sync porting
+# a specific repo
+canon plugin sync porting --repo ../svc
+# ad hoc: ignore canon.yaml
+canon plugin sync porting --spec-root ./specs
 ```
 
 `canon plugin sync <plugin-id>` resolves the manifest, then for each
@@ -70,9 +73,12 @@ error; the next step (3) reads the overlay back.
 ## 3. Project a read
 
 ```bash
-canon query --kind scenario --plugin porting          # human table, projected fields appended
-canon query --kind scenario --plugin porting --json   # merged record bodies
-canon query --kind scenario                           # no --plugin: byte-identical to the core view
+# human table, projected fields appended
+canon query --kind scenario --plugin porting
+# merged record bodies
+canon query --kind scenario --plugin porting --json
+# no --plugin: byte-identical to the core view
+canon query --kind scenario
 ```
 
 `--plugin <id>` folds the plugin's overlay records (latest-by-

package/dist/skills/reference/canon-report-dashboard.md

@@ -40,7 +40,8 @@ Renders the current ten-panel report to `<repo>/.canon/REPORT.md`.
 subcommand uses — omit it (or pass `.`) to run from any subdirectory.
 
 ```bash
-canon report build           # writes .canon/REPORT.md
+# writes .canon/REPORT.md
+canon report build
 canon report build --repo /path/to/repo
 ```
 
@@ -67,7 +68,8 @@ committed `.canon/REPORT.md`:
   `canon report build`).
 
 ```bash
-canon report check   # wire into CI exactly like canon format / canon gate check
+# wire into CI exactly like canon format / canon gate check
+canon report check
 ```
 
 Wire it as a CI step or pre-push hook the same way `canon gate
@@ -126,7 +128,8 @@ canon report snapshot /tmp/canon-snap
 Serves the dashboard web app locally, pointed at a real snapshot:
 
 ```bash
-canon dashboard                       # regenerates a fresh snapshot every run, serves it
+# regenerates a fresh snapshot every run, serves it
+canon dashboard
 canon dashboard --snapshot /tmp/canon-snap --port 8080
 ```
 

package/dist/skills/reference/canon-review.md

@@ -468,7 +468,7 @@ With `require_review` present, `canon subject move <id> --to <state>`
 prints on stderr which review checks it ran or skipped:
 
 ```stderr
-canon subject move: review guard for building → verifying (spec_coverage.require_review, scope: verifying, shipped)
+stderr: canon subject move: review guard for building → verifying (spec_coverage.require_review, scope: verifying, shipped)
   ran unreviewed-promotion — every owned scenario needs a signed review, current with the spec and evidence it pinned, by an actor, and from a session, other than its evidence's
   ran open-blocker — 1 adopted change(s) checked for open blocker findings
 ```

package/dist/skills/reference/canon-session-ingest.md

@@ -18,11 +18,16 @@ concurrency outgrows sqlite's single-writer mode.
 ## `canon ingest sessions [--watch] [--interval-secs N] [--home <dir>] [--full] [--all-workspaces]`
 
 ```bash
-canon ingest sessions                   # one pass over this project's sources
-canon ingest sessions --watch           # poll every 30s (see --interval-secs)
-canon ingest sessions --full            # ignore the watermark; re-parse every in-scope file
-canon ingest sessions --all-workspaces  # machine-wide scan
-canon ingest sessions --home /custom    # override the scan-root home ($HOME)
+# one pass over this project's sources
+canon ingest sessions
+# poll every 30s (see --interval-secs)
+canon ingest sessions --watch
+# ignore the watermark; re-parse every in-scope file
+canon ingest sessions --full
+# machine-wide scan
+canon ingest sessions --all-workspaces
+# override the scan-root home ($HOME)
+canon ingest sessions --home /custom
 ```
 
 **Done when:** the run summary (below) ends with `malformed records … : 0`
@@ -175,7 +180,8 @@ These events interleave with `token_usage` events in one deterministic
 order (directive-before-token on a timestamp tie). Query them with:
 
 ```bash
-canon query --kind event   # filter detail.label == "user_directive"
+# filter detail.label == "user_directive"
+canon query --kind event
 ```
 
 ## Reading the run summary

package/dist/skills/reference/canon-storage.md

@@ -105,9 +105,9 @@ canon query --kind trajectory --json
 
 # Page a long result and keep only the fields you need; `meta` carries
 # `page` = {returned, total, nextCursor} and `fields` = the paths kept; a present `nextCursor` means more, and
-# `meta.next` repeats the call with `--cursor <nextCursor>` (`--all` returns everything). A cursor is bound to the
-# call that issued it: change only `--limit`, `--all` or `--fields`; any other change is `CURSOR_INVALID`
-# (`error.reason` `ARGUMENTS_CHANGED`). A field path is the record's own key, written as it is.
+# `meta.next` repeats the call's explicit arguments with `--cursor=<nextCursor>` (`--all` returns everything). A cursor is bound to the
+# call that issued it, `CANON_ROLE` included: change only `--limit`, `--all`, `--fields` or `--json`; any other change is `CURSOR_INVALID`
+# (`error.reason` `ARGUMENTS_CHANGED`; `FOREIGN` for a cursor an older canon issued: start from the first page). A field path is the record's own key, written as it is.
 canon query --kind trajectory --json --limit 50 --fields at,kind
 canon query --kind trajectory --json --limit 50 --fields at,kind --cursor <nextCursor>
 ```
@@ -122,9 +122,12 @@ file names, tracked in git. `status`, the gate, the guards and `canon query`
 read the ledger only.
 
 ```bash
-canon query --kind evidence --history   # every version, archive included
-canon ledger compact                           # preview; writes nothing
-canon ledger compact --commit --plan-digest "$PLAN_DIGEST"   # pre-0.23 ledger or interrupted move; idempotent; `canon migrate` runs it
+# every version, archive included
+canon query --kind evidence --history
+# preview; writes nothing
+canon ledger compact
+# pre-0.23 ledger or interrupted move; idempotent; `canon migrate` runs it
+canon ledger compact --commit --plan-digest "$PLAN_DIGEST"
 ```
 
 A crash between the write and the move leaves a readable ledger that the next
@@ -287,10 +290,10 @@ skills:
   providers: [claude, codex]   # any of claude, codex, omp, pi; [] for none
 ```
 
-`canon init` writes it: on a terminal it asks, with the harnesses whose
-`.claude`, `.codex`, `.omp` or `.pi` directory exists checked;
-`--providers a,b` (or `none`) answers without asking; with neither it takes
-the detected ones, and with none detected it writes only a commented example
+`canon init` writes it and never asks: `--providers a,b` (or `none`) is the
+answer; without it init takes the harnesses whose
+`.claude`, `.codex`, `.omp` or `.pi` directory exists, and with none detected
+it writes only a commented example
 and installs nothing. `.agents` alone never selects Codex. `canon skills
 install|check|doctor` follow the section; `install` prunes projected files the bundle no longer ships when their bytes match the lock (a modified one stays, reported as `kept:`), `check` exits 1 (`SKILLS_DRIFT`) naming each orphan and `doctor` prints `orphan:` lines; `canon skills install
 --providers=<list>` rewrites it in place. Without the section they use the
@@ -311,17 +314,22 @@ or when the index holds a scenario of a spec root that no `.feature` file
 of it declares any more.
 
 The commands that write records (`canon subject move`, `canon review
-scenario`, `canon evidence add` and `canon artifacts store`) rebuild a stale index on disk first: they
+scenario`, `canon evidence add` and `canon artifacts store`) rebuild a stale index on disk, once nothing
+refuses the call (a refused call writes nothing, whatever the index; until then they read the index as the
+refresh would leave it, in memory): they
 run `canon inventory sync`'s code on the changed files (validation still
-covers the whole root) and print one stderr line:
+covers the whole root) and print one stderr line (in JSON mode the line is a `meta.warnings` entry,
+never a line on stderr):
 
 ```stderr
-canon artifacts store: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
+stderr: canon artifacts store: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
 ```
 
 The commands that only read (`canon gate check`, `canon status`) write
 nothing: they grade a stale index as the refresh would leave it, built in
-memory, and print no refresh line. `canon query --kind scenario` and the
+memory, and print no refresh line. `canon subject show` is the one read
+command that declares the refresh, as a cache effect (its `effectNote`), after the subject is found.
+`canon query --kind scenario` and the
 report panels read the index on disk as it is.
 
 A deleted scenario is not erased: `canon inventory sync` — and a writer's
@@ -332,7 +340,7 @@ a live generation that supersedes the tombstone. A root that fails to
 sync writes no tombstone either.
 
 ```stderr
-canon artifacts store: refreshed the scenario index from 1 scenario(s) no longer in any feature file (cart.pay.01): 1 record(s) written
+stderr: canon artifacts store: refreshed the scenario index from 1 scenario(s) no longer in any feature file (cart.pay.01): 1 record(s) written
 ```
 
 `canon inventory sync` and every refresh hold an OS file lock on
@@ -350,7 +358,7 @@ the `verifying → shipped` guard refuses, and `canon status` lists only
 `canon inventory sync`:
 
 ```stderr
-canon artifacts store: found the scenario index stale for 1 changed feature file(s) (…): 0 record(s) written; NOT refreshed: root `root` (2 format violation(s), 0 sync error(s)) — `canon inventory sync` lists them
+stderr: canon artifacts store: found the scenario index stale for 1 changed feature file(s) (…): 0 record(s) written; NOT refreshed: root `root` (2 format violation(s), 0 sync error(s)) — `canon inventory sync` lists them
 ```
 
 Nothing is written in a directory without `canon.yaml`. `canon inventory
@@ -370,6 +378,26 @@ released when its holder exits, however it exits, so it never goes stale;
 a writer gives up after 30 s with a message naming the file and saying to
 retry (the command exits `2` and writes no record).
 
+## The repository write lock
+
+A committed destructive command (`canon purge`, `canon tier age`, `canon ledger
+compact`, `canon artifacts move`, `canon migrate`) recomputes its plan, checks
+its digest and then makes the effects, and nothing may change the plan in
+between. It holds an OS file lock on `.canon/repo-write.lock` for the whole
+span, from before it recomputes the plan to after its last effect; a preview
+holds nothing. Every other command that writes what a plan reads (ledger
+appends, the artifact store, briefs, specs, hooks, skill files, `canon.yaml`)
+holds the same lock while it writes, so it waits for a commit and a commit
+waits for it; reads, `--dry-run` runs and previews hold nothing. The lock is
+the outermost one: it is taken before the scenario-index lock and the
+artifact-store lock. It is released when its holder exits, however it exits,
+so a killed commit never leaves it held, and the file is removed only by a
+call that made it to take the lock and then ended refused (a refusal leaves
+no file and no `.git/info/exclude` line behind). A
+command that waited 30 s for it starts nothing: it exits `2` with
+`REPO_WRITE_BUSY` (retryable; run it again in a moment). The first
+call that needs the lock makes the file, in any repository.
+
 ## What `canon init` keeps out of git
 
 A fresh `canon init` writes these lines to `.gitignore` (each under a
@@ -384,6 +412,8 @@ comment, only the missing ones):
 - `.canon/scenario-index.lock` — the lock serializing index rebuilds.
 - `.canon/artifact-store.lock` — the lock serializing artifact store
   writes.
+- `.canon/repo-write.lock` — the lock a committed destructive command and
+  every writer of what its plan reads hold.
 - `.canon/dashboard-snapshot/` — the snapshot `canon dashboard`
   regenerates on every run.
 - `.canon/learn/` and `.canon/r2/` — local learn scratch and the local

package/dist/skills/reference/canon-subject.md

@@ -40,7 +40,8 @@ Write (or update) the Subject before touching anything else, so every
 downstream artifact has a `subject_id` to pin to.
 
 ```bash
-canon context --repo .            # record kinds, enum domains, policy requirements
+# record kinds, enum domains, policy requirements
+canon context --repo .
 canon subject new subject-domain-loop \
   --domain dev --title "Subject domain loop" \
   --summary "The durable product unit + its per-domain loop" \
@@ -130,7 +131,8 @@ from anywhere). Any other transition is rejected by failure class, exits
 canon subject move subject-domain-loop --to specced
 canon subject move subject-domain-loop --to building
 canon subject move subject-domain-loop --to verifying
-canon subject move subject-domain-loop --to shipped   # gated — see below
+# gated — see below
+canon subject move subject-domain-loop --to shipped
 ```
 
 On success the status updates in place; `--json` prints the updated
@@ -182,8 +184,8 @@ a policy. The refusal is an `unreviewed-promotion` naming the subject, and
 says what to do:
 
 ```output
-canon subject move: SUBJECT_GATE_VIOLATION — unreviewed-promotion demo-subject — verifying → shipped: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line; a human must answer the brief, and only from that answer the agent will record their words with `canon brief approve c-demo --approver <the human> --note "<their words>"`
-canon subject move: refused — get the human's answer to the brief and record it with `canon brief approve`, or pass --override-reason <text> to move anyway; the waiver is recorded on the subject
+output: canon subject move: SUBJECT_GATE_VIOLATION — unreviewed-promotion demo-subject — verifying → shipped: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line; a human must answer the brief, and only from that answer the agent will record their words with `canon brief approve c-demo --approver <the human> --note "<their words>"`
+output: canon subject move: refused — get the human's answer to the brief and record it with `canon brief approve`, or pass --override-reason <text> to move anyway; the waiver is recorded on the subject
 ```
 
 For an external change with no canon brief yet, the reason reads
@@ -259,7 +261,7 @@ When `.canon/policy.yaml` sets `spec_coverage.require_review` (see
 prints on stderr which it ran or skipped:
 
 ```output
-canon subject move: review guard for building → verifying (spec_coverage.require_review, scope: verifying, shipped)
+output: canon subject move: review guard for building → verifying (spec_coverage.require_review, scope: verifying, shipped)
   ran unreviewed-promotion — every owned scenario needs a review by an actor, and from a session, other than its evidence's
   ran open-blocker — 1 adopted change(s) checked for open blocker findings
 ```
@@ -316,8 +318,8 @@ canon subject move demo-subject --to verifying \
 ```
 
 ```output
-canon subject move: reopened `demo-subject` from shipped, recorded by `impl`: follow-up: the retry path leaks a file handle; keep the follow-up in its approved change `c-demo`, then scenario, evidence and review; shipping again runs every guard
-canon subject move: demo-subject → verifying — written directly; nothing to promote
+output: canon subject move: reopened `demo-subject` from shipped, recorded by `impl`: follow-up: the retry path leaks a file handle; keep the follow-up in its approved change `c-demo`, then scenario, evidence and review; shipping again runs every guard
+output: canon subject move: demo-subject → verifying — written directly; nothing to promote
 ```
 
 - `--reason "<one line>"` is required for `shipped → verifying` (exit 2
@@ -353,9 +355,11 @@ Planning docs written outside canon become change/task records via
 `canon subject adopt` lifts an imported change into a managed Subject:
 
 ```bash
-canon ingest plans --repo .                          # import → change/task rows
+# import → change/task rows
+canon ingest plans --repo .
+# link change → subject
 canon subject adopt subject-domain-loop \
-  --change subject-domain-loop-plan                      # link change → subject
+  --change subject-domain-loop-plan
 ```
 
 A change made with `canon change new` (below) is recorded and adopted
@@ -377,7 +381,7 @@ second subject adds that subject, never re-points the change, and says
 so:
 
 ```output
-canon subject adopt: linked change `refactor-core` to subject `editing` as well; the change now belongs to `perception` and `editing` — written directly; nothing to promote
+output: canon subject adopt: linked change `refactor-core` to subject `editing` as well; the change now belongs to `perception` and `editing` — written directly; nothing to promote
 ```
 
 Every reader joins a subject to its changes from both sides (the
@@ -434,8 +438,8 @@ canon change new add-login --subject auth --title "Add login"
 ```
 
 ```output
-canon change new: wrote .canon/changes/add-login/brief.md
-canon change new: recorded change `add-login` adopted into subject `auth` — written directly; nothing to promote
+output: canon change new: wrote .canon/changes/add-login/brief.md
+output: canon change new: recorded change `add-login` adopted into subject `auth` — written directly; nothing to promote
 ```
 
 - **Writes** canon's own change dir, `.canon/changes/<slug>/`, holding
@@ -493,8 +497,10 @@ brief (`data.next`, `meta.next`).
 ### The brief: `canon brief show`, `canon brief check`, `canon brief approve`
 
 ```text
-canon brief show [<slug>]                       # state and the next one to three steps; never edits
-canon brief check [<slug>] [--json]            # findings; exit 0 clean, 2 blockers, 1 error
+# state and the next one to three steps; never edits
+canon brief show [<slug>]
+# findings; exit 0 clean, 2 blockers, 1 error
+canon brief check [<slug>] [--json]
 canon brief approve <slug> <slug> --approver <the human> --note "<their words>"
 ```
 
@@ -567,8 +573,10 @@ step that writes it.
 ## Where are we: `canon status`
 
 ```bash
-canon status                 # subjects by status, their gaps, next commands
-canon status --json          # the same report, stable shape
+# subjects by status, their gaps, next commands
+canon status
+# the same report, stable shape
+canon status --json
 canon status --repo ../other
 ```
 
@@ -818,7 +826,8 @@ and `canon gate check` exits `0`; read `data.subjects[]` for the counts and
 
 ```bash
 canon query --kind subject --domain dev --status building
-canon report build --repo .  # renders the "Subjects" panel
+# renders the "Subjects" panel
+canon report build --repo .
 ```
 
 - `canon query --kind subject [--domain <d>] [--status <s>]` — the