@journeykit/canon 0.13.1 → 0.15.0

package/dist/skills/SKILL.src.md

@@ -1,16 +1,91 @@
 ---
 name: canon
-description: The provider-neutral Canon companion skill for agents using the canon CLI. Routes setup, authoring, validation, storage, ingestion, learning, retrieval, reporting, and provider-specific lazy references.
+description: Use for every build, implement, add-a-feature, change-a-feature or fix request in a repo that has canon.yaml, including sites, apps and games; prefer it there over generic site, app or game builder skills. Runs canon's working loop (brief, subject, scenarios with failure paths, units, implement, evidence, independent review, status transition) and routes to the canon CLI reference for setup, specs, gates, storage, ingestion, retrieval and reports.
 ---
 
 # Canon
 
-Use this single skill when working with Canon in a consumer repository. Canon's CLI remains explicitly modular; choose the command that matches the operation rather than asking an implicit router to guess.
+Features in this repo are managed with canon. This skill's job is the
+working loop below; the CLI manual lives in `reference/*.md` and
+`canon <command> --help`. Start every session with `canon status`: it says
+where each subject stands and lists the next commands.
 
-## Setup and provider projection
+## The working loop
+
+Follow these steps in order for every request that builds, changes or fixes
+a feature, a one-line request included. Two points stop for a human:
+
+- **The brief** (step 1): the request, your assumptions, your open questions.
+- **The policy**: `.canon/policy.yaml` (written by `canon init`) is what the
+  gate grades the work against. A human approves it with
+  `canon policy approve --by <who>` (and again after every change to it);
+  never edit it to make the gate pass, and never approve it yourself.
+
+When no human can answer, write the question into the brief, proceed on the
+assumption you state there, and say so in your final report.
+
+1. **Brief.** Write down the request verbatim, your assumptions, and the
+   questions you could not ask. It becomes the change's
+   `openspec/changes/<slug>/proposal.md`, which
+   `canon change new <slug> --subject <id> --title "…"` scaffolds once the
+   subject exists (step 2). A human approves the brief.
+2. **Subject.** `canon subject new <id> --domain <domain> --title "…"`, then
+   `canon change new <slug> --subject <id> --title "…"`, and put the brief in
+   the change's `proposal.md`.
+3. **Scenarios.** `canon feature new <area>.<surface> --title "…"`, then one
+   `canon scenario new <area>.<surface>.<nn> --subject <id> --case <case> --title "…"`
+   per behavior, with failure paths (`--case failure`) as well as `happy`
+   and `edge`. When the gate asks for a missing case (`require_cases`), add
+   a new scenario; never retag an existing one to satisfy it. Check the
+   corpus with `canon format specs` and index it with `canon inventory sync`.
+4. **Units.** Split the work into units (for example specs, domain code,
+   assets, review). Give each unit its own actor id and session id, and pass
+   them on everything the unit records (`--actor-id <unit> --session-id <session>`),
+   so the ledger shows which unit did what. A delegated unit attests its own
+   work; never attest another unit's work under your id.
+5. **Implement.** Write the code with tests whose names carry the scenario
+   id (`game.run.01: …`), so a test report binds to its scenario. Record a
+   defect you find in your own work as a finding the moment you find it,
+   before review:
+   `canon finding add --change-id <slug> --round <n> --seq <n> --severity <s> --reviewer <me> --actor-id <me> --session-id <session> --summary "…"`.
+6. **Evidence.** Per scenario:
+   `canon evidence add --project-id <root-id> --scenario-id <id> --kind test-run --role implementer --ref "<command>" --actor-id <unit> --session-id <session>`,
+   with `--report junit:<path>` or `--artifact <path>` when files prove it.
+   canon stores those bytes in `.canon/artifacts/sha256/` (commit it with the
+   ledger) and `canon gate check` re-checks them. Then `canon gate promote`.
+   An external evaluator's audit is recorded with `canon evidence add --kind
+   audit`; canon never generates one.
+   Evidence for a plan task (`--task <id>`, before `canon gate task`) must
+   bind the artifact or report that proves the task; a canon command
+   (`canon status`, `canon gate check`) is never that proof.
+7. **Independent review.** A different session from the one that wrote the
+   code and evidence reviews the change. The reviewer records every defect
+   the review finds as a finding:
+   `canon finding add --change-id <slug> --round <n> --seq <n> --severity <blocker|should-fix|note> --reviewer <me> --actor-id <me> --session-id <session> --summary "…"`,
+   then `canon gate promote`; once fixed,
+   `canon finding close --change-id <slug> --round <n> --seq <n> --disposition fixed --resolution-sha <sha>`
+   (a short sha is fine; canon resolves it)
+   and `canon gate promote`. Every bug fix adds or extends a scenario. The
+   reviewer signs off each scenario:
+   `canon review add --project-id <root-id> --scenario-id <id> --reviewer <who> --actor-id <who> --role reviewer --session-id <review-session> --pin <sha> --upstream-ref <ref>`
+   (written directly; nothing to promote).
+8. **Transition.** `canon subject status <id> <state>` along
+   `proposed → specced → building → verifying → shipped`. It refuses a move
+   the policy does not yet allow (missing evidence, missing reviews, open
+   blocker findings); fix the gap rather than overriding, and finish with
+   `canon gate check` clean.
+
+Every write command says whether it staged the record (then
+`canon gate promote`) or wrote it directly.
+
+## Command reference
+
+Load only the reference the current step needs.
+
+### Setup and provider projection
 
 ```bash
-canon init
+canon init                                   # canon.yaml, starter policy, AGENTS.md block, plans home
 canon skills install                         # detects .claude/.agents|.codex/.omp/.pi; if none exists, installs Claude+Codex
 canon skills install --providers=claude,codex,omp,pi
 canon skills check                           # read-only drift check
@@ -26,24 +101,23 @@ legacy `.codex/skills/canon*` projection from canon 0.13.0 or earlier is
 migrated by `canon skills install` and reported by `check`/`doctor`. OMP and Pi
 projections are project-local passive skill bundles: the
 `scripts/canon-retrieve-pre-dispatch.sh` file is available as a sidecar, not
-installed as a native hook. Load only the reference needed for the current
-task. `canon/skills-dev` is a separate developer-only legacy source and is
-installed explicitly with `--source canon/skills-dev`.
+installed as a native hook. `canon/skills-dev` is a separate developer-only
+legacy source and is installed explicitly with `--source canon/skills-dev`.
 
-## Route by task
+### Route by task
 
