@journeykit/canon 0.21.1 → 0.23.0

package/dist/skills/SKILL.src.md

@@ -25,7 +25,9 @@ a feature, a one-line request included. A human is needed once per scope:
   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>"`.
-  Never edit the policy to make the gate pass. A brief edited after its
+  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
   approval is not approved (`BRIEF_CHANGED_SINCE_APPROVAL`): it needs a new
   answer. The ship guard and `canon evidence add` refuse an unapproved or
   edited brief, but those are backstops: the stop itself is at step 1.
@@ -35,7 +37,11 @@ a feature, a one-line request included. A human is needed once per scope:
   implement, evidence, independent review. A follow-up that adds or changes
   a step of the brief edits the brief: that is a scope change and needs a
   new answer. A follow-up on a shipped subject reopens it
-  (`canon subject status <id> --to verifying --reason "<why>"`).
+  (`canon subject status <id> --to verifying --reason "<why>"`); a fix
+  closed `fixed`, and an approved chore, then need the whole suite evidenced
+  again (`evidence add --all-scenarios`, for a chore after its approval)
+  before it ships, and a chore also needs one change-level review
+  (`review add --change <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
@@ -54,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
@@ -87,10 +111,11 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
 - Pass `--json` and read stdout as one document. On failure it is
   `{"error":{"code","message","hint","retryable","field","expected"}}`: branch
   on `error.code`, fix the option `field` names using the `expected` values,
-  and follow `error.hint`. The codes are stable; `canon schema --errors --json`
-  lists them.
-- A renamed command still runs for one release, warns on stderr and sets
-  `meta.deprecated`; use the new name it prints.
+  and follow `error.hint`. Every refusal carries a concrete `hint`: follow
+  it. The codes are stable; `canon schema --errors --json` lists them.
+- `canon status` sends the planner to write the brief while `brief check`
+  has blockers; the human stop appears only when the brief is clean and
+  unapproved.
 - Page long lists with `--limit <n>` and `--cursor <nextCursor>` (`--all`
   for everything), and project fields with `--fields a,b` (`status`, `export`,
   `query`, `finding list`, `divergence status`, `context`).

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

@@ -21,15 +21,15 @@ Every violation carries one of these stable, grep-able strings:
 
 | Class | Meaning |
 |---|---|
-| `uncovered-cell` | Either a policy-required evidence cell (role × artifact) with no matching record, or — with `spec_coverage` enabled — a spec scenario that is unimplemented or mismatched, or a feature surface missing a `require_cases` case. The detail string distinguishes them. Coverage means "a test exists", not "a test passed": even a `Divergent` verdict satisfies the role-cell form. |
-| `unreviewed-promotion` | An artifact tagged `reviewed` has no matching ledger review record — or, with `spec_coverage.require_review` set, an in-scope scenario has no qualifying `Review`: none at all, only self-reviews, only stale reviews (the spec or evidence it pinned changed since), or only `indeterminate`/`unavailable` ones. See `canon-review`. |
+| `uncovered-cell` | Either a policy-required evidence cell (role × artifact) with no matching record, or — with `spec_coverage` enabled — a spec scenario that is unimplemented or mismatched, or a feature surface missing a `require_cases` case. The detail string distinguishes them. Coverage means "a test exists", not "a test passed": even a `Divergent` verdict satisfies the role-cell form. At `verifying → shipped`, a `Divergent` latest verdict is `uncovered-cell` unless a reviewer accepted it (see Accepted divergence below), and a chore's approval, like a blocker closed `fixed`, needs every evidenced scenario evidenced again afterwards (see Re-verification below). |
+| `unreviewed-promotion` | An artifact tagged `reviewed` has no matching ledger review record — or, with `spec_coverage.require_review` set, an in-scope scenario has no qualifying `Review`: none at all, only self-reviews, only stale reviews (the spec or evidence it pinned changed since), or only `indeterminate`/`unavailable` ones. Also, subject `policy`: the policy changed since its approval or its approval is unreadable (fails closed; see `canon-policy`). See `canon-review`. |
 | `trust-below-required` | Achieved trust level is below `policy.yaml`'s `trust_required` for its class — RELEASE-scoped only (`canon gate check --release`); never fires on an ordinary run. |
 | `stale-evidence` | A passing record degraded to stale: its declared surface changed since its `evidence_sha`, or HEAD moved past `staleness.max_commits_behind`. Only degrades an already-green record. Also: a file bound to a latest evidence record whose bytes are gone — no intact blob in `.canon/artifacts/sha256/` and no working-tree copy with the recorded digest — or a file bound to an in-effect review with no intact blob (see Bound evidence stays provable below). |
 | `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"`) 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`. |
+| `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 — or closed `fixed` while an evidenced scenario of the subject has no evidence recorded after the close (re-verification). 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. |
 
 ## `canon gate check [--repo <dir>] [--release]`
@@ -51,11 +51,12 @@ Exit `0` clean, `1` gate-red (any violation), `2` usage/load failure
 resolves through the nearest-ancestor `canon.yaml` walk, so it reads the
 repo ROOT's `.canon/policy.yaml` and `.canon/ledger` from any subdirectory.
 
-When `.canon/policy.yaml` exists but has no approval, or its bytes no
-longer match the approved digest, the gate prints `advisory: policy not
-approved: …` or `advisory: policy changed since approval: …` after its
-result, naming `canon policy approve --by <who>`; the exit code is
-unchanged (see `canon-policy`).
+When `.canon/policy.yaml` exists but has no approval, the gate prints
+`advisory: policy not approved: …` after its result, naming
+`canon policy approve --by <who>`; the exit code is unchanged. When its
+bytes no longer match the approved digest, or the approval cannot be read,
+the gate fails closed: the violation is reported and the exit is `1` (see
+`canon-policy`).
 
 Before it reads the scenario index, the gate rebuilds any stale part of
 it from the changed `.feature` files (the same code `canon inventory
@@ -200,6 +201,39 @@ Malformed rows in those three kinds do NOT surface as
 `malformed-evidence`; they are kept off the evidence violation set on
 purpose, so enabling nothing changes no existing verdict.
 
+### Accepted divergence and re-verification
+
+```bash
+canon divergence accept --project-id <root-id> --scenario-id <id> --reason "<why>" --tracking <issue-url-or-ref> [--expiry YYYY-MM-DD] --reviewer <me> --actor-id <me> --session-id <session> --as reviewer
+```
+
+A reviewer accepts a scenario whose latest evidence is `divergent` as a
+known gap limited by something outside the change; never to skip a fix.
+Refused (`DIVERGENCE_ACCEPT_REFUSED`) unless the latest verdict is
+divergent and the session and actor differ from the evidence's. The record
+pins that evidence: new evidence for the scenario, or `--expiry` passing,
+ends it. While it holds, the ship guard counts the cell covered and
+`status` and `gate check` keep listing it, never silently:
+
+```
+accepted divergences: 1 known gap(s) — not failing the gate:
+  accepted-divergence demo.page.02 — https://example.test/issues/1 (no expiry)
+```
+
+Re-verification is one rule with two triggers: a blocker whose latest
+disposition is `fixed`, and a chore change once approved, keep the subject
+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>" …`. 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 <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`)
 
 canon never generates or runs an audit. An external evaluator does, and
@@ -233,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`)
 
@@ -346,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`:
+### Reviews that predate 0.23 pinning (`canon migrate`)
 
-  ```
-  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.
-
-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)
 
@@ -478,10 +487,9 @@ 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`,
+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`.
 
@@ -492,10 +500,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
@@ -515,6 +523,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)`):
 
