@journeykit/canon 0.17.0 → 0.21.0

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

@@ -28,7 +28,7 @@ Every violation carries one of these stable, grep-able strings:
 | `malformed-evidence` | A candidate record doesn't parse, is misfiled, or carries an unparseable interim tag. Malformed evidence is no evidence. |
 | `flagged` | The human-only `flagged` overlay is set — never green regardless of passing evidence. |
 | `unevidenced-flip` | `canon gate task <task_id>` was asked to flip a checkbox with no matching, non-`Divergent` evidence record. |
-| `fabricated-evidence` | An evidence note contains a blocklisted marker (`"would pass"`, `"TBD"`, `"n/a"`) or a bare `verified` claim with no attached command result. |
+| `fabricated-evidence` | An evidence note contains a blocklisted marker (`"would pass"`, `"TBD"`, `"n/a"`) standing as a whole word — never inside a path, a file name, a URL or a longer word, so `pack.json/atlas` is not `n/a` — or a bare `verified` claim with no attached command result. `canon evidence add` refuses such a note before writing (`canon evidence add: refused — fabricated-evidence …`, exit 1). |
 | `open-blocker` | With `spec_coverage.require_review` set (and `block_on_findings`, the default), a Finding whose latest version is severity `blocker`, disposition `open`, on a change an in-scope subject adopted. Subject string `<change_id>#<round>.<seq>`. See `canon-review`. |
 | `false-success` | The latest audit record (`canon evidence add --kind audit`) of a scenario says `refuted`: an external evaluator found a counterexample to the claimed success. Always on, regardless of policy or sampling, and takes precedence over any declared faithful verdict; only a newer audit (`confirmed` or `indeterminate`) clears it. The detail names the evaluator, its version, its sha256 and the counterexample paths. |
 
@@ -142,7 +142,7 @@ A present section, even `require_evidence: false` or a malformed one
   case). This is the gap evidence presence cannot see: every scenario
   attested, none of them specifying a refusal. Untagged scenarios satisfy
   no case, so an unclassified corpus is reported, not passed. Works with
-  `require_evidence: false` too. `canon subject status <id> shipped`
+  `require_evidence: false` too. `canon subject status <id> --to shipped`
   applies the same rule to the scenarios the subject owns.
 - **Independent review** (`require_review`) — scenarios whose subject is
   in `require_review.scope` (default `[verifying, shipped]`; `[]` = every
@@ -228,25 +228,38 @@ canon evidence add --kind audit --project-id root --scenario-id cart.add.01 \
 - Audits fold apart: per `(project_id, scenario_id)` there is a latest
   declared record and a latest audit. An audit never becomes the
   scenario's latest declared verdict.
-- `canon subject status <id> shipped` refuses `false-success`, and an
+- `canon subject status <id> --to shipped` refuses `false-success`, and an
   owed sampled audit when `require_audit.scope` covers `shipped`.
 - `canon status` shows an `audits` section (sampled / confirmed / owed /
   refuted) and suggests `canon evidence add --kind audit …` in `next:`.
 
-### Dropping a binding (`--drop-attachment`)
-
-`canon evidence add` for a scenario refuses (exit `2`) when the
-scenario's current latest record of the same fold (declared records, or
-audit records for an audit) — committed ledger plus `_staging` — binds
-files the new record does not. The refusal names the paths and two ways
-out: re-bind them (`--artifact`/`--report`; new bytes at the same path
-are fine), or drop them on purpose with `--drop-attachment <path>`
-(repeatable) and one single-line `--drop-reason <text>`. The drop is
-recorded as `attachment_drop: {paths, reason}`. Refused (`2`): a drop
-without a reason, a reason without a drop, a drop path that is not
-actually dropped, a multi-line reason, or a drop without
-`--scenario-id` (task-only evidence has no drop guard). `canon status`
-lists recorded drops (`dropped bindings (N):`; `drops[]` in `--json`).
+### Carrying and dropping bindings (`--drop-attachment`)
+
+`canon evidence add` for a scenario carries forward what the scenario's
+current latest record of the same fold (declared records, or audit
+records for an audit; committed ledger plus `_staging`) bound: every
+file the new write does not name again is bound into the new record
+unchanged (same path, digest and stored blob), and `--json` lists it as
+`carried: [paths]`. A file named again (`--artifact`/`--report`, new
+bytes at the same path included) replaces its earlier binding. A suite
+batch (`--all-scenarios`) therefore never costs a scenario its
+screenshots. A carried file whose blob the artifact store does not
+hold intact is refused (exit `2`, `EVIDENCE_CARRY_BLOB_MISSING`, nothing
+written): re-bind it, run `canon evidence vault`, or drop it. The audit
+fold (`--kind audit`) does not carry: an audit that leaves out a file
+the latest audit bound is refused (exit `2`) unless it names the file
+again or drops it with `--drop-attachment`, so a counterexample never
+rides along into a confirming audit.
+
+The only way to lose a binding is `--drop-attachment <path>`
+(repeatable) with one single-line `--drop-reason <text>`, recorded as
+`attachment_drop: {paths, reason}`. With `--all-scenarios` the drop
+applies to each scenario that binds the path. Refused (`2`): a drop
+without a reason, a reason without a drop, a drop path that no
+scenario of the write leaves out, a multi-line reason, or a drop
+without `--scenario-id`/`--all-scenarios` (task-only evidence has no
+carry or drop). `canon status` lists recorded drops (`dropped bindings
+(N):`; `drops[]` in `--json`).
 
 ### Nothing is attested before the brief is approved (`--override-reason`)
 
