@journeykit/canon 0.22.0 → 0.24.0

package/dist/skills/SKILL.src.md

@@ -24,7 +24,7 @@ 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. Record it only from the human's answer:
-  `canon brief approve --change <slug> --by <the human> --note "<their words>"`.
+  `canon brief approve --change-id <slug> --by <the human> --note "<their words>"`.
   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
@@ -39,7 +39,9 @@ a feature, a one-line request included. A human is needed once per scope:
   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`) and re-reviewed before it ships.
+  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>`).
 - 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
@@ -58,6 +60,24 @@ 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.
 
+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
+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.
+
+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.
+
 ## Know your role
 
 canon cannot detect a role; you declare it. Pass `--as <role>` or set
@@ -93,6 +113,10 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
   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.
+- 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`).
 - `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.

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

@@ -84,7 +84,7 @@ enum, like `lane`.
 ## Subject pinning
 
 Every scenario belongs to a Subject (the durable product unit, see
-`canon-subject`). Write the Subject first, then pin with `--subject`;
+`canon-subject`). Write the Subject first, then pin with `--subject-id`;
 the scenario index carries the tag onto the index record and
 `spec_coverage.scope` filters on it. An unpinned scenario is invisible to
 a scoped gate.
@@ -94,9 +94,9 @@ a scoped gate.
 ```bash
 canon feature new checkout.cart --title "Cart"                       # once per surface
 canon scenario new checkout.cart.01 --title "Adding an item raises the count" \
-  --subject checkout-core --lane behavior --case happy               # once per behavior
+  --subject-id checkout-core --lane behavior --case happy               # once per behavior
 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-id checkout-core --lane behavior --case failure             # and its failure path
 ```
 
 There is no format or sync step after these: the scaffold writes a
@@ -108,7 +108,7 @@ one of them prints `NOT refreshed`, the corpus has a format violation
 duplicate id; `canon inventory sync` (or `canon format <root>`) names it.
 Fix it and the next command indexes the files (see `canon-inventory`).
 
-- `--actor <id>` (or `CANON_ACTOR` in the environment) puts YOUR id on the
+- `--actor-id <id>` (or `CANON_ACTOR` in the environment) puts YOUR id on the
   provenance line. Default is `canon-scaffold`.
 - **Keep the `# canon:` lines when you fill in the scenario.** Dropping one
   makes `canon inventory sync` abort on `missing-provenance`; restore it
@@ -146,7 +146,7 @@ Fix it and the next command indexes the files (see `canon-inventory`).
 - **A Feature title that is a theme.** "Fidelity of the original
   experience" names no surface. Name the screen.
 - **Hand-stamped provenance.** Eighty lines with one timestamp and the
-  same `agent_id`. Use `canon scenario new --actor`.
+  same `agent_id`. Use `canon scenario new --actor-id`.
 - **Coverage by splitting.** One behavior as two scenarios so two rows go
   green. One behavior, one id.
 - **Runner tags as classification.** `@design`, `@p2`, `@wip` are

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

@@ -226,9 +226,13 @@ from shipping until every one of its evidenced scenarios has evidence
 recorded after the close or the approval. The refusal names the scenarios
 and the batch command: `canon evidence add --project-id <root-id>
 --all-scenarios --report <format>:<path> --kind test-run --role
-implementer --ref "<test command>" …`. That evidence stales the pinned
-reviews, so a re-review follows (and a new `divergence accept`, where the
-gap remains).
+implementer --ref "<test command>" …`. Reviews pin what the evidence says
+(its verdict and the identity of its checks), not which record it is, so
+recording the suite again with the same verdicts from the same cases leaves
+every scenario review current. A chore instead needs one change-level
+review of the chore itself (`canon review add --change-id <slug> …`) before
+`--to shipped`; a changed verdict or case set stales that scenario's
+review as before (and a new `divergence accept`, where the gap remains).
 
 ### Audit records (`--kind audit`)
 
@@ -263,33 +267,16 @@ canon evidence add --kind audit --project-id root --scenario-id cart.add.01 \
 - `canon status` shows an `audits` section (sampled / confirmed / owed /
   refuted) and suggests `canon evidence add --kind audit …` in `next:`.
 
-### 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`).
+### A record binds what its own write names
+
+`canon evidence add` binds exactly the files the write names
+(`--artifact`, `--report`, `--report-case`). Nothing is carried forward
+from an earlier record, in a single add or in a suite batch
+(`--all-scenarios`), and no drop is recorded: history keeps the earlier
+records, and a new record is reviewed on its own files. An audit
+(`--kind audit`) replaces a refutation the same way, so a counterexample
+never rides along into a confirming audit. `--drop-attachment` and
+`--drop-reason` no longer exist.
 
 ### Nothing is attested before the brief is approved (`--override-reason`)
 
@@ -308,7 +295,7 @@ 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 with `canon brief approve --change c-demo --by <the human> --note "<their words>"`
+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-id 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
 ```
 
@@ -319,7 +306,7 @@ 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, then record their words with
-`canon brief approve --change c-ext --by <the human> --note "<their words>"` ``. An `Approved:` line in the
+`canon brief approve --change-id 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
@@ -376,51 +363,43 @@ 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)
-
-With `require_review` on, the reviews in effect (latest per reviewer and
-scenario) that carry no pins were written before 0.15. Each still names
-`pin`, the commit it reviewed, and the gate checks it there (0.16):
-
-- **current** — the scenario's digest at that commit (read with `git`,
-  normalized exactly as `canon inventory sync` computes
-  `scenario_digest`) equals its current digest, and no declared evidence
-  record of the scenario is newer than the review. It counts. When the
-  scenario lived in another `.feature` file at that commit, the spec
-  root's files at that commit are searched for its id, then the files
-  under each of the root's `former_roots` (where `canon migrate` moved
-  it from, e.g. `specs` for a root now at `.canon/specs`). Only the
-  root's own directories are searched, never another root's.
-- **stale** — the scenario changed since the commit, or it has newer
-  evidence. It no longer counts, and an in-scope scenario left with no
-  other qualifying review is `unreviewed-promotion`:
-
-  ```
-  unreviewed-promotion gate.check.15 — stale review by `canon-reviewer-g1` (written before review pinning; checked against commit b556ab7529a332aa0b28d0a0f98bdd62fcbb9a63): it has declared evidence newer than the review; a review counts only while what it saw is current — review it again (`canon review add`)
-  ```
-
-  A spec change reads `its spec changed since <pin> (the scenario's
-  digest at that commit is not its current one)`.
-- **undecidable** — the pin is not a commit in this clone (a shallow
-  clone, rewritten history), or no feature file of the scenario's root
-  holds its id at that commit. It keeps counting, as in 0.15: a missing
-  commit never becomes a violation.
+### Reviews that predate 0.23 pinning (`canon migrate`)
 