@@ -545,8 +563,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
@@ -685,13 +702,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-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 {add,promote,resolve,defer,status}   # tracks/resolves a divergence
+canon divergence {add,promote,resolve,defer,accept,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 {add,promote,resolve,defer,status}`
+- **Divergence** — `canon divergence {add,promote,resolve,defer,accept,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-policy.md

@@ -101,21 +101,43 @@ its result:
 advisory: policy not approved: .canon/policy.yaml has no approval record (.canon/policy.approval.json); a human reviews it and runs `canon policy approve --by <who>`
 ```
 
-Once the policy's bytes no longer match the approved digest, it prints
-this instead:
+Once the policy's bytes no longer match the approved digest, or the
+approval file cannot be read, the gate fails closed instead:
 
 ```
-advisory: policy changed since approval: .canon/policy.yaml is sha256:<now>, but `<who>` approved sha256:<then> at <time>; a human reviews it and runs `canon policy approve --by <who>`
+unreviewed-promotion policy — policy changed since approval: .canon/policy.yaml is sha256:<now>, but `<who>` approved sha256:<then> at <time>; … (--override-reason does not waive it); the human re-approves the policy in force with `canon policy approve --by <human> --note "<words>"`, or restore the approved .canon/policy.yaml (and .canon/policy.approval.json) from git
 ```
 
-An approval file that does not parse reads
-`advisory: policy approval unreadable: …`.
-`canon status` prints the same text as a `warning:` line (and in
-`--json` `warnings`). The advisory never changes an exit code: canon
-cannot tell whether a human or an agent ran the command, so the record
-names who approved which bytes, and the advisory says when that no
-longer holds. An agent runs `canon policy approve` only to record a
-human's answer, never without one and never on its own behalf.
+`canon gate check` exits `1`; `canon subject status` (the ship guard and
+the reopen) refuses with `POLICY_CHANGED_SINCE_APPROVAL`, or
+`POLICY_APPROVAL_UNREADABLE` for an unreadable approval, and
+`--override-reason` does not waive either. A policy never approved stays
+an advisory. `canon status` prints the same text as a `warning:` line (and
+in `--json` `warnings`). canon cannot tell whether a human or an agent
+ran `policy approve`, so the record names who approved which bytes and
+the gate fails when that no longer holds. An agent never edits the policy
+to pass the gate: it stops and asks the human, who re-approves or restores
+it. An agent runs `canon policy approve` only to record a human's answer,
+never without one and never on its own behalf.
+
+## `canon policy show [--json]`
+
+Prints the policy path and current digest, and the approval state
+(`approved`, `changed`, `unreadable` or `unapproved`) with the approver,
+time and approved digest:
+
+```
+policy: .canon/policy.yaml
+digest: sha256:37ea…
+approval: approved
+approved by: Ann
+approved at: 2026-10-17T04:57:45Z
+approved digest: sha256:37ea…
+note: ok
+```
+
+For `changed` and `unreadable` it adds `gate: fails closed (…)` with the
+human's way out. Read-only; it writes nothing.
 
 ## The closed CEL profile
 

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 <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
@@ -150,7 +152,8 @@ may carry the same scenario id. Exactly one provenance ref is required.
 `--actor-id` defaults to `canon`; `--session-id` fills `actor.session_id`.
 A Review carries no verdict about the behavior; the `verifying → shipped`
 ship gate still refuses missing or `Divergent` evidence verdicts on its
-own. It is written directly to the ledger, with no staging step, and says
+own (a `Divergent` one passes only while a reviewer's `canon divergence
+accept` holds). 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`.
 
@@ -166,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`, 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
+<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` 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:
 
@@ -224,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.
 
@@ -307,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_record --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

@@ -146,7 +146,14 @@ owns must also carry a scenario of each required `@case:` (e.g. one
 `@case:failure`) — attested golden-path scenarios alone do not ship. A
 Subject with no tagged scenario is refused rather than shipped on an
 empty set; so is one whose `scenario` records route away from the
-gate's rung. Each refusal prints by failure class (`uncovered-cell`),
+gate's rung. A `Divergent` latest verdict is refused as `uncovered-cell`
+unless a reviewer accepted it (`canon divergence accept`, see
+`canon-gate`): the hint names both ways out. Re-verification: a blocker
+closed `fixed` keeps blocking, and a chore's approval keeps the subject
+from shipping, until every evidenced scenario has evidence recorded after
+the close or the approval; the refusal names the scenarios and the
+`canon evidence add --all-scenarios …` command. Each refusal prints by
+failure class (`uncovered-cell`), carries a `hint`,
 exits 1, and the status stays `verifying`. `retired` is not gated.
 
 **The brief (0.16, 0.17, 0.19):** `verifying → shipped` also refuses where a brief
@@ -280,6 +287,12 @@ canon subject status: demo-subject → verifying — written directly; nothing t
 - The review guard does not run on a reopen (it prints `skipped … — a
   reopen moves the subject back to fix its gaps; shipping again runs
   it`). `verifying → shipped` afterwards runs every guard above again.
+- A policy that fails closed (`POLICY_CHANGED_SINCE_APPROVAL`,
+  `POLICY_APPROVAL_UNREADABLE`: see `canon-policy`) refuses the reopen and
+  the ship, and `--override-reason` does not waive it.
+- `canon change new` on a shipped subject prints the reopen command
+  (`canon subject status <id> --to verifying --reason "<why it reopens>"`)
+  in its output and `meta.next`.
 - `canon status` flags a shipped subject whose gate went red (whatever
   `verifying → shipped` would now refuse it on) and its only step is
   this reopen.
@@ -440,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 <slug> …` before it ships. Work that changes
+behavior is a feature change, never a chore.
 
 ## Where are we: `canon status`
 
@@ -475,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:`
@@ -532,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
@@ -563,10 +574,14 @@ uses, so status and the gate cannot disagree about a gap:
   than one `specs.roots[]` entry, every suggested `canon scenario new`
   carries `--project`: 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:
-  a subject whose brief is enforced (its newest change's canon
+- **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`
+  (`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
-  and comes from an external openspec `proposal.md`) gets
+  and comes from an external openspec `proposal.md`) and clean gets
   `human: stop and report the brief in <brief>; build and attest nothing for <id> until the human answers (one answer approves brief and policy)`,
   where `<brief>` is the canon `brief.md`, or the external `proposal.md`
   when no canon brief exists yet. Its reason reads ``<id>: <why

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

@@ -18,8 +18,12 @@ canon scenario new <area>.<surface>.<nn> --subject <subject-id> --flow <F-id> --
 canon scenario new --from - --as implementer --json     # many at once: NDJSON on stdin, one {"id","title","subject","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
 ```
 
@@ -51,20 +55,46 @@ 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, bind its own screenshot or recording
+   with that scenario: `--scenario-id <id> --artifact <path>`. A batch
+   (`--all-scenarios`) binds every file it names to every scenario, so give
+   a batch only the reports; never loop all screenshots into it. 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.
+   the task; a canon command is never that proof. When the behavior cannot
+   match the scenario because of something outside this change, record the
+   evidence `divergent` and say why in `--ref`; never record `faithful` to
+   pass. A reviewer may accept the tracked gap (`canon divergence accept`);
+   fixing the behavior and recording again is the other way out.
 5. **Promote.** Under `write: { promote: auto }` (what `canon init` writes)
    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). 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
 
@@ -76,6 +106,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. 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`).
+Scenario reviews stay current when the verdicts and checks are unchanged.
+Reference: `reference/canon-gate.md`.

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