@@ -256,7 +269,8 @@ reports it, and builds nothing for that scope until the human answers.
 refuses (exit `1`, nothing staged or stored) while a subject the record
 attests for has an enforced, unapproved brief: the newest adopted
 change's canon `.canon/changes/<change>/brief.md` has no `Approved:`
-line, or there is no canon `brief.md` yet but the change comes from an
+line, was edited after its approval (`BRIEF_CHANGED_SINCE_APPROVAL`), or
+there is no canon `brief.md` yet but the change comes from an
 external openspec plan with a `proposal.md` under the plan sources (the
 check `canon status` and the ship guard use; see
 `canon-subject`). The subjects are the scenario's `@subject` owner for
@@ -264,8 +278,8 @@ check `canon status` and the ship guard use; see
 `--task`:
 
 ```
-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 as `Approved: <who> <when> — "<their words>"` in .canon/changes/c-demo/brief.md
-canon evidence add: refused — stop, report the brief to the human and wait for their answer: nothing is built or attested for a subject before its brief is approved. Record their words as `Approved: <who> <when> — "<their words>"` in that brief.md only from that answer; to attest anyway, pass --override-reason <text>, which is recorded on the evidence record
+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 --change c-demo --by <the human> --note "<their words>"`
+canon evidence add: refused — stop, report the brief to the human and wait for their answer: nothing is built or attested for a subject before its brief is approved. Record their answer with `canon brief approve --by <the human> --note "<their words>"` only from that answer; 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
@@ -274,8 +288,8 @@ change `c-ext` comes from the external plan
 openspec/changes/c-ext/proposal.md, which canon reads and never edits, so
 its approval lives in that canon file, so the human has not answered it;
 once they do, create .canon/changes/c-ext/brief.md holding a `Source:
-openspec/changes/c-ext/proposal.md` line and record their words there as
-`Approved: <who> <when> — "<their words>"` ``. An `Approved:` line in the
+openspec/changes/c-ext/proposal.md` line, then record their words with
+`canon brief approve --change c-ext --by <the human> --note "<their words>"` ``. An `Approved:` line in the
 external `proposal.md` itself is never read.
 
 A subject with no brief to answer (no adopted change, or a newest change
@@ -305,7 +319,7 @@ brief overrides: 1 evidence record(s) attested before their brief was approved
 
 ### Review-waiver advisories
 
-A subject moved into a review-scoped status with `canon subject status
+A subject moved into a review-scoped status with `canon subject status <id> --to <state>
 --override-reason` (see `canon-subject`) keeps the `unreviewed-promotion`
 and `open-blocker` gaps its waiver recorded visible without failing the
 gate. Only those exact `(class, subject)` pairs are waived; a gap that