-- **Start product work / pin a durable unit:** read `reference/canon-subject.md`, then run `canon context` and `canon subject`.
-- **Write or reorganize `.feature` specs:** read `reference/canon-authoring.md` before editing; use the scaffold.
+- **Where the repo stands, subjects and changes (loop steps 1, 2, 8):** read `reference/canon-subject.md`; it covers `canon status`, `canon subject new|adopt|status` and `canon change new`.
+- **Write or reorganize `.feature` specs (step 3):** read `reference/canon-authoring.md` before editing; use the scaffold.
 - **Understand available fields/enums/policy bindings:** read `reference/canon-context.md` and `reference/canon-vocab.md`.
 - **Capture replayable run inputs / version prompts:** read `reference/canon-context.md`, then use `canon context-pack create|show|verify` and `canon prompt register|show` with explicit repository-relative JSON manifests.
 - **Validate or index specs:** read `reference/canon-fmt.md` and `reference/canon-inventory.md`.
-- **Run evidence gates, flip tasks, install hooks:** read `reference/canon-gate.md`.
-- **Finish a subject (claim work done):** read `reference/canon-review.md`. Order: test-run evidence (`canon evidence add`) → independent review of the adopted change (`canon finding add` per issue, fix, `canon finding close --disposition fixed --resolution-sha <sha>`) → `canon review add` per scenario by a reviewer other than the evidence actor → `canon subject status`. Commit each record with `canon gate promote`.
-- **Ingest artifacts or sessions:** read `reference/canon-artifact-ingest.md`, `reference/canon-session-ingest.md`, or `reference/canon-plan-import.md`.
+- **Evidence, gates, task checkboxes, hooks (step 6):** read `reference/canon-gate.md`.
+- **Findings and reviews (step 7):** read `reference/canon-review.md`.
+- **Ingest artifacts, sessions or plans:** read `reference/canon-artifact-ingest.md`, `reference/canon-session-ingest.md`, or `reference/canon-plan-import.md`.
 - **Configure storage, policy, plugins, or strategy learning:** read `reference/canon-storage.md`, `reference/canon-policy.md`, `reference/canon-plugins.md`, or `reference/canon-learn.md`.
 - **Retrieve dispatch guidance:** read `reference/canon-retrieve.md` and load `scripts/canon-retrieve-pre-dispatch.sh` when wiring hooks.
 - **Read generated reports and dashboards:** read `reference/canon-report-dashboard.md`.
 
-## Safety contract
+### Safety contract
 
-`canon format --check`, `canon skills check`, and `canon gate check` are read-only. Do not hand-edit generated reports, provenance lines, locks, or task evidence. Inspect `canon context` before authoring typed artifacts, and treat every failure class as actionable evidence rather than bypassing the gate.
+`canon status`, `canon format <root>`, `canon skills check`, and `canon gate check` are read-only. Do not hand-edit generated reports, provenance lines, locks, or task evidence. Inspect `canon context` before authoring typed artifacts, and treat every failure class as actionable evidence rather than bypassing the gate.

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

@@ -18,6 +18,23 @@ canon context --json          # the full machine-readable surface
 canon context --repo ../other # resolve a specific repo's surface
 ```
 
+The outline opens with a short header, then a blank line, then the
+schema outline starting at `capabilityVersion:`:
+
+```text
+status: run `canon status` for this repo's subjects, gaps and next commands
+warning: no policy: .canon/policy.yaml not found, so `canon gate check` requires no evidence, failure cases or review here
+```
+
+The `warning:` line appears when the policy file is absent or unreadable
+or has no `spec_coverage` section (the gate then requires no evidence,
+cases or review), or when that section is invalid (the gate refuses until
+it is fixed); it is omitted when coverage is in force. `context` describes what CAN be
+authored; `canon status` (see `canon-subject`) says where the repo stands
+and what to run next. `--json` is unchanged: the header adds no field,
+and `policy.spec_coverage`/`policy.diagnostics` already carry the same
+fact.
+
 ## Reproducible context packs and prompt bundles
 
 Use an explicit, repository-relative JSON manifest when a run needs a

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

@@ -15,26 +15,27 @@ release-scoped check (below) enforces it. A human-only `flagged` overlay
 overrides the ladder — a flagged artifact is never green regardless of
 evidence. (Author `policy.yaml`'s trust/staleness fields via `canon-policy`.)
 
-## The nine failure classes
+## The ten failure classes
 
 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, or only reviews by its own evidence actor). See `canon-review`. |
+| `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`. |
 | `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. |
+| `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 (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"`) or a bare `verified` claim with no attached command result. |
 | `open-blocker` | With `spec_coverage.require_review` set (and `block_on_findings`, the default), a Finding whose latest version is severity `blocker`, disposition `open`, on a change an in-scope subject adopted. Subject string `<change_id>#<round>.<seq>`. See `canon-review`. |
+| `false-success` | The latest audit record (`canon evidence add --kind audit`) of a scenario says `refuted`: an external evaluator found a counterexample to the claimed success. Always on, regardless of policy or sampling, and takes precedence over any declared faithful verdict; only a newer audit (`confirmed` or `indeterminate`) clears it. The detail names the evaluator, its version, its sha256 and the counterexample paths. |
 
 ## `canon gate check [--repo <dir>] [--release]`
 
 Assembles coverage + ledger + staleness + the always-on trust-ladder
-check, plus the opt-in spec-coverage check, over the resolved repo's
+check + the bound-artifact check, plus the opt-in spec-coverage check, over the resolved repo's
 corpus and runs them, printing every violation grouped by failure class.
 `--release` additionally engages the release-scoped
 `trust-below-required` check; the trust-ladder check is never dropped
@@ -50,6 +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`).
+
 ### The spec-derived worklist (`spec_coverage`, opt-in)
 
 Coverage groups the EVIDENCE corpus, so it can only ever enumerate
@@ -60,7 +67,7 @@ adds the other direction: it starts from the Scenario corpus
 an unimplemented or mismatched spec becomes a reported violation.
 
 ```yaml
-# .canon/policy.yaml — ABSENT by default; absent means zero violations
+# .canon/policy.yaml — absent means zero violations; `canon init` writes a starter
 spec_coverage:
   require_evidence: true
   scope: [building, verifying]   # optional; omit for the whole corpus