@@ -13,7 +13,11 @@ canon status --as orchestrator --json --fields next,waitingOn   # at the start a
 canon brief approve --change <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
@@ -57,9 +61,14 @@ When `status` or `meta.next` shows a step with `actor: human` (the brief's
 approval), stop everything for that scope, report the brief to the human in
 its language, and wait. Do not start the implementer before the answer.
 Record the answer with `brief approve`. Never approve it yourself and never
-edit the policy to pass the gate. Inside an approved scope never stop for a
-human: fixes, follow-ups and re-reviews go straight to the implementer and
-reviewer in the same change.
+edit the policy to pass the gate. A policy that no longer matches the
+approval fails closed (`POLICY_CHANGED_SINCE_APPROVAL`, or
+`POLICY_APPROVAL_UNREADABLE`): the ship guard and the reopen refuse, and
+`--override-reason` does not waive it. Run `canon policy show`, then stop and
+ask the human to re-approve (`canon policy approve --by <human>`) or restore
+the approved policy from git; never edit the policy yourself. Inside an
+approved scope never stop for a human: fixes, follow-ups and re-reviews go
+straight to the implementer and reviewer in the same change.
 
 ## Move the subject
 
@@ -69,8 +78,30 @@ evidence or reviews, open blockers, an unapproved brief); fix the gap rather
 than overriding. Move to `shipped` yourself once its guard passes, unless the
 brief says the human ships. A follow-up on a shipped subject goes back to
 `verifying` with `--reason`, then the implementer and reviewer in the same