-One advisory line after the violations counts the three. A stale one
-whose scenario already has another qualifying review (current, signed,
-distinct) is counted as superseded, since nothing is owed for it; only
-the scenarios a stale one leaves without a qualifying review are named
-for re-review. The exit code is unchanged by the line itself:
+A review pins what its scenario's evidence says: the scenario's spec
+digest and, per role, the verdict and the identity of the checks the latest
+evidence bound (`ReviewPins.checks`). Reviews written before 0.23 pin
+something the gate no longer compares: 0.15–0.22 reviews pin evidence
+record files, and reviews written before 0.15 pin only `pin`, the commit
+they reviewed. Such a review does not count until `canon migrate` rewrites
+it; the gate says so:
 
 ```
-advisory: 338 review(s) predate review pinning (0.15) and were checked against the commit each one pinned: 318 current, 12 stale, 8 undecidable; 7 stale one(s) superseded by a current review of the same scenario, so nothing is owed for them; a stale one with no current review in its place no longer counts — review its scenario again (`canon review add`): platformer.movement.01, platformer.movement.02, …; an undecidable one still counts unchecked, because its pinned commit or the scenario at it is not in this clone — check out full history (`fetch-depth: 0` in CI) to check it
+unreviewed-promotion gate.check.15 — review by `canon-reviewer-g1` predates 0.23 review pinning (it pins evidence records, or nothing): `canon migrate` rewrites it to what the evidence says, and a review that is not migrated does not count
 ```
 
-A review of a scenario no feature file declares any more is not counted.
-In CI, check out full history (`actions/checkout` with `fetch-depth: 0`)
-for the job that runs `canon gate check`, or every legacy review is
-undecidable. Each pinned commit is read once per run through one `git
-cat-file --batch` process, and never fetched over the network.
+One advisory line counts the scenarios whose review is not migrated.
+`canon migrate` converts each review (and accepted divergence) that was
+current under the rule it was written under, in place, keeping its
+reviewer, actor, session and artifacts; one that was already stale stays
+stale and its scenario needs a new review.
+
+- **0.15–0.22 reviews** are current when the spec pin matches and the
+  latest evidence record per role is the one the review pinned.
+- **pre-0.15 reviews** are current when the scenario's digest at the pinned
+  commit (read with `git`, normalized as `canon inventory sync` computes
+  `scenario_digest`) equals its current digest and no declared evidence is
+  newer than the review. When the scenario lived in another `.feature`
+  file at that commit, the spec root's files at that commit are searched
+  for its id, then the files under each of the root's `former_roots`
+  (where `canon migrate` moved it from). Only the root's own directories
+  are searched, never another root's. A pin that is not a commit in this
+  clone, or a scenario no file holds at that commit, is undecidable: the
+  review is pinned as the scenario stands (it counted unchecked before
+  0.23), and the migration says how many. In CI, check out full history
+  (`actions/checkout` with `fetch-depth: 0`) for the job that runs
+  `canon migrate` to check them.
+
+A review of a scenario no feature file declares any more is left alone.
 
 ## Experimental: evidence binding (`experimental.evidence_binding`, off by default)
 
@@ -503,15 +482,20 @@ them: `faithful` when every case passed, `divergent` when one failed,
 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.
+the stored report, and the output lists each scenario with its verdict on
+its own line. Each record binds the attachments its own cases name in the
+report (a JUnit test case's `[[ATTACHMENT|path]]` lines, which Playwright's
+JUnit reporter writes; a Cucumber JSON embedding), so a test's screenshot
+stays with its scenario. A file the report does not name goes with
+`--artifact <scenario-id>=<path>`; a bare `--artifact <path>` in a batch is
+refused (`EVIDENCE_INVALID_ARGUMENT`). A report attachment that is missing,
+outside the repo or oversized is refused.
 
 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`,
+scenario's subject refuses the whole batch, and nothing is written. Each
+record binds only what the batch names (nothing is carried forward).
+`--scenario-id`, `--task`,
 `--report-case`, `--kind audit` and the approval flags name one subject
 and are refused with `--all-scenarios`.
 
@@ -522,10 +506,10 @@ in the report, so a `faithful` verdict needs all of them to pass.
 
 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:
+review it makes stale (its verdict or checks differ from what the review saw), 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
+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 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
@@ -545,6 +529,16 @@ again. The directory is tracked in git (`canon init` never ignores it):
 commit it with the ledger. A file larger than 25 MiB is refused (exit 2);
 raise the limit with `--max-artifact-mib <N>`.
 
+Where those bytes live is `canon.yaml`'s `artifact_store: { backend: local |
+<s3 tier>, prefix: artifacts/ }` (default `local`: the directory above,
+git-tracked, no credentials). With an object-store tier, `evidence add`,
+`review add` and `evidence vault` upload each blob under
+`<prefix>sha256/<digest>` and keep nothing locally. `canon gate check` and
+`canon artifacts verify [--full]` ask the store (a HEAD per digest; `--full`
+downloads and re-hashes) and refuse, never pass, when it cannot be reached.
+`canon artifacts migrate --to <tier> [--dry-run]` moves an existing local
+store; it is the repo owner's decision. See `canon-storage`.
+
 `canon gate check` re-checks every file bound to a LATEST evidence record
 (the latest per task and per `(project_id, scenario_id)`):
 
@@ -575,8 +569,7 @@ re-attesting is the fix.
 Files bound to a review (`canon review add --artifact`, see
 `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
+that went stale against its scenario (its spec or evidence pin moved). 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
@@ -715,13 +708,12 @@ 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 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`,
+gate promote` and names it, under the same `write:` rule. Every
+other write — `review add`, `subject new|adopt|status`, `change new`, `scenario new`, `feature new`,
 `gate task` (it edits the plan document and re-ingests it)
 — is final when it returns, and its success line ends `— written
 directly; nothing to promote`. Full promote-on-write contract:
-`canon-storage` (Staged writes and promotion).
+`canon-storage` (Staged writes and promotion). `divergence resolve|defer|accept` stage and promote their own record in the same run and end `— staged and promoted in this run; nothing to promote`.
 
 ## `canon gate install-hooks [--repo] [--event] [--matcher] [--command] [--timeout]`
 

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