@@ -69,11 +76,28 @@ spec_coverage:
   require_review: {}             # optional; see Independent review below
 ```
 
+`canon init` writes a starter `.canon/policy.yaml` with this section on
+(`require_evidence: true`, `require_cases: [failure]`,
+`require_review: {}`; see `canon-policy`). When the section is absent and
+the indexed corpus has scenarios, the gate says so after its result, on
+stdout like its other advisories, and the exit code is unchanged:
+
+```
+advisory: spec_coverage is off — 12 scenario(s) are not checked for evidence; see .canon/policy.yaml
+```
+
+A present section, even `require_evidence: false` or a malformed one
+(already a violation), and an empty corpus print no advisory.
+
 - **Unimplemented** — no `EvidenceRecord` carries the scenario's
   `(project_id, scenario_id)`. Author one with
   `canon evidence add --scenario-id <id> --project-id <root-id>`; both
   flags are required together, because two spec roots may carry the same
-  scenario id.
+  scenario id. `--summary` is allowed here too (scanned for fabrication
+  markers like a task's); it is a row suffix only when the record also
+  names a `--task`. A record carrying both `--task` and `--scenario-id`
+  is one attestation answering both joins: it counts for the task cell
+  and for the scenario cell (verdicts, the shipped gate, the review gate).
 - **Mismatched** — the folded divergence state is `open`,
   `still-divergent`, or `resolved-invalid` (a resolution whose app sha
   has moved), or the latest ledger verdict is `divergent`.
@@ -94,12 +118,18 @@ spec_coverage:
 - **Independent review** (`require_review`) — scenarios whose subject is
   in `require_review.scope` (default `[verifying, shipped]`; `[]` = every
   scenario; independent of `scope` above) need a `Review` record
-  (`canon review add`), by a reviewer and actor other than the
-  scenario's evidence actor when `distinct_actor` (default `true`);
-  gaps are `unreviewed-promotion`. With `block_on_findings` (default
-  `true`), an open `blocker` Finding on a change an in-scope subject
-  adopted is `open-blocker`. `exclude_lanes` also exempts scenarios
-  from review. Full contract: `canon-review`.
+  (`canon review add`) whose latest version per reviewer is `signed`,
+  still matches the scenario digest and latest evidence it pinned
+  (a review written before 0.15 has no pins and skips this check), and,
+  when `distinct_actor` (default `true`), is by a reviewer and actor
+  other than the scenario's evidence actor and from a session other than
+  any evidence session when both carry one (`--session-id`);
+  gaps are `unreviewed-promotion`, and the detail says whether the
+  review is missing, a self-review, stale (naming whether the spec, the
+  evidence or both changed), or not signed. With `block_on_findings`
+  (default `true`), an open `blocker` Finding on a change an in-scope
+  subject adopted is `open-blocker`. `exclude_lanes` also exempts
+  scenarios from review. Full contract: `canon-review`.
 
   ```yaml
   spec_coverage:
@@ -110,12 +140,28 @@ spec_coverage:
       block_on_findings: true       # default
   ```
 
+- **Sampled audits** (`require_audit`) — a deterministic sample of
+  in-scope scenarios (`require_audit.scope`, default `[verifying,
+  shipped]`; `exclude_lanes` applies) must carry an external audit
+  (`canon evidence add --kind audit`, see Audit records below). A sampled
+  scenario whose latest audit is missing or `indeterminate` is
+  `uncovered-cell`:
+
+  ```
+  uncovered-cell cart.add.01 — sampled for audit by spec_coverage.require_audit (rate 0.1, seed `s1`) and has no audit record — …
+  uncovered-cell cart.add.01 — sampled for audit by spec_coverage.require_audit (rate 0.1, seed `s1`), but its latest audit is indeterminate (evaluator `judge` 1.2) — …
+  ```
+
+  Keys, defaults and the exact sampling formula: `canon-policy`.
+
 Two refusals rather than a silent pass, both surfacing as
 `uncovered-cell` on the subject `spec_coverage`:
 
 - A **malformed section** (unknown key, unknown `scope` status, or a
-  malformed `require_cases`/`require_review` — unknown key, bad status,
-  `null`, non-mapping) refuses at check time. It is never treated as
+  malformed `require_cases`/`require_review`/`require_audit` — unknown
+  key, bad status, `null`, non-mapping, a missing or out-of-range
+  `rate`) refuses at check time (`uncovered-cell spec_coverage — ...
+  unusable`). It is never treated as
   absent — a typo must not be silently equivalent to not opting in.
 - A **corpus kind routed off the gate's rung** (`scenario`,
   `divergence`, or `subject` sent anywhere but `local`) refuses, because
@@ -125,6 +171,54 @@ 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.
 
+### Audit records (`--kind audit`)
+
+canon never generates or runs an audit. An external evaluator does, and
+canon records its result:
+
+```bash
+canon evidence add --kind audit --project-id root --scenario-id cart.add.01 \
+  --ref "judge run 42" --role reviewer \
+  --evaluator-id judge --evaluator-version 1.2 \
+  --evaluator-digest <64 lowercase hex sha256> \
+  --audit-result refuted --report junit:audit/counterexample.xml
+```
+
+- `--kind audit` requires `--evaluator-id`, `--evaluator-version`,
+  `--evaluator-digest` (sha256, 64 lowercase hex), `--audit-result
+  confirmed|refuted|indeterminate`, and `--scenario-id` with
+  `--project-id`. It refuses `--task`, `--verdict`, `--surface-ref` and
+  `--approval-*`; the four evaluator flags are refused on any other kind.
+  All refusals exit `2`.
+- The record carries `audit: {evaluator_id, evaluator_version,
+  evaluator_digest, result}`; its verdict is derived (`confirmed` →
+  faithful, `refuted` → divergent, `indeterminate` → not-applicable).
+- Optional `--report`/`--artifact` counterexamples are bound and stored
+  like any report; the latest audit's bindings are re-hashed by the
+  artifact check.
+- Audits fold apart: per `(project_id, scenario_id)` there is a latest
+  declared record and a latest audit. An audit never becomes the
+  scenario's latest declared verdict.
+- `canon subject status <id> shipped` refuses `false-success`, and an
+  owed sampled audit when `require_audit.scope` covers `shipped`.
+- `canon status` shows an `audits` section (sampled / confirmed / owed /
+  refuted) and suggests `canon evidence add --kind audit …` in `next:`.
+
+### Dropping a binding (`--drop-attachment`)
+
+`canon evidence add` for a scenario refuses (exit `2`) when the
+scenario's current latest record of the same fold (declared records, or
+audit records for an audit) — committed ledger plus `_staging` — binds
+files the new record does not. The refusal names the paths and two ways
+out: re-bind them (`--artifact`/`--report`; new bytes at the same path
+are fine), or drop them on purpose with `--drop-attachment <path>`
+(repeatable) and one single-line `--drop-reason <text>`. The drop is
+recorded as `attachment_drop: {paths, reason}`. Refused (`2`): a drop
+without a reason, a reason without a drop, a drop path that is not
+actually dropped, a multi-line reason, or a drop without
+`--scenario-id` (task-only evidence has no drop guard). `canon status`
+lists recorded drops (`dropped bindings (N):`; `drops[]` in `--json`).
+
 ### Review-waiver advisories
 
 A subject moved into a review-scoped status with `canon subject status
@@ -141,6 +235,17 @@ review waivers: 1 advisory(ies) — not failing the gate:
 
 The waiver lasts only until the subject's next status write.
 
+### Reviews that predate pinning
+
+With `require_review` on, the reviews in effect (latest per reviewer and
+scenario) that carry no pins were written before 0.15. They keep
+counting, and one advisory line after the violations counts them; the
+exit code is unchanged:
+
+```
+advisory: 340 review(s) predate review pinning (0.15) and still count without a check that their scenario's spec and evidence are unchanged; a new `canon review add` pins what it saw
+```
+
 ## Experimental: evidence binding (`experimental.evidence_binding`, off by default)
 
 An evidence record is an attestation: canon never runs `--ref`, and it