-change, then `--to shipped` again. `canon status` flags a shipped subject
+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 (the implementer's `evidence add --all-scenarios`) and
+one change-level review of the chore from the reviewer (`review add --change
+<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

@@ -21,7 +21,11 @@ canon brief approve --change <slug> --by "<the human>" --note "<their words>" --
 
 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.
+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>
+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.
 
 ## Steps
 
@@ -75,7 +79,11 @@ 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. Work that
+`canon evidence add --all-scenarios …`, then the reviewer records one
+change-level review of the chore (`canon review add --change <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
 changes behavior is never a chore: it is a feature change.
 
 ## Hand-off

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

@@ -17,6 +17,10 @@ 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 <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_record --history --as reviewer --json   # every version, not only the current record
 ```
 
 `review add` needs `--upstream-ref <ref>` or `--original-spec-ref <path>`;
@@ -24,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`
@@ -56,6 +68,27 @@ what you could not run: a reviewer that cannot run the tests says so and
 does not sign off; record that instead (`--outcome indeterminate`, or
 `unavailable` when you could not run).
 
+## Check the checks
+
+Passing is not enough: read each bound test against its scenario's Then
+steps. Record a finding (`finding add`) when a check pins behavior the
+scenario does not require, or skips a Then step the scenario states: such a
+test passes without proving the scenario. Do this before you sign.
+
+## Accept a known gap
+
+`divergence accept` is for a scenario whose honest evidence is `divergent`
+and whose gap is limited by something outside this change (an upstream
+limit, a platform bug) and is tracked there: give the reason and the
+`--tracking` reference, and an `--expiry` when the limit should be gone by
+a date. Never use it to skip a fix you can make in this change. It is your
+step, from a session that did not attest the evidence
+(`DIVERGENCE_ACCEPT_REFUSED` otherwise). The acceptance pins that evidence:
+new evidence for the scenario, or its expiry, ends it, and you accept (or
+the implementer fixes) again. An accepted gap counts as covered for the
+ship guard and stays listed as `accepted-divergence` in `status` and
+`gate check`.
+
 ## Record
 
 - Every defect is a finding; `finding list` shows round, seq, severity and
@@ -64,7 +97,17 @@ does not sign off; record that instead (`--outcome indeterminate`, or
 - Sign off in one batch with `review add`, all or nothing. It writes
   directly; nothing to promote. canon stores and re-checks attached bytes
   and never compares images.
-- 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.
+- A blocker you close `fixed` stays blocking until the implementer records
+  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 <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.21.1",
+  "version": "0.23.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.21.1",
-    "@journeykit/canon-core-linux-x64": "0.21.1",
-    "@journeykit/canon-core-win32-x64": "0.21.1"
+    "@journeykit/canon-core-darwin-arm64": "0.23.0",
+    "@journeykit/canon-core-linux-x64": "0.23.0",
+    "@journeykit/canon-core-win32-x64": "0.23.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",