@journeykit/canon 0.14.0 → 0.15.0

package/dist/skills/SKILL.src.md

@@ -17,8 +17,9 @@ 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; never edit it to make
-  the gate pass.
+  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.
@@ -43,18 +44,27 @@ assumption you state there, and say so in your final report.
    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.
+   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. Record every defect as a finding,
-   including the ones the author found and fixed during implementation:
+   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>`

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

@@ -15,14 +15,14 @@ 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. 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. |
@@ -30,6 +30,7 @@ Every violation carries one of these stable, grep-able strings:
 | `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]`
 
@@ -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
@@ -111,14 +118,18 @@ A present section, even `require_evidence: false` or a malformed one
 - **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, and from a session other than any evidence
-  session when both carry one (`--session-id`), 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:
@@ -129,12 +140,28 @@ A present section, even `require_evidence: false` or a malformed one
       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
@@ -144,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
@@ -160,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
@@ -313,6 +399,14 @@ 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 .
 ```
@@ -367,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-policy.md

@@ -37,10 +37,56 @@ spec_coverage:
 
 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. 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`).
+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
 
@@ -124,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

@@ -34,7 +34,8 @@ The order an agent follows to claim a subject done:
    ```
 
 3. **One Review per scenario**, by someone other than the evidence actor,
-   from a session other than the one that attested the evidence:
+   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 \
@@ -43,7 +44,11 @@ The order an agent follows to claim a subject done:
      --pin "$(git rev-parse HEAD)" --upstream-ref "pr#41"
    ```
 
-   `review add` writes directly; there is nothing to 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`.
@@ -73,14 +78,24 @@ 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, with `--reviewer` and `--actor-id` set
-to the author's own id. 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`.
+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
 
@@ -113,19 +128,66 @@ 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>] [--session-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`; `--session-id` fills `actor.session_id`.
-A Review carries no verdict; 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
+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
@@ -169,9 +231,41 @@ 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
@@ -190,6 +284,22 @@ 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
@@ -222,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, and from a session, other than its evidence's
+  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

@@ -162,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 \
@@ -274,12 +277,25 @@ uses, so status and the gate cannot disagree about a gap:
   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 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.
+  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
@@ -320,7 +336,7 @@ Status fails closed rather than suggest progress the gate would refuse:
   "warnings": [],
   "subjects": [
     { "id": "cart", "title": "Cart", "status": "building", "scenarios": 2, "excluded": 0, "evidenced": 2, "divergent": 0,
-      "reviewed": 1, "reviewDue": true, "openBlockers": 1, "missingCases": [] }
+      "reviewed": 1, "staleReviews": 0, "unsignedReviews": 0, "reviewDue": true, "openBlockers": 1, "missingCases": [] }
   ],
   "unowned": ["cart.promo.01"],
   "next": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@journeykit/canon",
-  "version": "0.14.0",
+  "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.14.0",
-    "@journeykit/canon-core-linux-x64": "0.14.0",
-    "@journeykit/canon-core-win32-x64": "0.14.0"
+    "@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",