@@ -159,12 +264,20 @@ canon evidence add ... --report junit:target/nextest/default/junit.xml
 canon evidence add ... --report cucumber:reports/cucumber.json
 ```
 
-The case is found by the scenario id in its name, classname, or Cucumber
-tag — dotted (`cart.add.04`) or underscored (`cart_add_04`, the form a
-test function carries) — or named exactly with `--report-case <name>`
-(a Rust test by its function name). No match refuses (exit 2); a
-`faithful` verdict over a failed or skipped case refuses (exit 1). Files
-must be inside the repository and are recorded by relative path.
+A case is bound when the scenario id is its OWN: the first
+scenario-id-shaped token (`<area>.<surface>.<nn>`) in its full name —
+classname (a describe path) first, then name — dotted (`cart.add.04`) or
+underscored (`cart_add_04`, the form a test function carries), equals
+the scenario id; a Cucumber tag equal to it binds too. Start each test
+name with its scenario id: `game.session.04: restarting as in
+game.session.01` binds to `game.session.04` only, never to the id it
+mentions. Each bound case is its own attachment with its name and
+outcome. `--report-case <name>` (repeatable; a Rust test by its
+function name) ADDS cases; it never hides the scenario's own. No match,
+or a `--report-case` naming no case, refuses (exit 2); a `faithful`
+verdict when ANY bound case failed or was skipped refuses (exit 1). Files
+must be inside the repository, are recorded by relative path, and are
+stored (see Bound evidence stays provable).
 
 Strength, weakest first: `attested` (no attachment) < `artifact` (any
 bound file) < `report` (a parsed report whose case passed). The policy
@@ -189,6 +302,49 @@ violation in every mode. Canon still cannot know whether the bound test
 actually exercises the scenario — binding narrows the trust gap, it does
 not close it.
 
+## Bound evidence stays provable (the artifact store)
+
+`canon evidence add --artifact/--report` copies each bound file into
+`.canon/artifacts/sha256/<hex>`, named by its sha256. Writes go through a
+temp file and a rename, and a digest already stored intact is not written
+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>`.
+
+`canon gate check` re-checks every file bound to a LATEST evidence record
+(the latest per task and per `(project_id, scenario_id)`):
+
+- the stored blob exists and hashes to the recorded digest → clean, even
+  after the working-tree file is rewritten (a smoke script that rewrites
+  `reports/smoke.json` on every run no longer orphans the record);
+- no blob, but the working-tree path still hashes to the recorded digest
+  → clean, with an advisory naming `canon evidence vault` (records from
+  before the store existed):
+
+  ```
+  evidence artifacts: 1 bound file(s) not in the artifact store — not failing the gate; run `canon evidence vault` to store them before the working tree changes:
+    unstored cart.add.01 reports/junit.xml (sha256 b7cb…) is verified against the working tree only
+  ```
+- anything else → `stale-evidence` naming the path, the recorded digest,
+  and what the store and the working tree hold now (`missing` or a
+  digest), ending with why: a stored blob that no longer hashes to its
+  name "does not match its name, so its bytes were altered"; a missing
+  one means "the bound bytes are gone". Re-run the test and re-attest
+  with `canon evidence add`.
+
+The check applies to every latest record, not only subjects in
+`spec_coverage.scope`: a binding is a claim about bytes whatever the
+subject's status, and a repo with no `spec_coverage` would otherwise never
+have its bindings checked. A superseded record is not checked —
+re-attesting is the fix.
+
+`canon evidence vault [--max-artifact-mib <N>]` stores the bytes for
+existing records: every attachment whose working-tree file still matches
+its digest is copied in, and everything else is listed as not stored,
+with both digests. It exits `0` whenever it ran (the gate decides whether
+an unstored file matters), `2` when the ledger cannot be read or a write
+fails.
+
 ## Effect-aware risk approvals (`risk_tiers`)
 
 `risk_tiers` is absent by default and remains a no-op when absent. When it
@@ -229,12 +385,28 @@ the compat default `[{ dialect: openspec, root: <repo> }]`; no source
 locating the task at all is a loud failure naming every source consulted.
 It requires
 a matching non-`Divergent` evidence record, and flips `- [ ]` → `- [x]`
-with an appended evidence note ONLY on a clean check. Every other path —
-missing evidence, a `Divergent` verdict, a fabricated note — leaves the
-row byte-unchanged and exits `1` with the blocking violation on stderr.
-An already-`[x]` row is an idempotent no-op (exit `0`). An unknown
+with an appended evidence note ONLY on a clean check. The note
+aggregates every record bound to the task, on one line:
+`— ✅ 3 evidence records (2 faithful, 1 not-applicable); latest: <summary>`
+(the latest `--summary`, or a default naming the latest passing record).
+Every other path — missing evidence, a `Divergent` verdict, a fabricated
+note on any of the task's records — leaves the row byte-unchanged and
+exits `1` with the blocking violation on stderr. After a flip, the plan
+source is re-ingested so the record store's task status agrees with the
+checkbox (`canon query --kind task` reads `done`); a failed re-ingest is
+a stderr warning naming `canon ingest plans`, never a failed flip.
+The success line is `canon gate task: <task_id> flipped — written
+directly; nothing to promote`. An already-`[x]` row is an idempotent no-op (exit `0`). An unknown
 `task_id` is reported (exit `1`).
 
+A flip on evidence that cannot prove the task still succeeds, but warns
+on stderr: when none of the task's evidence records binds a file and one
+of them cites a canon command as its `--ref` (`canon gate check`,
+`canon status`), the warning says to bind the artifact or report that
+proves the task (`canon evidence add --task <id> --artifact <path>` or
+`--report <format>:<path>`). A canon command reports on canon's own
+records, so it is never the proof of a task.
+
 ```bash
 canon gate task my-change#5.2 --repo .
 ```
@@ -258,6 +430,15 @@ canon gate promote --repo .            # land every staged candidate
 canon gate promote --repo . --dry-run  # preview only
 ```
 
+Which writes need this step: `evidence add`, `finding add` and `finding
+close` stage, and their success line ends ``— run `canon gate promote`
+to commit it``. `divergence stage` stages for `canon divergence promote`
+and names it. Every other write — `review add`, `divergence
+resolve|defer`, `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`.
+
 ## `canon gate install-hooks [--repo] [--event] [--matcher] [--command] [--timeout]`
 
 Idempotent, diff-only hook-seam installation: merges one
@@ -280,8 +461,8 @@ Prefer this over hand-editing `settings.json`/`hooks.json`.
 
 ## `canon gate selftest`
 
-Runs the shipped fixture corpus — one fixture per failure class (nine,
-including `open-blocker`), each a
+Runs the shipped fixture corpus — one fixture per failure class (ten,
+including `false-success`), each a
 deliberately broken corpus proving that class fires and ONLY that class
 (both under-detection and over-triggering fail the run). Takes no
 `--repo`; self-contained. Run it before trusting any other `canon gate

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