@@ -179,7 +179,7 @@ record.
 An operator-requested rollback is a distinct authenticated action:
 
 ```bash
-canon learn rollback <strategy_id> --reason "<reason>" --actor alice \
+canon learn rollback <strategy_id> --reason "<reason>" --actor-id alice \
   --signature-file rollback.sig --approved-at 2026-10-02T12:00:00Z \
   [--contradicting-trajectory-id <trajectory_id>] --repo .
 ```

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

@@ -142,6 +142,8 @@ canon review add --project-id <root-id> --scenario-id <id> [--scenario-id <id>].
   [--outcome signed|indeterminate|unavailable] \
   [--reviewer-provider <p>] [--reviewer-model <m>] [--reviewer-harness <h>] \
   [--artifact <path>]... [--max-artifact-mib <MiB>]
+canon review add --project-id <root> --change-id <slug> --reviewer <who> --pin <sha-or-ref> \
+  --role reviewer (--upstream-ref <ref> | --original-spec-ref <ref>) …   # a chore, below
 ```
 
 One attributed Review record per scenario, joined on
@@ -167,14 +169,30 @@ 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`).
 
+### A chore is reviewed as a change (`--change-id`, 0.23)
+
+A chore adds no scenarios, and recording the suite again after it leaves
+every scenario review current (a review pins the evidence's verdict and
+checks, so the same verdicts from the same cases change nothing). What the
+chore needs instead is one change-level review: the reviewer signs its
+invariants and checks against the diff with `canon review add --change-id
+<slug> …`, in place of `--scenario-id`. The review pins the chore's brief
+(its digest, less the `Approved:` line), so an edit to the brief stales it,
+and `--to shipped` refuses a chore with no signed, current change-level
+review (`spec_coverage.require_review.distinct_actor` asks it of a reviewer
+and session that did not attest the subject's evidence). `--change-id` takes a
+chore's slug and refuses a feature change.
+
 ### What the reviewer looked at (artifacts)
 
 `--artifact <path>` (repeatable) binds a file the reviewer looked at — a
 screenshot, a recording, a trace — exactly as `canon evidence add
 --artifact` binds one: the path must resolve to a file inside the
 repository, a file over 25 MiB is refused unless `--max-artifact-mib <N>`
-raises the limit, and the bytes are copied into
-`.canon/artifacts/sha256/<hex>` (commit it with the ledger) before the
+raises the limit, and the bytes are stored by digest (in
+`.canon/artifacts/sha256/<hex>` unless `canon.yaml`'s `artifact_store:` names an
+object store, where they are uploaded and nothing is kept locally; commit
+the local store with the ledger) before the
 review is written. Any refusal exits 2 and writes and stores nothing. The
 review records each distinct file once, in the order given:
 
@@ -225,12 +243,16 @@ reviewer never types them:
   `scenario_digest`; then the review pins its `source_digest` (the
   sha256 of the whole `.feature` file) and records
   `scenario_digest_scope: file`;
-- `evidence` — the scenario's latest evidence record per role, each as
-  `{key, digest}`: the ledger file `kind=evidence_record/<key>__<digest>.json`.
-  A scenario with no evidence yet is pinned with an empty list.
-
-It prints `canon review add: pinned <id> at scenario digest <12 hex> and
-<n> latest evidence record(s); …` (`at source digest` for a file pin). A
+- `checks` — the scenario's latest evidence per role, each as `{role,
+  verdict, checks}`: its verdict and the identity of what it checked (the
+  report format and the matched case names, as `junit:<case>`, or the
+  artifact digests). It names no evidence record, so recording the same
+  verdict from the same checks again leaves the review current. A scenario
+  with no evidence yet is pinned with an empty list.
+
+It prints `canon review add: pinned <id> at scenario digest <12 hex> and the
+verdict and checks of its <n> role(s) of evidence; …` (`at source digest` for
+a file pin). A
 scenario with no record (never synced) is refused with exit 2 and nothing
 is written: there is nothing to pin.
 
@@ -308,44 +330,25 @@ The scenario is reviewed when at least one of those latest reviews:
 
 1. is `signed`;
 2. still matches its pins — the scenario record's current
-   `source_digest`, and its current latest evidence record per role —
-   when it has pins; or, written before 0.15 without pins, still
-   describes its scenario at the commit it pinned (below);
+   `scenario_digest` (or `source_digest` for a file pin), and the verdict and
+   checks of its latest evidence per role — when it has pins; reviews
+   written before 0.23 count only after `canon migrate` (below);
 3. passes `distinct_actor`, when that is on.
 
-### Reviews written before pinning
-
-A review written before 0.15 has no pins, only `pin`: the commit it
-reviewed. The gate reads the scenario's `.feature` file at that commit
-(`git`, with the same per-scenario normalization `canon inventory sync`
-uses for `scenario_digest`; if the scenario was in another file then, the
-spec root's files at that commit are searched for its id) and decides:
-
-- **current** when that digest equals the scenario's current one and no
-  declared evidence record of the scenario is newer than the review: it
-  counts under rules 1 and 3;
-- **stale** when the scenario changed since the commit (`its spec changed
-  since <pin>`) or has evidence newer than the review (`it has declared
-  evidence newer than the review`): it no longer counts, exactly like a
-  stale pinned review;
-- **undecidable** when the pin is not a commit in this clone (shallow
-  clone, rewritten history) or the scenario id is absent at it: it keeps
-  counting, as in 0.15. A missing commit never becomes a violation.
-
-`canon gate check` prints one advisory line with the split (exit code
-unchanged by the line itself). A stale one whose scenario already has
-another qualifying review is counted as superseded and not named:
-
-```
-advisory: 338 review(s) predate review pinning (0.15) and were checked against the commit each one pinned: 318 current, 12 stale, 8 undecidable; 7 stale one(s) superseded by a current review of the same scenario, so nothing is owed for them; a stale one with no current review in its place no longer counts — review its scenario again (`canon review add`): platformer.movement.01, platformer.movement.02, …; an undecidable one still counts unchecked, because its pinned commit or the scenario at it is not in this clone — check out full history (`fetch-depth: 0` in CI) to check it
-```
-
-`canon status` prints the same line as a warning, and `canon subject
-status` prints it on stderr for the subject's own scenarios; all three
-make the same decision. Re-review exactly the scenarios the line names:
-the new review pins what it saw and replaces the reviewer's legacy one.
-In CI, check out full history (`fetch-depth: 0`) for the job that runs
-the gate, or every legacy review is undecidable.
+### Reviews written before 0.23 pinning
+
+A review written before 0.23 pins something the gate no longer compares: a
+0.15–0.22 review pins evidence record files, and a review written before
+0.15 has no pins, only `pin`, the commit it reviewed. Such a review does not
+count until `canon migrate` rewrites it to what the evidence says (see
+`canon-gate`). A review that was current under the rule it was written under
+becomes a current review; one that was stale stays stale, and its scenario
+needs a new `canon review add`, which pins what it saw and replaces the
+reviewer's earlier one. The gate, `canon status` and `canon subject status`
+print one advisory naming how many scenarios are waiting for `canon
+migrate`. In CI, check out full history (`fetch-depth: 0`) for the job that
+runs `canon migrate`, or a pre-0.15 review whose commit is missing is pinned
+as the scenario stands instead of being checked.
 
 ### `unreviewed-promotion`
 

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

@@ -105,6 +105,43 @@ canon query --kind trajectory --json --limit 50 --fields at,kind
 canon query --kind trajectory --json --limit 50 --cursor <nextCursor>
 ```
 