@@ -319,15 +333,18 @@ review waivers: 1 advisory(ies) — not failing the gate:
 
 The waiver lasts only until the subject's next status write.
 
-`canon subject status <id> shipped` also refuses where a brief exists and
-has no `Approved:` line (the subject's newest adopted change has a canon
-`brief.md`, or an external `proposal.md` and no canon `brief.md` yet;
+`canon subject status <id> --to shipped` also refuses where a brief exists and
+is not approved (the subject's newest adopted change has a canon
+`brief.md` with no `Approved:` line or one the brief's text no longer
+matches, or an external `proposal.md` and no canon `brief.md` yet;
 see `canon-subject`), as an `unreviewed-promotion` naming
-the subject. With no brief to answer it prints an advisory and does not
-refuse. Like the evidence refusal above, it is a backstop: the stop is at
-the brief. `canon gate check` does not grade briefs, so a waived ship
-brief prints no advisory here; `canon status` keeps showing the brief as
-not approved.
+the subject, and while `canon brief check` has structure blockers or a
+flow step has no scenario or no failure scenario (the coverage rules gate
+shipping, never approval). With no brief to answer it prints an advisory
+and does not refuse. Like the evidence refusal above, it is a backstop:
+the stop is at the brief. `canon gate check` does not grade briefs, so a
+waived ship brief prints no advisory here; `canon status` keeps showing
+the brief as not approved.
 
 ### Reviews that predate pinning (checked against their pin)
 
@@ -391,6 +408,8 @@ canon evidence add --scenario-id cart.add.04 --project-id root \
 # a JUnit XML or Cucumber JSON report: also records the matched case + outcome
 canon evidence add ... --report junit:target/nextest/default/junit.xml
 canon evidence add ... --report cucumber:reports/cucumber.json
+# a Swift Testing event stream (swift test --experimental-event-stream-output <path>)
+canon evidence add ... --report swift-testing:.build/events.jsonl
 ```
 
 A case is bound when the scenario id is its OWN: the first
@@ -408,6 +427,12 @@ verdict when ANY bound case failed or was skipped refuses (exit 1). Files
 must be inside the repository, are recorded by relative path, and are
 stored (see Bound evidence stays provable).
 
+A Swift Testing case is named by its display name (`@Test("cart.add.04
+refuses an out-of-stock item")`), else its function name
+(`cart_add_04_refuses()`). A test with a failing issue failed, a skipped
+test was skipped, a test that started and ended without one passed, and
+a test that started and never ended failed.
+
 Strength, weakest first: `attested` (no attachment) < `artifact` (any
 bound file) < `report` (a parsed report whose case passed). The policy
 decides whether the gate cares:
@@ -431,6 +456,56 @@ violation in every mode. Canon still cannot know whether the bound test
 actually exercises the scenario — binding narrows the trust gap, it does
 not close it.
 
+### One report, many scenarios (0.18)
+
+One test run proves many scenarios. Bind it once:
+
+```bash
+canon evidence add --project-id root --all-scenarios \
+  --report junit:target/nextest/default/junit.xml \
+  --kind test-run --ref "cargo nextest run" --role implementer
+```
+
+Each indexed scenario of `--project-id` that owns a case (the rule above)
+gets its own record, with only its own cases. Its verdict comes from
+them: `faithful` when every case passed, `divergent` when one failed,
+`not-applicable` when one was skipped and none failed. `--verdict <v>`
+claims the same verdict for every record instead. A case whose id is not
+indexed is named and skipped (`skipped <id> — not an indexed scenario`);
+a report no indexed scenario owns is refused (exit 2). The records share
+the stored report and every `--artifact`, and the output lists each
+scenario with its verdict on its own line.
+
+It is all or nothing: a claimed `faithful` verdict over a failed case,
+a fabrication marker in `--summary`, an unapproved brief for any
+scenario's subject, or a carried attachment whose blob is missing from the
+store refuses the whole batch, and nothing is written. Each scenario's
+earlier attachments are carried into its new record (see above), and
+`--drop-attachment` applies per scenario. `--scenario-id`, `--task`,
+`--report-case`, `--kind audit` and the approval flags name one subject
+and are refused with `--all-scenarios`.
+
+A task's evidence with `--report` and no `--scenario-id` binds EVERY case
+in the report, so a `faithful` verdict needs all of them to pass.
+
+### A write that makes a review stale says so (0.18)
+
+When new evidence (one record or a batch) supersedes the evidence a
+current pinned review saw, `canon evidence add` prints one line per
+review it makes stale, with the command that re-pins it:
+
+```
+canon evidence add: review by `reviewer-2` of cart.add.01 is now stale (it pinned the evidence this record supersedes); re-pin it: canon review add --project-id root --scenario-id cart.add.01 --reviewer reviewer-2 --actor-id reviewer-2 --role reviewer --pin <HEAD sha> --original-spec-ref specs/kind=feature/area=cart/add.feature
+```
+
+The decision is the gate's own (the same stale-review rule `canon gate
+check` reports). The command repeats the review's reviewer, actor, role,
+session, provenance ref, runtime labels and artifacts, pinned at `HEAD` (`<sha>`
+when the repository has no commit). A record that is only staged says
+the review "goes stale once this evidence is promoted": promote first,
+then re-pin. The reviewer re-reviews before re-pinning; several
+scenarios re-pin in one `canon review add` (see `canon-review`).
+
 ## Bound evidence stays provable (the artifact store)
 
 `canon evidence add --artifact/--report` copies each bound file into
@@ -468,20 +543,29 @@ have its bindings checked. A superseded record is not checked —
 re-attesting is the fix.
 
 Files bound to a review (`canon review add --artifact`, see
-`canon-review`) are checked the same way for every in-effect review (the
-latest per `(project_id, scenario_id, reviewer)`), with one difference:
-they were stored when the review was written, so only an intact blob is
-clean. A missing or altered blob is `stale-evidence` on the review's
-scenario, and the detail names the review: ``review by `<reviewer>`
-(actor `<id>`, <time>)``. The working-tree file is reported but never
-vouches for it.
+`canon-review`) are checked by the same rule for every CURRENT in-effect
+review: the latest per `(project_id, scenario_id, reviewer)`, less any
+that went stale against its scenario (its spec or evidence pin moved, or
+a review from before pinning is stale at its commit). A stale review is
+superseded — the gate reads the newer review, or reports the missing
+one as `unreviewed-promotion` — so its files are not re-checked, as a
+superseded evidence record's are not. A missing blob whose working-tree
+file still matches is an advisory, listed with the reviewer:
+
+```
+  unstored cart.add.01 reports/cart-badge.png (sha256 9848…, review by `reviewer-2`) is verified against the working tree only
+```
+
+Anything else is `stale-evidence` on the review's scenario, and the
+detail names the review: ``review by `<reviewer>` (actor `<id>`,
+<time>)``.
 
 `canon evidence vault [--max-artifact-mib <N>]` stores the bytes for
-existing records: every attachment whose working-tree file still matches
-its digest is copied in, and everything else is listed as not stored,
-with both digests. It exits `0` whenever it ran (the gate decides whether
-an unstored file matters), `2` when the ledger cannot be read or a write
-fails.
+existing evidence records and current reviews (a superseded review's files are not vaulted): every attachment whose
+working-tree file still matches its digest is copied in, and everything
+else is listed as not stored, with both digests. It exits `0` whenever it
+ran (the gate decides whether an unstored file matters), `2` when the
+ledger cannot be read or a write fails.
 
 ## Effect-aware risk approvals (`risk_tiers`)
 
@@ -514,6 +598,11 @@ empty clean map.
 
 ## `canon gate task <task_id> [--repo <dir>]`
 
+For imported external plans, and for a `tasks.md` that already exists in
+a canon change. `canon change new` writes no `tasks.md` (0.19), and
+nothing gates on one: a canon-owned change is covered by its flow steps'
+scenarios (`canon status`).
+
 The evidence-gated task checkbox flip. Resolves `<task_id>`
 (`<change_id>#<n>`) through `.canon/changes/` (canon's own changes, read
 first whenever the directory exists, with no `plans:` entry) and then
@@ -595,7 +684,7 @@ promote`, so no separate
 staged. A record another run staged is not touched: only `gate promote`
 commits everything staged. It stays safe to run anyway: with nothing
 staged it prints
-`nothing staged` and exits `0`. `divergence stage` stages for `canon
+`nothing staged` and exits `0`. `divergence add` stages for `canon
 divergence promote` and names it, under the same `write:` rule. Every
 other write — `review add`, `divergence
 resolve|defer`, `subject new|adopt|status`, `change new`, `scenario new`, `feature new`,

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

@@ -72,7 +72,7 @@ scenario index                  # refreshed by every reader; `canon inventory sy
         │
         ▼
 canon review add                # attests a review — see canon-inventory downstream / canon-gate
-canon divergence {stage,promote,resolve,defer,status}   # tracks/resolves a divergence
+canon divergence {add,promote,resolve,defer,status}   # tracks/resolves a divergence
 canon gate check [--release]    # trust-ladder / staleness / coverage — see canon-gate
         │
         ▼
@@ -158,7 +158,7 @@ specs:
 
 - **Review** — `canon review add` attests a verdict against a synced
   scenario. (See `canon-inventory` downstream commands and each command's `--help`.)
-- **Divergence** — `canon divergence {stage,promote,resolve,defer,status}`
+- **Divergence** — `canon divergence {add,promote,resolve,defer,status}`
   tracks/resolves divergences against synced scenarios.
 - **Gate** — `canon gate check` enforces trust-ladder / staleness /
   coverage over the corpus (see `canon-gate`).

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

@@ -46,15 +46,13 @@ The production activation path is a signed, paired-evaluation workflow:
    ```bash
    canon learn approve <strategy_id> --evaluation evaluation.json \
      --principal alice --repo .
-   # `request` is an exact alias:
-   canon learn request <strategy_id> --evaluation evaluation.json \
-     --principal alice --repo .
    ```
 
-   The JSON output contains the evaluation digest, RFC3339 `approved_at`,
+   With `--json` the payload is `.data` of the `{ "data", "meta" }` envelope, and
+   `meta.next` names the human signing step. The `data` contains the evaluation digest, RFC3339 `approved_at`,
    subject `strategy:<strategy_id>`, namespace
-   `canon-learning-approval-v1`, and `payload_hex`. `approve`/`request` never
-   read a private key and never set `verified`.
+   `canon-learning-approval-v1`, and `payload_hex`. `approve` never
+   reads a private key and never sets `verified`.
 6. Decode `payload_hex` to the exact canonical JSON bytes. The signed object
    is:
 

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

@@ -10,8 +10,9 @@ one, and neither can `canon gate`.
 ## 1. Canon's own changes and external `plans:` sources
 
 `.canon/changes/` is canon's native plan source (dialect id `canon`):
-one `<slug>/` directory per change holding `brief.md` and `tasks.md`,
-written by `canon change new` (see `canon-subject`). Every plan reader —
+one `<slug>/` directory per change holding `brief.md` (and a `tasks.md`
+only when someone adds one: an optional work note), written by
+`canon change new` (see `canon-subject`). Every plan reader —
 `canon ingest plans`, `canon gate task`, `canon evidence add --task`,
 `canon dispatch --task`, `canon status` and the brief check — reads it
 first whenever the directory exists, with no `plans:` entry. Being first,
@@ -21,7 +22,8 @@ Its records carry the actor `canon-plan-import-canon`; an external
 openspec change's carry `canon-plan-import-openspec`. A `brief.md` with a
 `Source: <path>` line is not a change of its own: it is the canon brief
 of a change imported from an external plan (it points at the external
-document and holds the human's `Approved:` line), so the native reader
+document and holds the human's `Approved:` line, written by
+`canon brief approve`), so the native reader
 skips that directory and the external source keeps the change id.
 
 `plans.sources` lists only EXTERNAL plans — documents you prepare outside
@@ -89,12 +91,13 @@ No dialect/plugin filter exists or is needed — an imported `change`/
 ## The `canon` dialect (`.canon/changes/`)
 
 Uses the `openspec` change-dir grammar below, with three differences:
-the brief is `brief.md` (its `## Why` first paragraph is the summary; a
+the brief is `brief.md` (the first paragraph of its intent section, or of
+`## Why` in a pre-0.19 brief, is the summary; a
 missing one is a `missing-brief-md` malformed dir), the source root is
 always `.canon/changes/` itself (archived changes under
 `.canon/changes/archive/`), and a `brief.md` carrying a `Source:` line is
-skipped (a pointer brief, above). `tasks.md` uses the same checkbox row
-grammar.
+skipped (a pointer brief, above). An existing `tasks.md` uses the same
+checkbox row grammar; a change with none imports with zero tasks.
 
 ## The `openspec` dialect
 
@@ -175,7 +178,7 @@ downstream reader's job.
 ## What this skill does NOT cover
 
 - **Authoring a change** — `canon change new` writes
-  `.canon/changes/<slug>/brief.md` and `tasks.md` and adopts the change
+  `.canon/changes/<slug>/brief.md` (no `tasks.md`) and adopts the change
   into a subject (see `canon-subject`); it never scaffolds an openspec
   change dir. This skill covers IMPORTING plans.
 - **`canon gate check`/`canon gate task`** (the hand-authored one-task-at-

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

@@ -74,8 +74,10 @@ canon policy approve --by <who> [--note <text>] [--repo <dir>]
 
 A human approves the policy after reviewing `.canon/policy.yaml`, in the
 same answer that approves a subject's brief (0.16; see the skill's working
-loop). The human runs this, or the agent runs it right after that answer
-as `canon policy approve --by <the human> --note "<their words>"`. It
+loop). `canon brief approve` records both in one call, so the agent does
+not run this command next to it. Run `canon policy approve` alone for a
+policy-only change, as the human, or as the agent right after that answer
+(`canon policy approve --by <the human> --note "<their words>"`). It
 writes `.canon/policy.approval.json` directly (nothing to promote):
 
 ```json
@@ -227,7 +229,7 @@ read as a big-endian u64, are less than `rate · 2^64` — computed exactly,
 as a comparison against `ceil(rate · 2^64)`, so `rate: 0` samples nothing
 and `rate: 1` samples everything. A sampled in-scope scenario whose
 latest audit is missing or `indeterminate` is `uncovered-cell`; with
-`shipped` in `scope`, `canon subject status <id> shipped` also refuses
+`shipped` in `scope`, `canon subject status <id> --to shipped` also refuses
 it. `canon context` and the `canon status` policy line show
 `require_audit=(rate=… seed=`…` scope=…)`.
 

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

@@ -55,7 +55,7 @@ The order an agent follows to claim a subject done:
    the screenshots or recordings it looked at with `--artifact <path>`
    (below).
 
-4. **Move the subject**: `canon subject status <id> verifying`, later
+4. **Move the subject**: `canon subject status <id> --to verifying`, later
    `shipped`. See `canon-subject`.
 
 ## `canon finding add` / `canon finding close`
@@ -135,7 +135,8 @@ fixed finding reopened with `--disposition open` counts as open again.
 ## `canon review add`
 
 ```bash
-canon review add --project-id <root-id> --scenario-id <id> \
+canon review add --project-id <root-id> --scenario-id <id> [--scenario-id <id>]... \
+  [--scenario-ids-from <file|->] \
   --reviewer <who> --pin <sha-or-ref> --role <role> \
   (--upstream-ref <ref> | --original-spec-ref <ref>) [--actor-id <id>] [--session-id <id>] \
   [--outcome signed|indeterminate|unavailable] \
@@ -143,7 +144,7 @@ canon review add --project-id <root-id> --scenario-id <id> \
   [--artifact <path>]... [--max-artifact-mib <MiB>]
 ```
 
-One attributed Review record for one scenario, joined on
+One attributed Review record per scenario, joined on
 `(project_id, scenario_id)` — both are required because two spec roots
 may carry the same scenario id. Exactly one provenance ref is required.
 `--actor-id` defaults to `canon`; `--session-id` fills `actor.session_id`.
@@ -153,6 +154,18 @@ own. It is written directly to the ledger, with no staging step, and says
 so: `canon review add: wrote <path> (new) — written directly; nothing to
 promote`.
 
+### Several scenarios in one call (0.18)
+
+`--scenario-id` is repeatable, and `--scenario-ids-from <file>` (`-` reads
+stdin) adds one id per line; `#` starts a comment and blank lines are
+skipped. One reviewer, pin, provenance ref and set of artifacts cover
+every review; each review pins its own scenario and evidence, and each
+gets its own `pinned` and `wrote` line. The artifacts are stored once.
+It is all or nothing: a scenario with no record, or a line in the file
+that is not a scenario id, refuses the call (exit 2) and writes no review.
+This is also the batch re-pin after `canon evidence add` reports reviews
+it made stale (see `canon-gate`).
+
 ### What the reviewer looked at (artifacts)
 
 `--artifact <path>` (repeatable) binds a file the reviewer looked at — a
@@ -173,19 +186,25 @@ The field is absent when no `--artifact` is given. `review add` prints
 .canon/artifacts/sha256/ (<k> newly stored) — commit them with the
 ledger`.
 
-`canon gate check` re-hashes the stored blob of every file bound to an
-in-effect review (the latest per `(project_id, scenario_id, reviewer)`).
-A missing or altered blob is `stale-evidence` on the review's scenario,
-naming the review, even when the working-tree file still matches (see
-`canon-gate`, "Bound evidence stays provable"):
+`canon gate check` re-checks every file bound to a current in-effect
+review (the latest per `(project_id, scenario_id, reviewer)`, unless it
+went stale against its scenario) by the evidence rule (see `canon-gate`,
+"Bound evidence stays provable"). A missing blob whose working-tree file
+still matches is an advisory naming `canon evidence vault`, which stores
+it back. A missing blob with a changed or missing working-tree file, or
+an altered blob, is `stale-evidence` on the review's scenario, naming
+the review:
 
 ```
-stale-evidence world.demo.01 — review by `reviewer-2` (actor `reviewer-2`, 2026-10-11T09:00:00Z) bound file `reports/title.png` recorded sha256 <hex>; stored blob .canon/artifacts/sha256/<hex>: missing; working tree: <hex> — the bound bytes are gone, look again and re-record the review with `canon review add --artifact <path>`
+stale-evidence world.demo.01 — review by `reviewer-2` (actor `reviewer-2`, 2026-10-11T09:00:00Z) bound file `reports/title.png` recorded sha256 <hex>; stored blob .canon/artifacts/sha256/<hex>: missing; working tree: <other hex> — the bound bytes are gone, look again and re-record the review with `canon review add --artifact <path>`
 ```
 
 The reviewer's later review replaces the earlier one, so its files are
-the ones checked. Canon binds and re-checks bytes only; it never compares
-images or judges what a screenshot shows.
+the ones checked. A review that went stale (its scenario's spec or
+evidence moved since) is not checked either: it no longer counts, and the
+scenario's newer review is the one whose files are checked. Canon binds
+and re-checks bytes only; it never compares images or judges what a
+screenshot shows.
 
 ### What the review saw (pins)
 
@@ -394,7 +413,7 @@ review waivers: 1 advisory(ies) — not failing the gate:
 
 ## The status guard
 
-With `require_review` present, `canon subject status <id> <state>`
+With `require_review` present, `canon subject status <id> --to <state>`
 prints on stderr which review checks it ran or skipped:
 
 ```

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

@@ -98,17 +98,23 @@ canon query --kind handoff --since 2026-06-01T00:00:00Z
 
 # Machine-readable output instead of the human table.
 canon query --kind trajectory --json
+
+# Page a long result and keep only the fields you need; `meta` carries
+# returned, total, hasMore and nextCursor (`--all` returns everything).
+canon query --kind trajectory --json --limit 50 --fields at,kind
+canon query --kind trajectory --json --limit 50 --cursor <nextCursor>
 ```
 
 ## What `canon report` does and doesn't read
 
 canon exposes layered `stg_`/`int_`/`mart_` query views; `canon report`
 builds its numbers from the `mart_` views. Those read ONLY local roots
-— the git ledger and a LOCAL `.canon/r2` parquet mirror. `canon report`
+— the git ledger, the sqlite `hot` db file (local, no credential; read
+since 0.18) and a LOCAL `.canon/r2` parquet mirror. `canon report`
 never opens a live DB connection or the live bucket, so:
 
-- Kinds routed to `hot` (sqlite/postgres) do NOT appear in `canon
-  report`.
+- Kinds routed to a postgres `hot` rung do NOT appear in `canon
+  report`; kinds routed to `canon init`'s default sqlite `hot` rung do.
 - Kinds routed to `cold` (s3) appear only if a local `.canon/r2` mirror
   has been separately materialized — there is no automatic sync.
 
@@ -119,8 +125,11 @@ section listing them and emits a matching stderr `WARN`.
 
 ## Retention, export, and access audit
 
-`canon purge --kind <kind> --before <RFC3339> [--repo <dir>] [--dry-run] [--json]`
-is the canonical data-lifecycle boundary. The only purgeable kinds are
+`canon purge --kind <kind> --before <RFC3339> (--plan | --confirm <planDigest>) [--repo <dir>] [--json]`
+is the canonical data-lifecycle boundary: `--plan` prints the removal set and
+its `planDigest` and deletes nothing; `--confirm <planDigest>` deletes only if
+the plan recomputed now has the same digest (`PLAN_CHANGED`, exit 2, when the
+data moved), and a bare `purge` is refused (`PURGE_PLAN_REQUIRED`). The only purgeable kinds are
 `session`, `run`, `event`, and `trajectory`; the cutoff applies to every
 routed rung and every configured aging destination, including retained
 historical versions. For `trajectory`, the command also purges the
@@ -133,8 +142,14 @@ an explicit `partial` result with matched/deleted counts and a nonzero
 status. Purge never rewrites Git history or deletes source transcript
 files.
 
+With `--json`, `purge` and `export` answer `{ "data", "meta" }` like every other
+command: `data` is the plan or manifest, `meta.next` the step after (a plan's is the
+human's review and `--confirm`), and an export's page state (`total`, `returned`,
+`nextCursor`) sits in `meta`. `export --json --out <file>` writes the manifest to the
+file and answers with `data: { out, kind, recordCount }`.
+
 `canon export --kind <kind> [--before <RFC3339>] [--after <RFC3339>]
-[--out <file>] [--json]` emits a versioned manifest containing source scope,
+[--out <file>] [--json] [--limit <n> | --all] [--cursor <c>]` emits a versioned manifest containing source scope,
 counts, digests, and redacted metadata. It does not authorize backend access;
 credentials remain an operator prerequisite. New output files are mode
 `0600`. Raw event detail text is excluded unless `--include-sensitive` is
@@ -160,7 +175,7 @@ record bodies.
 Four writes stage their record instead of committing it: `canon evidence
 add`, `canon finding add` and `canon finding close` (under
 `.canon/ledger/_staging/`, committed by `canon gate promote`) and `canon
-divergence stage` (committed by `canon divergence promote`). `canon.yaml`'s
+divergence add` (committed by `canon divergence promote`). `canon.yaml`'s
 `write:` section decides whether they promote in the same run:
 
 ```yaml