@@ -17,6 +17,8 @@ plans:
       root: .              # resolved relative to canon.yaml's directory
 ```
 
+- `canon init` writes exactly this source, plus an empty
+  `openspec/changes/` (so the adapter never scans the repo root itself).
 - An absent `plans:` section = zero sources (a clean no-op).
 - A present section parses STRICTLY: a typo'd key, an unregistered
   `dialect`, or a nonexistent `root` fails the command loud, naming the
@@ -135,8 +137,8 @@ downstream reader's job.
 ## What this skill does NOT cover
 
 - **Authoring an openspec change dir** (`proposal.md`/`tasks.md`
-  conventions) — see the openspec CLI's own docs; this skill covers
-  IMPORTING that shape, not producing it.
+  conventions) — `canon change new` scaffolds one and adopts it into a
+  subject (see `canon-subject`); this skill covers IMPORTING that shape.
 - **`canon gate check`/`canon gate task`** (the hand-authored one-task-at-
   a-time path this complements at bulk) — see `canon-gate`.
 - **Wiring an imported `Task`/`Change` into a `canon gate` decision** —

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

@@ -23,6 +23,71 @@ uncovered-cell spec_coverag — `spec_coverag` is not a known top-level policy.y
 The known keys still resolve normally, and `canon context` lists the
 diagnostic and reports `clean: false`.
 
+## The starter policy `canon init` writes
+
+A fresh `canon init` writes `.canon/policy.yaml` (skip it with
+`--no-policy`; an existing file is never overwritten):
+
+```yaml
+spec_coverage:
+  require_evidence: true    # every scenario needs evidence
+  require_cases: [failure]  # every feature surface needs a @case:failure scenario
+  require_review: {}        # verifying/shipped subjects need an independent review
+```
+
+The file carries comments explaining each field. It loads with zero
+diagnostics. It is what `canon gate check` grades the work against, so a
+human should review and approve it, and every later change to it (next
+section). The agent doing the work should not write its own grading
+policy. Narrow it with `scope: [building, verifying]` to check evidence
+only for subjects in those statuses (see `canon-gate`).
+
+## Approving the policy
+
+```bash
+canon policy approve --by <who> [--note <text>] [--repo <dir>]
+```
+
+A human runs this after reviewing `.canon/policy.yaml`. It writes
+`.canon/policy.approval.json` directly (nothing to promote):
+
+```json
+{
+  "policy_digest": "sha256:<sha256 of the policy.yaml bytes>",
+  "approved_by": "<who>",
+  "approved_at": "2026-10-11T09:00:00Z",
+  "note": "<text, or null>"
+}
+```
+
+Commit it with the policy: the file is tracked, and neither canon's
+`.gitignore` nor the one `canon init` writes ignores it. Running the
+command again replaces the record. With no `.canon/policy.yaml` it is
+refused (exit `2`), and so is an empty `--by`.
+
+While a policy exists with no approval, `canon gate check` prints after
+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:
+
+```
+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>`
+```
+
+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 never runs `canon policy approve` on its own
+behalf.
+
 ## The closed CEL profile
 
 Every expression is evaluated against exactly one variable, `record` (the
@@ -105,6 +170,40 @@ question rather than adding an expression field. Conditional logic about
 what a record *means* lives in `policy.yaml`/`applies_when:`, evaluated
 against the record's fields, never inside the record.
 
+## Sampled audits: `spec_coverage.require_audit`
+
+Optional; absent means no audit is ever owed (a recorded `refuted` audit
+is still `false-success` regardless — see `canon-gate`).
+
+```yaml
+spec_coverage:
+  require_audit:
+    rate: 0.1                  # required: a number in [0, 1]
+    seed: "2026-q4"            # optional string; default ""
+    scope: [verifying, shipped] # optional subject statuses; this is the default; [] = every scenario
+```
+
+`spec_coverage.exclude_lanes` applies. A malformed `require_audit` —
+unknown key, missing `rate`, `rate` out of range or a string, bad
+`scope`, `null` or a non-mapping — poisons the whole `spec_coverage`
+section: the gate reports `uncovered-cell spec_coverage — ... unusable`
+rather than checking anything under it.
+
+Sampling is deterministic. A scenario is in the sample iff the first 8
+bytes of
+
+```
+sha256(seed || 0x00 || project_id || 0x00 || scenario_id)
+```
+
+read as a big-endian u64, are less than `rate · 2^64` — computed exactly,
+as a comparison against `ceil(rate · 2^64)`, so `rate: 0` samples nothing
+and `rate: 1` samples everything. A sampled in-scope scenario whose
+latest audit is missing or `indeterminate` is `uncovered-cell`; with
+`shipped` in `scope`, `canon subject status <id> shipped` also refuses
+it. `canon context` and the `canon status` policy line show
+`require_audit=(rate=… seed=`…` scope=…)`.
+
 ## Effect-aware risk tiers
 
 The optional `risk_tiers` section is not CEL. Absent means no risk-approval

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

@@ -17,15 +17,15 @@ state they are in.
 The order an agent follows to claim a subject done:
 
 1. **Test-run evidence** per owned scenario (`canon evidence add
-   --scenario-id <id> --project-id <root-id> ...`, then `canon gate
-   promote`). See `canon-gate`.
+   --scenario-id <id> --project-id <root-id> ... --session-id <session>`,
+   then `canon gate promote`). See `canon-gate`.
 2. **Independent review** of the change(s) the subject adopted. Record
    each issue the reviewer raises as a Finding, fix it, then close it:
 
    ```bash
    canon finding add --change-id c-demo --round 1 --seq 1 \
      --severity blocker --disposition open --reviewer reviewer-2 \
-     --summary "unbounded subprocess wait"
+     --summary "unbounded subprocess wait" --session-id review-session-1
    canon gate promote
    # ... fix, commit ...
    canon finding close --change-id c-demo --round 1 --seq 1 \
@@ -33,15 +33,23 @@ The order an agent follows to claim a subject done:
    canon gate promote
    ```
 
-3. **One Review per scenario**, by someone other than the evidence actor:
+3. **One Review per scenario**, by someone other than the evidence actor,
+   from a session other than the one that attested the evidence, after
+   the evidence is in (the review pins what it saw):
 
    ```bash
    canon review add --project-id root --scenario-id world.demo.01 \
      --reviewer reviewer-2 --actor-id reviewer-2 --role reviewer \
+     --session-id review-session-1 \
      --pin "$(git rev-parse HEAD)" --upstream-ref "pr#41"
-   canon gate promote
    ```
 
+   `review add` writes directly; there is nothing to promote. If the
+   reviewer could not reach a verdict, record that instead of signing:
+   `--outcome indeterminate` (or `unavailable` when it could not run).
+   Changing the scenario or re-attesting it afterwards makes the review
+   stale; review it again.
+
 4. **Move the subject**: `canon subject status <id> verifying`, later
    `shipped`. See `canon-subject`.
 
@@ -57,15 +65,37 @@ work collapsed into one identity.
 canon finding add --change-id <c> --round <n> --seq <n> \
   --severity blocker|should-fix|note --disposition open \
   --reviewer <who> --summary "<one line>" \
-  [--reviewed-sha <sha>] [--file-ref path/to/file.rs:120-134] [--actor-id <id>]
+  [--reviewed-sha <sha>] [--file-ref path/to/file.rs:120-134] [--actor-id <id>] [--session-id <id>]
 canon finding close --change-id <c> --round <n> --seq <n> \
-  --disposition fixed --resolution-sha <sha>     # or rejected / deferred / open
+  --disposition fixed --resolution-sha <sha> [--session-id <id>]   # or rejected / deferred / open
 ```
 
-Both stage a candidate; `canon gate promote` commits it. `finding close`
+Both stage a candidate; `canon gate promote` commits it, and both say so
+(``… — run `canon gate promote` to commit it``). `finding close`
 changes only the disposition (and `resolution_sha` with it); severity,
 reviewer, summary, and refs are copied from the committed record. It
-appends a second version at the same natural key — the first stays.
+appends a second version at the same natural key — the first stays. Its
+`--actor-id` and `--session-id` name who authored the transition; the
+raiser's stay on the first version.
+
+Every sha flag (`--reviewed-sha`, `--resolution-sha`, `--introduced-by`)
+takes a full 40-character sha or a short one (4 or more lowercase hex
+characters). A short sha is resolved with `git rev-parse --verify
+<sha>^{commit}` in the repo, and the record stores the full sha. It is
+refused (exit `2`) when it names no commit, when more than one commit
+starts with it (pass more characters), when it only resolves by peeling a
+tag, or outside a git work tree.
+
+### A defect the author found in its own work
+
+Record it like any other finding, at the moment you find it and before
+review, with `--reviewer` and `--actor-id` set to your own id; never ask
+the reviewer to record it later under theirs. Nothing refuses a finding
+whose reviewer is also the implementer, and an open `blocker` the author
+raised blocks under `block_on_findings` exactly like a reviewer's.
+`--introduced-by` names the commit that introduced the defect, not who
+found it: `--introduced-by self` is a usage error (exit 2) that points at
+`--reviewer`.
 
 ### Severities
 
@@ -98,15 +128,70 @@ fixed finding reopened with `--disposition open` counts as open again.
 ```bash
 canon review add --project-id <root-id> --scenario-id <id> \
   --reviewer <who> --pin <sha-or-ref> --role <role> \
-  (--upstream-ref <ref> | --original-spec-ref <ref>) [--actor-id <id>]
+  (--upstream-ref <ref> | --original-spec-ref <ref>) [--actor-id <id>] [--session-id <id>] \
+  [--outcome signed|indeterminate|unavailable] \
+  [--reviewer-provider <p>] [--reviewer-model <m>] [--reviewer-harness <h>]
 ```
 
 One attributed Review record for one scenario, joined on
 `(project_id, scenario_id)` — both are required because two spec roots
 may carry the same scenario id. Exactly one provenance ref is required.
-`--actor-id` defaults to `canon`. A Review carries no verdict; the
-`verifying → shipped` ship gate still refuses missing or `Divergent`
-evidence verdicts on its own. Commit with `canon gate promote`.
+`--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
+so: `canon review add: wrote <path> (new) — written directly; nothing to
+promote`.
+
+### What the review saw (pins)
+
+`review add` reads the corpus and records `pins` on the review; the
+reviewer never types them:
+
+- `scenario_digest` — the scenario record's `scenario_digest`: a sha256
+  over that scenario alone, as `canon inventory sync` stores it. It
+  covers the scenario's tags and block (header, steps, doc strings,
+  tables, `Examples:`) and the context it inherits: the Feature's tags,
+  the Feature `Background:`, and an enclosing `Rule:` with its tags and
+  `Background:`. Layout does not count: comments, blank lines, line
+  indentation, tag order, and table alignment (cells are compared
+  trimmed and unescaped). Values do: any step, tag or cell change, and
+  whitespace inside a doc string after the delimiter's own indentation
+  is removed. Other scenarios never count. A record synced before 0.15 has no
+  `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
+scenario with no record (never synced) is refused with exit 2 and nothing
+is written: there is nothing to pin.
+
+The gate compares each pin like for like: a scenario pin with the
+scenario's current `scenario_digest`, a file pin with its current
+`source_digest`. Adding or editing another scenario in the file leaves a
+scenario-pinned review current; editing this scenario, or a Background
+or Rule it inherits, makes it stale. A file-pinned review stays a file
+pin until it is reviewed again. Review after the spec and evidence are
+final.
+
+### The reviewer's outcome and runtime
+
+`--outcome` records how the reviewer's run ended: `signed` (the default:
+an approval), `indeterminate` (it ran and reached no verdict) or
+`unavailable` (it could not run). Only `signed` counts; the other two
+are recorded so a failed review is visible, never mistaken for a
+sign-off or a rejection, and `review add` says so. `--reviewer-provider`,
+`--reviewer-model` and `--reviewer-harness` record the runtime that
+produced the review, as given. An empty or padded label is a usage error.
+
+`--session-id` (on `evidence add`, `review add`, `finding add` and
+`finding close`) takes one opaque token: non-empty, no surrounding
+whitespace, no control characters. Anything else is a usage error
+(exit 2) and nothing is written.
 
 ## The `require_review` policy (opt-in)
 