+## The ledger is latest-only; the archive holds history
+
+The `local` rung's directory (`.canon/ledger`) holds the current record of
+each key. Appending a newer version (evidence for a scenario and role, a
+closed finding, a rewritten scenario, a subject's next status) moves the
+versions it supersedes to `.canon/archive`: same `kind=<kind>/…` layout and
+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 --dry-run                 # report; writes nothing
+canon ledger compact                           # pre-0.23 ledger or interrupted move; idempotent; `canon migrate` runs it
+```
+
+A crash between the write and the move leaves a readable ledger that the next
+append or `canon ledger compact` finishes. The archive is local, not routed
+through `tiers:`; a `tiers.local.root` whose directory is not named `ledger`
+has no archive and keeps every version.
+
+## Where artifact bytes live (`artifact_store:`)
+
+```yaml
+artifact_store: { backend: local }                  # default
+# artifact_store: { backend: cold, prefix: artifacts/ }   # an `s3` tier of `tiers:`
+```
+
+`local` is `.canon/artifacts/sha256/`, git-tracked and credential-free. An
+object-store tier gets `evidence add`, `review add` and `evidence vault`
+uploads under `<prefix>sha256/<digest>` and keeps nothing locally. The gate
+and `canon artifacts verify [--full]` ask the store and refuse, never pass,
+when it cannot be reached. `canon artifacts migrate --to <tier> [--dry-run]`
+uploads, reads back and verifies every local blob, then writes the
+`artifact_store:` block, removes the local copies and ignores
+`.canon/artifacts/`; commit the removals, `.gitignore` and `canon.yaml`. It is
+resumable and a second run finds nothing to do.
+
 ## What `canon report` does and doesn't read
 
 canon exposes layered `stg_`/`int_`/`mart_` query views; `canon report`
@@ -173,9 +210,11 @@ record bodies.
 ## Staged writes and promotion
 
 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 add` (committed by `canon divergence promote`). `canon.yaml`'s
+add`, `canon finding add`, `canon finding close` and `canon divergence add`
+(under `.canon/ledger/_staging/`, one staging shape for every kind,
+committed by `canon gate promote`; `canon divergence promote` commits only
+the staged divergences). `canon divergence resolve|defer|accept` stage and
+promote their own record in the same run. `canon.yaml`'s
 `write:` section decides whether they promote in the same run:
 
 ```yaml
@@ -184,9 +223,8 @@ write:
 ```
 
 - `auto` — the command stages, then promotes that one record through the
-  same validation and assignment `canon gate promote` (or `canon
-  divergence promote`) applies. Records other runs staged stay staged;
-  only `canon gate promote` / `canon divergence promote` commit
+  same validation and assignment `canon gate promote` applies. Records
+  other runs staged stay staged; only `canon gate promote` commits
   everything staged. The one success line names the committed record
   (`wrote kind=…/….json`; promotion renames it, so the staged file is not
   named) and ends `— staged and promoted in this run; nothing to

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

@@ -69,12 +69,12 @@ canon subject new subject-domain-loop \
 ### 2. Retrieve subject-scoped strategy memory BEFORE working
 
 ```bash
-canon retrieve --role dev --domain dev --subject subject-domain-loop --k 5
+canon retrieve --role dev --domain dev --subject-id subject-domain-loop --k 5
 ```
 
-- `--regime <key>` XOR the derived pair `--domain <d> [--subject <id>]`:
+- `--regime <key>` XOR the derived pair `--domain <d> [--subject-id <id>]`:
   give the full regime key directly, OR let retrieval derive it. Never both.
-- With `--domain`/`--subject`, retrieval tries `<domain>-<subject_id>`
+- With `--domain`/`--subject-id`, retrieval tries `<domain>-<subject_id>`
   first, then `<domain>` — a subject's own lessons win, falling back to
   the domain's shared memory when the subject is new.
 - Fail-soft: an empty/missing store degrades to an empty guidance list,
@@ -82,7 +82,7 @@ canon retrieve --role dev --domain dev --subject subject-domain-loop --k 5
 
 ### 3. Work → pin every artifact to `subject_id`
 
-- **Scenarios**: `canon scenario new <tag> --subject <subject-id>` emits
+- **Scenarios**: `canon scenario new <tag> --subject-id <subject-id>` emits
   the `@subject:<subject-id>` tag; the scenario index maps the tag onto
   the scenario's `subject_id` the next time a command reads it (no sync
   step; see `canon-inventory`). A malformed/absent tag leaves it unset
@@ -172,7 +172,7 @@ a policy. The refusal is an `unreviewed-promotion` naming the subject, and
 says what to do:
 
 ```
-canon subject status: 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 --change c-demo --by <the human> --note "<their words>"`
+canon subject status: 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 --change-id c-demo --by <the human> --note "<their words>"`
 canon subject status: 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
 ```
 
@@ -181,7 +181,7 @@ For an external change with no canon brief yet, the reason reads
 the external plan <proposal>, which canon reads and never edits, so its
 approval lives in that canon file`` and the agent will ``create
 .canon/changes/<c>/brief.md holding a `Source: <proposal>` line, then
