@journeykit/canon 0.21.0 → 0.22.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,9 @@ 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`) and re-reviewed before it ships.
 - 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
@@ -87,10 +91,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-authoring.md

@@ -110,6 +110,9 @@ 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
   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
+  from git history or a sibling scenario (the error shows its shape).
 - **Never hand-type, move, or edit a `# canon:` line.** The scaffold
   writes it directly above the scenario's tags:
 

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,35 @@ 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>" …`. That evidence stales the pinned
+reviews, so a re-review follows (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

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

@@ -150,7 +150,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`.
 

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
@@ -265,11 +272,13 @@ canon subject status: reopened `demo-subject` from shipped, recorded by `impl`:
 canon subject status: demo-subject → verifying — written directly; nothing to promote
 ```
 
-- `--reason "<one line>"` is required for `shipped → verifying` and
-  refused on any other transition (exit 2, as is a blank one). The new
-  record carries it with the actor and the change the work goes into:
+- `--reason "<one line>"` is required for `shipped → verifying` (exit 2
+  without it, as for a blank one) and optional on every other transition,
+  where it is an audit note. The new record carries it with the actor as
+  `status_reason: { reason: …, actor: { agent_id: impl } }`; a reopen also
+  records the change the work goes into:
   `reopen: { reason: …, change: c-demo, actor: { agent_id: impl } }`. The
-  next status write clears it, as it clears a waiver.
+  next status write clears both, as it clears a waiver.
 - Inside the approved scope it needs no human: the subject's newest
   adopted change's brief is approved, or there is no brief to answer.
   Otherwise it refuses, exit 1, naming the brief to approve, and
@@ -278,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.
@@ -561,10 +576,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,6 +18,7 @@ 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 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 gate promote --as implementer --json            # only with write.promote: manual
@@ -39,7 +40,8 @@ After the first `status`, follow `meta.next` of each write; do not call
    violation or a duplicate id: it names each problem). Specs live at
    `<root>/kind=feature/area=<area>/<surface>.feature` under a `specs.roots[]`
    root (default `.canon/specs`); `reference/canon-authoring.md` has the
-   scaffold.
+   scaffold. When you fill in a scenario, keep its `# canon: {...}` provenance
+   lines: dropping one aborts `inventory sync` on `missing-provenance`.
 2. **Units.** Give each unit its own actor id and session id and pass them on
    everything it records. A delegated unit attests its own work; never attest
    another unit's work under your id.
@@ -56,7 +58,11 @@ After the first `status`, follow `meta.next` of each write; do not call
    or recording (`--artifact <path>`). 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
@@ -64,6 +70,13 @@ After the first `status`, follow `meta.next` of each write; do not call
 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.
+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.
 
 ## Retry safety
 
@@ -76,5 +89,5 @@ 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`.
+old evidence and makes pinned reviews stale; shipping needs that evidence
+newer than the chore's approval. Reference: `reference/canon-gate.md`.

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

@@ -12,7 +12,8 @@ Every line is complete; fill the `<placeholders>`.
 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 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   # follow-up on a shipped subject
+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
 ```
 
@@ -57,9 +58,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,7 +75,12 @@ 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 (`evidence add --all-scenarios`) and a re-review. A
+blocker closed `fixed` needs the same. 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.
 

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,10 @@ 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 a re-review follows. 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,7 @@ 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 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
 ```
 
 `review add` needs `--upstream-ref <ref>` or `--original-spec-ref <path>`;
@@ -56,6 +57,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,6 +86,9 @@ 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.
+- 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@journeykit/canon",
-  "version": "0.21.0",
+  "version": "0.22.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.0",
-    "@journeykit/canon-core-linux-x64": "0.21.0",
-    "@journeykit/canon-core-win32-x64": "0.21.0"
+    "@journeykit/canon-core-darwin-arm64": "0.22.0",
+    "@journeykit/canon-core-linux-x64": "0.22.0",
+    "@journeykit/canon-core-win32-x64": "0.22.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",