@@ -129,8 +214,11 @@ spec_coverage:
   scenarios from review.
 - **`distinct_actor`** — a review only counts when both its `reviewer`
   and its actor (`--actor-id`) differ from every actor on that
-  scenario's evidence records. An agent cannot review its own attested
-  work.
+  scenario's evidence records, and, when the review carries a session,
+  that session differs from every session on those evidence records. An
+  agent cannot review its own attested work, under another id or from
+  the same session. A record with no session never matches one, so
+  records written before sessions were recorded count by actor alone.
 - **`block_on_findings`** — fail on open blocker findings (below).
 
 A malformed `require_review` (an unknown key, an unknown status, `null`,
@@ -138,13 +226,46 @@ a non-mapping) poisons the whole `spec_coverage` section: `canon gate
 check` reports it invalid rather than treating it as off, the same as a
 malformed `require_cases`.
 
-Canon's own `.canon/policy.yaml` does not enable `require_review`.
+Canon's own `.canon/policy.yaml` enables `require_review: {}`, and so does
+the starter policy `canon init` writes.
 
 ## How it meets the gate
 
+### Which review counts
+
+The reviews of a scenario are folded to the **latest per `reviewer`**
+first (by `at`, then schema, then content digest — the fold every reader
+uses). A reviewer's later review replaces their earlier one: a reviewer
+who signed and later recorded `indeterminate` no longer counts as
+signing, and a later `signed` review counts again. Reviews by different
+reviewers never replace each other.
+
+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;
+3. passes `distinct_actor`, when that is on.
+
+A review written before 0.15 has no pins. It keeps counting under rules
+1 and 3, without the freshness check, and `canon gate check` prints one
+advisory line counting such in-effect reviews (exit code unchanged):
+
+```
+advisory: 340 review(s) predate review pinning (0.15) and still count without a check that their scenario's spec and evidence are unchanged; a new `canon review add` pins what it saw
+```
+
+`canon status` prints the same line as a warning, and `canon subject
+status` prints it on stderr for the subject's own scenarios. Reviewing
+the scenario again pins it and drops it from the count.
+
 ### `unreviewed-promotion`
 