-record their words with `canon brief approve --change <c> --by <the human> --note "<their words>"` ``.
+record their words with `canon brief approve --change-id <c> --by <the human> --note "<their words>"` ``.
 
 Never record the approval without the human's answer. When there is no brief to
 answer (no adopted change, or a newest change with neither a canon
@@ -306,7 +306,7 @@ Planning docs written outside canon become change/task records via
 ```bash
 canon ingest plans --repo .                          # import → change/task rows
 canon subject adopt subject-domain-loop-plan \
-  --subject subject-domain-loop                        # link change → subject
+  --subject-id subject-domain-loop                        # link change → subject
 ```
 
 A change made with `canon change new` (below) is recorded and adopted
@@ -343,7 +343,7 @@ The two records cannot be written atomically, so the subject is written
 first: a half-done adoption still has that change's open blockers
 counted. If the change write then fails, `adopt` exits `2`, names the
 subject that now lists the change, and prints `canon subject adopt
-<change_id> --subject <id>` to complete it.
+<change_id> --subject-id <id>` to complete it.
 
 ### Starting a new change: `canon change new`
 
@@ -351,7 +351,7 @@ For a change that does not exist yet, one command writes it and records
 it adopted:
 
 ```bash
-canon change new add-login --subject auth --title "Add login"
+canon change new add-login --subject-id auth --title "Add login"
 ```
 
 ```
@@ -387,7 +387,7 @@ canon change new: recorded change `add-login` adopted into subject `auth` — wr
   cannot be written atomically. If the change record fails after the
   subject record was written, the command exits `2`, keeps the change
   dir and that one subject record, and prints the repair, `canon ingest
-  plans && canon subject adopt <slug> --subject <id>`, which completes
+  plans && canon subject adopt <slug> --subject-id <id>`, which completes
   the link and is safe to rerun.
 - **Refuses** with exit `2`, writing nothing, when the subject does not
   exist, or when the slug already has a `.canon/changes/<slug>` dir
@@ -411,12 +411,12 @@ it, so the external source keeps the change, its summary and its tasks.
 ### The brief: `canon brief`, `canon brief check`, `canon brief approve`
 
 ```bash
-canon brief [--change <slug>]                 # state and the next one to three steps; never edits
-canon brief check [--change <slug>] [--json]  # findings; exit 0 clean, 2 blockers, 1 error
-canon brief approve --change <slug> --by <the human> --note "<their words>"
+canon brief [--change-id <slug>]                 # state and the next one to three steps; never edits
+canon brief check [--change-id <slug>] [--json]  # findings; exit 0 clean, 2 blockers, 1 error
+canon brief approve --change-id <slug> --by <the human> --note "<their words>"
 ```
 
-Without `--change`, the repo's only live change is read. The brief is the
+Without `--change-id`, the repo's only live change is read. The brief is the
 PRD `canon change new` writes; sections are found by their
 `<!-- canon:section <key> role=… -->` marker, never by heading text. A
 brief without markers (written before 0.19) checks as `brief.legacy`, an
@@ -453,9 +453,10 @@ built or kept, never what it does. Its brief is intent, category,
 invariants, checks, out of scope; it adds no scenarios, and its evidence
 is the subject's suite run again at the chore commit with
 `canon evidence add --all-scenarios --report <kind>:<path> …`. That
-supersedes the old evidence, which makes the pinned reviews stale, so an
-independent re-review follows. Work that changes behavior is a feature
-change, never a chore.
+supersedes the old evidence; the pinned reviews stay current while the
+verdicts and checks are the same, so the chore itself is reviewed once with
+`canon review add --change-id <slug> …` before it ships. Work that changes
+behavior is a feature change, never a chore.
 
 ## Where are we: `canon status`
 
@@ -488,8 +489,7 @@ uses, so status and the gate cannot disagree about a gap:
   stale or whose latest reviews are all `indeterminate`/`unavailable`
   (see `canon-review`), and the `canon review add` step names both. With
   `require_review` on, a `warning:` line counts the in-effect reviews that
-  predate review pinning (0.15), checked against the commit each pinned:
-  current, stale (named) and undecidable.
+  predate 0.23 review pinning and wait for `canon migrate`.
 - **Brief** (0.16, 0.17, 0.19) — for each `building`, `verifying` or `shipped`
   subject, and each `proposed` subject whose newest adopted change has a
   brief (a canon `brief.md`, or an external `proposal.md`), a `brief:`
@@ -545,8 +545,6 @@ uses, so status and the gate cannot disagree about a gap:
   refuted audit adds a `next:` step suggesting `canon evidence add
   --kind audit …` (recorded from an external evaluator; canon never runs
   one).
-- **Dropped bindings** — `dropped bindings (N):` lists every recorded
-  `--drop-attachment` (scenario, paths, reason); `drops[]` in `--json`.
 - **Brief overrides** — a `warning:` line per evidence record attested
   with `canon evidence add --override-reason` while its subject's brief
   was not approved: what it attests, who, when, the subject and the
@@ -562,7 +560,7 @@ uses, so status and the gate cannot disagree about a gap:
   first, then building, specced, proposed, shipped: an unapproved brief
   (building and later, and proposed once its change has a brief)
   → the human step below, which is then the subject's
-  only step; no scenario → `canon scenario new … --subject <id>` (and, when no
+  only step; no scenario → `canon scenario new … --subject-id <id>` (and, when no
   `.feature` file holds a scenario yet, `canon feature new` first, unless
   every subject waits on its brief); a missing case → `canon scenario new
   <surface>.<next nn> … --case <case>`; (building and later) an
@@ -574,12 +572,12 @@ uses, so status and the gate cannot disagree about a gap:
   Last, unowned scenarios → `canon status`, after tagging them in their
   `.feature` files (status re-indexes the edit; no sync step). With more
   than one `specs.roots[]` entry, every suggested `canon scenario new`
-  carries `--project`: the owning root for a missing case, `<root-id>`
+  carries `--project-id`: the owning root for a missing case, `<root-id>`
   (the reason lists the roots) for a subject that owns no scenario yet.
 - **The one human step.** Every step is the agent's to run except one,
   and it comes only once the brief is clean: while `canon brief check
-  --change <slug>` has blockers, the subject gets the planner step
-  `write the brief: canon brief check --change <slug> lists N blockers`
+  --change-id <slug>` has blockers, the subject gets the planner step
+  `write the brief: canon brief check --change-id <slug> lists N blockers`
   (`role: planner`) instead. A subject whose brief is enforced (its
   newest change's canon
   `brief.md` has no `Approved:` line, or it has no canon `brief.md` yet
@@ -591,10 +589,10 @@ uses, so status and the gate cannot disagree about a gap:
   and the approval is never assumed: `canon evidence add` refuses <id>'s
   scenarios and tasks until it is recorded; once the human answers,
   <record> (one call records the brief and the policy approval)``, where
-  `<record>` is ``record their words with `canon brief approve --change
+  `<record>` is ``record their words with `canon brief approve --change-id
   <c> --by <the human> --note "<their words>"` ``, or, for an external
   change, ``create <brief> holding a `Source: <proposal>` line, then
-  record their words with `canon brief approve --change <c> --by <the
+  record their words with `canon brief approve --change-id <c> --by <the
   human> --note "<their words>"` ``; for a brief edited after its
   approval, ``re-approve with `canon brief approve …` ``.
   It is the subject's only step, whatever its status: nothing suggests
@@ -640,7 +638,7 @@ Status fails closed rather than suggest progress the gate would refuse:
   ],
   "unowned": ["cart.promo.01"],
   "next": [
-    { "command": "stop and report the brief in openspec/changes/c-promo/proposal.md; build and attest nothing for promo until the human answers (one answer approves brief and policy)", "why": "promo: .canon/changes/c-promo/brief.md does not exist yet: change `c-promo` comes from the external plan openspec/changes/c-promo/proposal.md, which canon reads and never edits, so its approval lives in that canon file (an older change's approval does not cover a new scope), and the approval is never assumed: … once the human answers, create .canon/changes/c-promo/brief.md holding a `Source: openspec/changes/c-promo/proposal.md` line, then record their words with `canon brief approve --change c-promo --by <the human> --note \"<their words>\"` (one call records the brief and the policy approval)", "actor": "human" },
+    { "command": "stop and report the brief in openspec/changes/c-promo/proposal.md; build and attest nothing for promo until the human answers (one answer approves brief and policy)", "why": "promo: .canon/changes/c-promo/brief.md does not exist yet: change `c-promo` comes from the external plan openspec/changes/c-promo/proposal.md, which canon reads and never edits, so its approval lives in that canon file (an older change's approval does not cover a new scope), and the approval is never assumed: … once the human answers, create .canon/changes/c-promo/brief.md holding a `Source: openspec/changes/c-promo/proposal.md` line, then record their words with `canon brief approve --change-id c-promo --by <the human> --note \"<their words>\"` (one call records the brief and the policy approval)", "actor": "human" },
     { "command": "canon finding close --change-id c-cart --round 1 --seq 1 --disposition fixed --resolution-sha <sha> --actor-id <unit> --session-id <session>", "why": "cart: 1 open blocker finding(s) (first: …); fix it, commit, then close it", "actor": "agent" },
     { "command": "canon review add --project-id root --scenario-id cart.add.02 --reviewer <reviewer> --actor-id <reviewer> --session-id <review-session> --role reviewer --pin <sha> --original-spec-ref \"<feature file>\"", "why": "cart: 1 of 2 scenario(s) lack a qualifying review; …", "actor": "agent" },
     { "command": "canon status", "why": "1 scenario(s) carry no @subject tag (first: cart.promo.01); add `@subject:<id>` above each in its .feature file, then check again: …", "actor": "agent" }

package/dist/skills/reference/role-implementer.md

@@ -14,13 +14,16 @@ a `specs.roots[]` entry in `canon.yaml` (`root` by default).
 ```bash
 canon status --as implementer --json                  # once, at the start
 canon feature new <area>.<surface> --title "<title>" --as implementer --json
-canon scenario new <area>.<surface>.<nn> --subject <subject-id> --flow <F-id> --case <happy|edge|failure> --title "<title>" --as implementer --json
-canon scenario new --from - --as implementer --json     # many at once: NDJSON on stdin, one {"id","title","subject","flow","case",…} per line
+canon scenario new <area>.<surface>.<nn> --subject-id <subject-id> --flow <F-id> --case <happy|edge|failure> --title "<title>" --as implementer --json
+canon scenario new --from - --as implementer --json     # many at once: NDJSON on stdin, one {"id","title","subject-id","flow","case",…} per line
 canon evidence add --project-id <root-id> --all-scenarios --report <junit|cucumber|swift-testing>:<path> --kind test-run --role implementer --ref "<test command>" --actor-id <unit> --session-id <session> --as implementer --json
 canon evidence add --project-id <root-id> --scenario-id <id> --artifact <path> --kind test-run --role implementer --ref "<what it shows>" --actor-id <unit> --session-id <session> --as implementer --json
 canon evidence add --project-id <root-id> --scenario-id <id> --verdict divergent --artifact <path> --kind test-run --role implementer --ref "<the external limit, and where it is tracked>" --actor-id <unit> --session-id <session> --as implementer --json   # honest divergent evidence
+canon artifacts verify --full --as implementer --json  # bound files are in the artifact store (omit --full to trust the store's size and digest metadata); refuses when an object store is unreachable
 canon finding add --change-id <slug> --round <n> --seq <n> --severity <blocker|should-fix|note> --reviewer <unit> --actor-id <unit> --session-id <session> --summary "<defect>" --as implementer --json
 canon inventory sync --as implementer --json          # only after a write printed NOT refreshed
+canon query --kind <kind> --history --as implementer --json   # earlier versions too; without --history only the current record of each key
+canon ledger compact --as implementer --json           # only for a pre-0.23 ledger or an interrupted move (add --dry-run to preview)
 canon gate promote --as implementer --json            # only with write.promote: manual
 ```
 
@@ -52,10 +55,23 @@ After the first `status`, follow `meta.next` of each write; do not call
    `--all-scenarios`: one record per indexed scenario owning a case, each with
    the verdict its own cases show; any refusal writes none. For one scenario
    use `--scenario-id <id>` (repeatable) with `--report` or `--artifact`.
-   canon stores the bytes in `.canon/artifacts/sha256/` (commit it with the
-   ledger) and `canon gate check` re-checks them, so the working-tree report
-   may be gitignored. For a scenario about what users see, bind the screenshot
-   or recording (`--artifact <path>`). An external evaluator's audit is
+   A record binds exactly what its own write names (`--report`,
+   `--artifact`): nothing is carried forward from an earlier record, so name
+   every file the record should prove again. canon stores the bytes by digest
+   in the artifact store (by default `.canon/artifacts/sha256/`, committed
+   with the ledger; an object store when `canon.yaml`'s `artifact_store:` block
+   names one, in which case nothing is kept locally) and `canon gate check`
+   re-checks them, so the working-tree report may be gitignored. Run
+   `canon artifacts verify` to ask the store yourself; it refuses, never
+   passes, when an object store cannot be reached. Moving an existing store
+   (`canon artifacts migrate`) is the repo owner's call: do not run it.
+   For a scenario about what users see, let the test report carry its
+   screenshots: Playwright's JUnit reporter attaches, per test case, what a
+   test attaches (`testInfo.attach(name, {path})`, or `screenshot: 'on'`), and
+   one `evidence add --all-scenarios --report junit:<path>` binds to each
+   record only its own tests' files. A file the report does not name goes
+   with `--artifact <scenario-id>=<path>`; a bare `--artifact` in a batch is
+   refused. An external evaluator's audit is
    `--kind audit`; canon never generates one. Evidence for a task of an
    imported plan (`--task <id>`) must bind the artifact or report that proves
    the task; a canon command is never that proof. When the behavior cannot
@@ -67,16 +83,21 @@ After the first `status`, follow `meta.next` of each write; do not call
    the record is final when `evidence add` returns. Only with
    `write.promote: manual` (or no `write:` key) follow it with
    `gate promote`; `meta.next` names it.
-6. **A new record makes a signed review stale.** The add prints the reviewer
-   and the `canon review add … --pin <sha>` that re-pins it; that is the
-   reviewer's call. Do not run it yourself.
+6. **A changed result makes a signed review stale.** A review pins the
+   verdict and the checks (report format and matched case names, or artifact
+   digests) of the evidence it saw, not which record it was. Recording the
+   same verdict from the same checks keeps every review current; a different
+   verdict, different checks or an edited scenario stales it. The add prints
+   the reviewer and the `canon review add … --pin <sha>` that re-pins it; that
+   is the reviewer's call. Do not run it yourself.
 7. **After a fix or a chore, record the whole suite again.** A blocker the
    reviewer closed `fixed`, and an approved chore, are not done until every
    evidenced scenario has evidence newer than the close or the approval:
    run the suite and bind it with `canon evidence add --all-scenarios …`
-   (the shipping refusal names the scenarios and this command). The
-   re-review follows; a scenario whose gap was accepted is accepted again
-   by the reviewer once new evidence supersedes the old.
+   (the shipping refusal names the scenarios and this command). Reviews stay
+   current while the verdicts and checks are unchanged; a scenario whose gap
+   was accepted is accepted again by the reviewer once new evidence says
+   something different.
 
 ## Retry safety
 
@@ -88,6 +109,8 @@ response, run it again.
 
 When every scenario has evidence, the review is the reviewer's session, in a
 separate process: do not review your own change. A chore adds no scenarios:
-run the suite again and bind it with `--all-scenarios`, which supersedes the
-old evidence and makes pinned reviews stale; shipping needs that evidence
-newer than the chore's approval. Reference: `reference/canon-gate.md`.
+once it is approved, run the suite and bind it with `--all-scenarios`;
+shipping needs that evidence newer than the chore's approval, plus the
+reviewer's one change-level review of the chore (`review add --change-id`).
+Scenario reviews stay current when the verdicts and checks are unchanged.
+Reference: `reference/canon-gate.md`.

package/dist/skills/reference/role-orchestrator.md

@@ -10,11 +10,14 @@ Every line is complete; fill the `<placeholders>`.
 
 ```bash
 canon status --as orchestrator --json --fields next,waitingOn   # at the start and when resuming
-canon brief approve --change <slug> --by "<the human>" --note "<their words>" --as orchestrator --json
+canon brief approve --change-id <slug> --by "<the human>" --note "<their words>" --as orchestrator --json
 canon subject status <subject-id> --to <proposed|specced|building|verifying|shipped> --actor-id <unit> --as orchestrator --json
 canon subject status <subject-id> --to verifying --reason "<why>" --actor-id <unit> --as orchestrator --json   # reopen a shipped subject (--reason is required here; any other transition accepts it as a note)
 canon policy show --as orchestrator --json            # policy digest and its approval: approved, changed, unreadable or unapproved
 canon gate check --as orchestrator --json
+canon migrate --dry-run --as orchestrator --json       # on a repo upgraded from an earlier canon: the plan, nothing written
+canon migrate --as orchestrator --json                 # applies it (see "Upgraded repo")
+canon artifacts verify --as orchestrator --json        # the artifact store holds every bound file; refuses when an object store is unreachable
 ```
 
 ## Read the state
@@ -78,10 +81,27 @@ brief says the human ships. A follow-up on a shipped subject goes back to
 change, then `--to shipped` again. A chore on a shipped subject (`change
 new … --kind chore` names the reopen command) is approved first, then
 reopened the same way; shipping again needs the whole suite evidenced after
-the chore's approval (`evidence add --all-scenarios`) and a re-review. A
-blocker closed `fixed` needs the same. The refusal names the scenarios and
+the chore's approval (the implementer's `evidence add --all-scenarios`) and
+one change-level review of the chore from the reviewer (`review add --change-id
+<slug>`): the order is approval, evidence, review. A blocker closed
+`fixed` needs the suite again. The refusal names the scenarios and
 the command; never override them. `canon status` flags a shipped subject
 whose gate went red. A bad `--to` fails with `error.field` `--to` and
 `error.expected` listing the states.
 
+## Upgraded repo
+
+After a repo moves to a newer canon, run `canon migrate --dry-run`, then
+`canon migrate`. Besides the layout, it compacts the ledger (moves every
+superseded version to `.canon/archive`, as `canon ledger compact` does) and
+re-pins the reviews written before 0.23, which do not count until then (the
+gate, `status` and `subject status` print one advisory naming it). Commit
+what it changes. In CI run it with full history (`fetch-depth: 0`).
+
+`canon artifacts migrate --to <tier>` moves the local artifact store to an
+object store and removes the local blobs. It is the repo owner's decision,
+not a step of the loop: never run it yourself. If the repo is large, the
+store is slow or the human has not asked for it, ask the human first, and
+run it only on their answer (`--dry-run` previews it).
+
 Reference: `reference/canon-subject.md`.

package/dist/skills/reference/role-planner.md

@@ -12,17 +12,17 @@ Every line is complete; fill the `<placeholders>`.
 ```bash
 canon status --as planner --json                      # once, at the start
 canon subject new <subject-id> --domain <domain> --title "<title>" --actor-id <unit> --as planner --json
-canon change new <slug> --subject <subject-id> --title "<title>" --as planner --json
-canon change new <slug> --subject <subject-id> --kind chore --title "<title>" --as planner --json
-canon subject adopt <slug> --subject <other-subject-id> --as planner --json
-canon brief check --change <slug> --as planner --json
-canon brief approve --change <slug> --by "<the human>" --note "<their words>" --as planner --json
+canon change new <slug> --subject-id <subject-id> --title "<title>" --as planner --json
+canon change new <slug> --subject-id <subject-id> --kind chore --title "<title>" --as planner --json
+canon subject adopt <slug> --subject-id <other-subject-id> --as planner --json
+canon brief check --change-id <slug> --as planner --json
+canon brief approve --change-id <slug> --by "<the human>" --note "<their words>" --as planner --json
 ```
 
 After the first `status`, follow `meta.next` of each write. `brief check`
 lists blockers and advisories; bare `canon brief --as planner` names the next
 steps. While the brief has blockers, `status` and `change new`'s `meta.next`
-send you to write it (`write the brief: canon brief check --change <slug>
+send you to write it (`write the brief: canon brief check --change-id <slug>
 lists N blockers`); the human step appears only once the brief is clean and
 unapproved. A policy that no longer matches its approval fails closed
 (`POLICY_CHANGED_SINCE_APPROVAL`): never edit it; the human re-approves.
@@ -79,7 +79,8 @@ can observe: `change new … --kind chore`. Its brief is short (intent,
 category, invariants, checks, out of scope) and approved like any brief, one
 human stop. A chore adds no scenarios: the
 implementer runs the subject's suite again and binds it with
-`canon evidence add --all-scenarios …`, then a re-review follows. On a
+`canon evidence add --all-scenarios …`, then the reviewer records one
+change-level review of the chore (`canon review add --change-id <slug>`). On a
 shipped subject `change new` prints the reopen command for the orchestrator
 (`subject status <id> --to verifying --reason "<why>"`); the subject cannot
 ship again until the suite is evidenced after the chore's approval. Work that

package/dist/skills/reference/role-reviewer.md

@@ -10,14 +10,17 @@ Every line is complete; fill the `<placeholders>`. `<root-id>` is the `id` of
 a `specs.roots[]` entry in `canon.yaml` (`root` by default).
 
 ```bash
-canon brief check --change <slug> --as reviewer --json
+canon brief check --change-id <slug> --as reviewer --json
 canon gate check --as reviewer --json                 # once, before review add
 canon finding add --change-id <slug> --round <n> --seq <n> --severity <blocker|should-fix|note> --reviewer <me> --actor-id <me> --session-id <session> --summary "<defect>" --as reviewer --json
 canon finding list --change-id <slug> --open --as reviewer --json
 canon finding close --change-id <slug> --round <n> --seq <n> --disposition fixed --resolution-sha <sha> --as reviewer --json
 canon review add --project-id <root-id> --scenario-id <id> --scenario-id <id> --reviewer <me> --actor-id <me> --role reviewer --session-id <session> --pin <sha> --upstream-ref <ref> --as reviewer --json
 canon review add --project-id <root-id> --scenario-ids-from - --reviewer <me> --actor-id <me> --role reviewer --session-id <session> --pin <sha> --upstream-ref <ref> --as reviewer --json   # ids on stdin, one per line
+canon review add --project-id <root-id> --change-id <chore-slug> --reviewer <me> --actor-id <me> --role reviewer --session-id <session> --pin <sha> --upstream-ref <ref> --as reviewer --json   # a chore: one change-level review of its invariants and checks against the diff
 canon divergence accept --project-id <root-id> --scenario-id <id> --reason "<why the gap stays>" --tracking <issue-url-or-ref> [--expiry YYYY-MM-DD] --reviewer <me> --actor-id <me> --session-id <session> --as reviewer --json
+canon artifacts verify --full --as reviewer --json    # the files the evidence and reviews bind are in the artifact store; refuses when an object store is unreachable
+canon query --kind evidence --history --as reviewer --json   # every version, not only the current record
 ```
 
 `review add` needs `--upstream-ref <ref>` or `--original-spec-ref <path>`;
@@ -25,6 +28,14 @@ add `--artifact <path>` (repeatable) for user-visible behavior. A short
 `<sha>` is fine. With `write.promote: manual`, follow `finding add` and
 `finding close` with `canon gate promote --as reviewer --json`.
 
+A scenario review pins what you saw: the scenario's digest plus the verdict
+and checks (report format and matched case names, or artifact digests) of its
+latest evidence per role, not which record held them. It stays current when
+the implementer records the same verdict from the same checks again, and
+goes stale when the verdict or the checks differ or the scenario changes.
+Reviews written before 0.23 do not count until `canon migrate` re-pins them
+(an advisory names it); that is the orchestrator's step, not yours.
+
 Run `gate check` once, before `review add`: its `unreviewed-promotion`
 violations are the subjects and scenarios that need your review. Do not loop
 it. After `review add`, read its `meta.next` instead of calling `gate check`
@@ -87,9 +98,16 @@ ship guard and stays listed as `accepted-divergence` in `status` and
   directly; nothing to promote. canon stores and re-checks attached bytes
   and never compares images.
 - A blocker you close `fixed` stays blocking until the implementer records
-  the whole suite again (`evidence add --all-scenarios`); re-review after
-  it, since new evidence makes your pinned review stale.
-- Fixes you ask for return as a re-review of the same change. When a new
-  evidence record makes your review stale, look again before you re-pin.
+  the whole suite again (`evidence add --all-scenarios`); your pinned review
+  stays current when the new evidence says the same, otherwise look again.
+- Fixes you ask for return as a re-review of the same change. When new
+  evidence changes a verdict or the checks and so stales your review, look
+  again before you re-pin.
+  A chore has no scenarios: review it with one change-level review, `canon
+  review add --project-id <root-id> --change-id <slug> --reviewer <me> --role
+  reviewer --pin <sha> --upstream-ref <ref> …`. It signs the chore's
+  invariants and checks against the diff and pins its brief, so editing the
+  brief stales it. The chore also needs evidence recorded after its approval
+  (the implementer's `--all-scenarios` run) before it ships.
 
 Reference: `reference/canon-review.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@journeykit/canon",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "canon — harness knowledge substrate. JS launcher: platform detection + native binary resolution.",
   "license": "MIT",
   "type": "module",
@@ -30,9 +30,9 @@
   },
   "dependencies": {},
   "optionalDependencies": {
-    "@journeykit/canon-core-darwin-arm64": "0.22.0",
-    "@journeykit/canon-core-linux-x64": "0.22.0",
-    "@journeykit/canon-core-win32-x64": "0.22.0"
+    "@journeykit/canon-core-darwin-arm64": "0.24.0",
+    "@journeykit/canon-core-linux-x64": "0.24.0",
+    "@journeykit/canon-core-win32-x64": "0.24.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",