-An in-scope scenario with no qualifying review:
+An in-scope scenario with no qualifying review. When several latest
+reviews fail for different reasons, the detail names the one closest to
+counting: a current signed review failing only `distinct_actor`, then a
+stale review, then non-signed outcomes.
 
 ```
 unreviewed-promotion world.demo.01 — no review record for this scenario; spec_coverage.require_review wants an independent review (`canon review add`) once its subject is claimed done
@@ -156,6 +277,29 @@ or, when the only reviews are self-reviews:
 unreviewed-promotion world.demo.01 — every review of this scenario is by an actor that also attested its evidence (`impl-agent`); spec_coverage.require_review.distinct_actor wants a reviewer other than the evidence actor
 ```
 
+or, when another actor id reviewed from a session that attested the
+evidence:
+
+```
+unreviewed-promotion world.demo.01 — every review of this scenario is by an actor that also attested its evidence (`impl-agent`) or from a session that did (`sess-impl`); spec_coverage.require_review.distinct_actor wants a reviewer other than the evidence actor, in a session other than any evidence session
+```
+
+or, when the scenario's spec, its evidence, or both changed after the
+review (`its spec changed`, `its evidence changed`, `its spec and its
+evidence changed`):
+
+```
+unreviewed-promotion world.demo.01 — stale review by `reviewer-2`: its evidence changed (the latest evidence records are not the pinned ones) since the review; a pinned review counts only while what it saw is current — review it again (`canon review add`)
+```
+
+or, when every latest review recorded no sign-off:
+
+```
+unreviewed-promotion world.demo.01 — no signed review: the latest review recorded no sign-off (`reviewer-2` indeterminate); an indeterminate or unavailable review is a gap, never an approval — run the review again and record `--outcome signed`
+```
+
+A non-signed review is a gap even without `distinct_actor`.
+
 ### `open-blocker`
 
 With `block_on_findings`, a Finding whose latest version is severity
@@ -188,7 +332,7 @@ prints on stderr which review checks it ran or skipped:
 
 ```
 canon subject status: review guard for building → verifying (spec_coverage.require_review, scope: verifying, shipped)
-  ran unreviewed-promotion — every owned scenario needs a review by an actor other than its evidence actor
+  ran unreviewed-promotion — every owned scenario needs a signed review, current with the spec and evidence it pinned, by an actor, and from a session, other than its evidence's
   ran open-blocker — 1 adopted change(s) checked for open blocker findings
 ```
 

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

@@ -146,7 +146,10 @@ query:
 ```
 
 Every query, export, and purge appends an actor-stamped record to
-`.canon/audit/access.jsonl` (mode `0600` on creation). `CANON_ACTOR` takes
+`.canon/audit/access.jsonl` (mode `0600` on creation) in the repository
+whose `canon.yaml` it read (through `--repo` or `--canon-yaml`), never in
+the current directory; with no `canon.yaml` there is no audit and nothing
+is written. `CANON_ACTOR` takes
 precedence over the OS username. Audit rows contain operation, kind, scope,
 sensitive flag, counts, and timestamp only—never query text, secrets, or
 record bodies.

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

@@ -135,7 +135,8 @@ what brings a scenario into that scope. See `canon-gate`.
 requires that the Subject OWNS at least one scenario (one whose latest
 synced generation carries `@subject:<id>`), and that EVERY owned
 scenario carries a latest, non-`Divergent` verdict in the ledger (the
-same last-wins rule `canon gate check` uses). With
+same last-wins rule `canon gate check` uses; a record keyed by both a
+task and the scenario counts for the scenario). With
 `spec_coverage.require_cases` set, every feature surface the Subject
 owns must also carry a scenario of each required `@case:` (e.g. one
 `@case:failure`) — attested golden-path scenarios alone do not ship. A
@@ -152,7 +153,7 @@ prints on stderr which it ran or skipped:
 
 ```
 canon subject status: review guard for building → verifying (spec_coverage.require_review, scope: verifying, shipped)
-  ran unreviewed-promotion — every owned scenario needs a review by an actor other than its evidence actor
+  ran unreviewed-promotion — every owned scenario needs a review by an actor, and from a session, other than its evidence's
   ran open-blocker — 1 adopted change(s) checked for open blocker findings
 ```
 
@@ -161,7 +162,10 @@ unreviewed-promotion — `specced` is not in require_review.scope`. A
 transition INTO an in-scope status with gaps — an owned scenario with no
 qualifying review (`unreviewed-promotion`), or an open blocker finding
 on an adopted change (`open-blocker`) — prints the violations, exits 1,
-leaves the record unchanged, and names `--override-reason`.
+leaves the record unchanged, and names `--override-reason`. `shipped`
+also refuses a `false-success` (a scenario whose latest audit is
+`refuted`) and, when `require_audit.scope` covers `shipped`, an owed
+sampled audit; see `canon-gate`.
 
 ```bash
 canon subject status demo-subject verifying \
@@ -204,7 +208,156 @@ canon subject adopt subject-domain-loop-plan \
 
 `adopt` stamps the change's `subject_id` and adds it to the Subject's
 `change_ids`, so `canon query --kind change --change-id …` and `canon
-query --kind subject` agree on the link from both ends.
+query --kind subject` agree on the link from both ends. It writes only
+the side that lacks the link, so rerunning it on a linked pair writes
+nothing and exits `0`.
+
+The two records cannot be written atomically, so the subject is written
+first: its `change_ids` is what the gate reads a subject's adopted
+changes from (`open-blocker`, the status guard), so a half-done adoption
+still has that change's open blockers counted. If the change write then
+fails, `adopt` exits `2`, names the subject that now lists the change,
+and prints `canon subject adopt <change_id> --subject <id>` to complete
+it.
+
+### Starting a new change: `canon change new`
+
+For a change that does not exist yet, one command scaffolds it and
+records it adopted:
+
+```bash
+canon change new add-login --subject auth --title "Add login"
+```
+
+- **Writes** `openspec/changes/<slug>/proposal.md` (the title is its
+  `## Why`, which imports as the change summary) and `tasks.md` (no rows
+  yet, so the change imports as `proposed`), under the repo's first
+  `openspec` plans source. `canon init` configures that source
+  (`{dialect: openspec, root: .}`), so `canon.yaml` needs no edit.
+- **Reads** the files with the same `openspec` adapter `canon ingest
+  plans` uses, then **records** the change already adopted, through the
+  same write as `canon subject adopt`.
+- **What a failure leaves behind.** The files are staged under `.canon/`
+  and the change dir is moved into place only once they parse. A failure
+  before any record is written (staging, publishing the dir, or the
+  first record write) removes the change dir, the staged files and any
+  directory created for them: nothing is left behind. The two records
+  cannot be written atomically. If the change record fails after the
+  subject record was written, the command exits `2`, keeps the change
+  dir and that one subject record, and prints the repair, `canon ingest
+  plans && canon subject adopt <slug> --subject <id>`, which completes
+  the link and is safe to rerun.
+- **Refuses** with exit `2`, writing nothing, when the subject does not
+  exist, when the slug already has a change dir (active or archived) or a
+  `change` record, or when `canon.yaml` has no `openspec` plans source.
+
+Add task rows to `tasks.md` as `- [ ] <n> <title>`, rerun `canon ingest
+plans`, and flip each with `canon gate task <slug>#<n>` once evidence
+exists.
+
+## Where are we: `canon status`
+
+```bash
+canon status                 # subjects by status, their gaps, next commands
+canon status --json          # the same report, stable shape
+canon status --repo ../other
+```
+
+A read: it always exits 0 and writes nothing (no ledger record, no
+`.canon/audit` line). Every count comes from the joins the gate itself
+uses, so status and the gate cannot disagree about a gap:
+
+- **Header** — the canon version, and the policy in force:
+  `spec_coverage` (with `scope`/`exclude_lanes`), `require_cases` and
+  `require_review`. When `.canon/policy.yaml` is absent, unreadable, has
+  no `spec_coverage` section, or has an invalid one, a `warning:` line
+  says the gate requires no evidence, failure cases or review (or refuses
+  until it is fixed).
+- **Subjects grouped by status** (lifecycle order). Per subject:
+  scenarios it owns through `@subject:` (after `exclude_lanes`, which
+  are counted separately), how many carry a ledger verdict (the
+  `verifying → shipped` gate's reading; divergent ones are counted too),
+  how many carry a review that satisfies `require_review` (any current
+  signed review when it is off; with `distinct_actor`, a self-review does
+  not count), open blocker findings on its adopted changes, and each
+  feature surface missing a `require_cases` case. `(N due)` marks reviews
+  the next transition will require; `N stale review(s)` and `N unsigned
+  review(s)` (printed when non-zero) count scenarios whose review went
+  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).
+- **Unowned** — scenarios with no `@subject:` tag.
+- **Audits** — how many scenarios are sampled for
+  `spec_coverage.require_audit`, confirmed, owed (no audit or
+  `indeterminate`) and refuted (`false-success`). An owed or
+  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`.
+- **`next:`** — at most five commands, each with a one-line reason; the
+  rest are counted. Rules, in order: no `canon.yaml` → `canon init`; an
+  unreadable one → `canon init --check-config`; a scenario tagged with a
+  subject that has no record → `canon subject new <that id>`; no subject
+  at all → `canon subject new`; subjects but no scenario records →
+  `canon inventory sync`. Then per subject, verifying first, then
+  building, specced, proposed, shipped: no scenario → `canon scenario new
+  … --subject <id>`; a missing case → `canon scenario new <surface>.<next
+  nn> … --case <case>`; (building and later) an unevidenced or divergent
+  scenario → `canon evidence add --scenario-id …`; an open blocker →
+  `canon finding close …`; a due, unreviewed, evidenced scenario →
+  `canon review add …` from another session; none of these →
+  `canon subject status <id> <next status>`. Last, unowned scenarios →
+  tag them and `canon inventory sync`. With more 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.
+
+Status fails closed rather than suggest progress the gate would refuse:
+
+- When `scenario`, `subject`, `review` or `finding` routes away from the
+  `local` rung (the only rung status and the gate read), its records
+  would read as empty. The only `next:` step is
+  `canon init --check-config`, with the reason naming the
+  `routing.<kind>: local` setting to restore.
+- When `spec_coverage` is present but unusable, `canon gate check`
+  refuses. The first `next:` step is `canon gate check`, with the reason
+  naming the section to fix, and no subject is suggested to move to its
+  next status until it parses.
+
+`--json` prints one object:
+
+```json
+{
+  "statusVersion": 1,
+  "canonVersion": "0.14.0",
+  "policy": { "present": true, "spec_coverage": { "require_evidence": true, "scope": [], "exclude_lanes": [], "require_cases": ["failure"], "require_review": { "scope": ["verifying", "shipped"], "distinct_actor": true, "block_on_findings": true } } },
+  "warnings": [],
+  "subjects": [
+    { "id": "cart", "title": "Cart", "status": "building", "scenarios": 2, "excluded": 0, "evidenced": 2, "divergent": 0,
+      "reviewed": 1, "staleReviews": 0, "unsignedReviews": 0, "reviewDue": true, "openBlockers": 1, "missingCases": [] }
+  ],
+  "unowned": ["cart.promo.01"],
+  "next": [
+    { "command": "canon finding close --change-id c-cart --round 1 --seq 1 --disposition fixed --resolution-sha <sha> --actor-id <unit> --session-id <session>", "why": "cart: 1 open blocker finding(s) (first: …); fix it, commit, then close it" },
+    { "command": "canon review add --project-id root --scenario-id cart.add.02 --reviewer <reviewer> --actor-id <reviewer> --session-id <review-session> --role reviewer --pin <sha> --original-spec-ref \"<feature file>\"", "why": "cart: 1 of 2 scenario(s) lack a qualifying review; …" },
+    { "command": "canon inventory sync", "why": "1 scenario(s) carry no @subject tag (first: cart.promo.01); …" }
+  ],
+  "nextOmitted": 0
+}
+```
+
+Each `missingCases` entry is `{ "projectId", "surface", "case" }`: the
+spec root, the `<area>.<surface>`, and the required case it lacks.
+
+`policy.spec_coverage` has the shape `canon context --json` prints
+(`null` when absent, `{"invalid": …}` when unusable). `statusVersion`
+changes only when a field changes meaning or is removed.
+
+`subject new`, `adopt` and `status` write their records directly; the
+human-readable success line ends `— written directly; nothing to
+promote` (`--json` prints the record and nothing else).
 
 ## Reading the per-domain management view
 

package/package.json

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