@journeykit/canon 0.14.0 → 0.16.0

package/dist/skills/SKILL.src.md

@@ -13,60 +13,122 @@ where each subject stands and lists the next commands.
 ## 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; never edit it to make
-  the gate pass.
-
-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
+a feature, a one-line request included. A human is needed once per scope:
+
+- **The approval** (step 1). A new subject, or a change to an approved
+  subject's scope, needs the human to approve its brief: the request, your
+  assumptions, your open questions. Write the brief, then stop and report
+  it: build nothing for that scope (no scenarios, code or evidence) before
+  the human answers. The approval is the one thing you never assume, even
+  when the human said they cannot answer until you report: the brief is
+  that report. In the same answer the human approves the policy,
+  `.canon/policy.yaml` (written by `canon init`), which is what the gate
+  grades the work against. When the human answers, record both at once:
+  an `Approved: <who> <when> — "<the human's words>"` line in the change's
+  `proposal.md`, and
+  `canon policy approve --by <the human> --note "<their words>"`. Never
+  approve without a human answer, and never edit the policy to make the
+  gate pass.
+- **Inside an approved scope, never stop for a human.** Fixes, follow-ups,
+  review rounds and re-reviews go straight on: add or extend the scenario,
+  implement, gather evidence, and get an independent review in another
+  session. Independent review happens on every change. A fix or follow-up
+  stays in the approved change: add it as tasks in that change's
+  `tasks.md`, never with `canon change new`, because a new change is a new
+  scope and needs the human's approval.
+
+When no human can answer one of the brief's questions, write the question
+into the brief, state the assumption you will build on, and say so in your
+report. Proceeding on an assumption applies to the brief's questions and to
+work inside an approved scope, never to the approval itself.
+
+1. **Brief.** For a new subject or a scope change, 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.
+   subject exists (step 2). Once it is there, stop and report the brief,
+   asking the human once for the brief and the policy; go on to step 3
+   only after the human answers, and record the answer as above. Inside an
+   approved scope there is no new brief: go to step 3 under the existing
+   subject and change.
 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`.
+   the change's `proposal.md`. For a new subject or a scope change, this is
+   where you stop until the human answers (step 1).
 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`.
+   a new scenario; never retag an existing one to satisfy it. There is no
+   sync or format step: `canon status`, `canon gate check`,
+   `canon evidence add`, `canon review add` and `canon subject status`
+   index added, edited or deleted `.feature` files themselves. Only when
+   one of them prints `NOT refreshed` (a format violation, such as a
+   hand-written header with no `# canon:` provenance comment, or a
+   duplicate id) run `canon inventory sync`: it names each problem; fix
+   them, and the next command indexes the files.
 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.
+   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`.
+   ledger) and `canon gate check` re-checks them. For a scenario about what
+   users see, bind the screenshot or recording that shows it
+   (`--artifact <path>`). Under `write: { promote: auto }` (what
+   `canon init` writes) the record is final when the command returns; only
+   in a repo with `write.promote: manual` (or no `write:` key) follow it
+   with `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. Both read the
+   change's `tasks.md` as it is now, so a task row you add needs no
+   `canon ingest plans` first.
 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:
-   `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,
+   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 "…"`;
+   once fixed,
    `canon finding close --change-id <slug> --round <n> --seq <n> --disposition fixed --resolution-sha <sha>`
-   and `canon gate promote`. Every bug fix adds or extends a scenario. The
+   (a short sha is fine; canon resolves it). With `write.promote: manual`,
+   follow each with `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).
+   (written directly; nothing to promote). A reviewer of user-visible
+   behavior attaches what it looked at with `--artifact <path>`
+   (repeatable); canon stores and re-checks those bytes and never compares
+   images.
 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.
+   `canon gate check` clean. A root whose `.feature` edits could not be
+   indexed fails the gate and refuses `shipped` (`uncovered-cell <root>`;
+   see step 3). `shipped` also refuses while the change's `proposal.md`
+   has no `Approved:` line, and `canon evidence add` refuses the subject's
+   scenarios and tasks the same way. Both are backstops: the stop itself
+   is at step 1, so you never reach them for a brief the human has not
+   answered. You record the line only from the human's answer (with no
+   `proposal.md` there is no brief to answer: neither refuses, and the
+   ship guard only prints an advisory). Move the subject to
+   `shipped` yourself once `canon subject status <id> shipped` passes its
+   guard, unless the brief says the human ships. `canon status` shows
+   whether each subject's brief is approved, by the same check, and names
+   the next step.
+
+Every write command says whether the record is final (`written directly`,
+or `staged and promoted in this run`) or staged; only a staged record
+needs `canon gate promote`, and only `write.promote: manual` leaves one.
 
 ## Command reference
 
@@ -75,7 +137,7 @@ Load only the reference the current step needs.
 ### Setup and provider projection
 
 ```bash
-canon init                                   # canon.yaml, starter policy, AGENTS.md block, plans home
+canon init                                   # canon.yaml, starter policy (--policy light|standard|strict, default strict; see canon-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

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

@@ -85,7 +85,7 @@ enum, like `lane`.
 
 Every scenario belongs to a Subject (the durable product unit, see
 `canon-subject`). Write the Subject first, then pin with `--subject`;
-`canon inventory sync` carries the tag onto the index record and
+the scenario index carries the tag onto the index record and
 `spec_coverage.scope` filters on it. An unpinned scenario is invisible to
 a scoped gate.
 
@@ -97,10 +97,17 @@ canon scenario new checkout.cart.01 --title "Adding an item raises the count" \
   --subject checkout-core --lane behavior --case happy               # once per behavior
 canon scenario new checkout.cart.04 --title "Adding an out-of-stock item is refused" \
   --subject checkout-core --lane behavior --case failure             # and its failure path
-canon format specs                                                   # clean?
-canon inventory sync                                                 # index it
 ```
 
+There is no format or sync step after these: the scaffold writes a
+format-clean scenario, and `canon status`, `canon gate check`,
+`canon evidence add`, `canon review add` and `canon subject status`
+index added, edited and deleted `.feature` files before they read. When
+one of them prints `NOT refreshed`, the corpus has a format violation
+(for example a hand-written header with no `# canon:` line) or a
+duplicate id; `canon inventory sync` (or `canon format specs`) names it.
+Fix it and the next command indexes the files (see `canon-inventory`).
+
 - `--actor <id>` (or `CANON_ACTOR` in the environment) puts YOUR id on the
   provenance line. Default is `canon-scaffold`.
 - **Never hand-type, move, or edit a `# canon:` line.** The scaffold

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

@@ -15,21 +15,22 @@ 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). |
+| `stale-evidence` | A passing record degraded to stale: its declared surface changed since its `evidence_sha`, or HEAD moved past `staleness.max_commits_behind`. Only degrades an already-green record. Also: a file bound to a latest evidence record whose bytes are gone — no intact blob in `.canon/artifacts/sha256/` and no working-tree copy with the recorded digest — or a file bound to an in-effect review with no intact blob (see Bound evidence stays provable below). |
 | `malformed-evidence` | A candidate record doesn't parse, is misfiled, or carries an unparseable interim tag. Malformed evidence is no evidence. |
 | `flagged` | The human-only `flagged` overlay is set — never green regardless of passing evidence. |
 | `unevidenced-flip` | `canon gate task <task_id>` was asked to flip a checkbox with no matching, non-`Divergent` evidence record. |
 | `fabricated-evidence` | An evidence note contains a blocklisted marker (`"would pass"`, `"TBD"`, `"n/a"`) 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,32 @@ 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`).
+
+Before it reads the scenario index, the gate rebuilds any stale part of
+it from the changed `.feature` files (the same code `canon inventory
+sync` runs) and says so in one stderr line, silent when the index is
+fresh:
+
+```
+canon gate check: refreshed the scenario index from 1 changed feature file(s) (specs/features/kind=feature/area=cart/add.feature): 1 record(s) written
+```
+
+A root that fails to sync (format violations, a duplicate id) is named
+instead, ending ``NOT refreshed: root `x` (N format violation(s), 0 sync
+error(s)) — `canon inventory sync` lists them``, and the gate fails
+closed: it adds `uncovered-cell <root> — the scenario index for spec root
+`<root>` is stale and could not be refreshed (…); `canon inventory sync`
+lists the problems to fix` and exits 1, since the index it would grade
+does not hold the edits. The `verifying → shipped` guard refuses with
+the same violation, and `canon status` lists the sync as its only step.
+Fix what the sync lists and run the gate again. See `canon-storage`
+(The scenario index).
+
 ### The spec-derived worklist (`spec_coverage`, opt-in)
 
 Coverage groups the EVIDENCE corpus, so it can only ever enumerate
@@ -111,14 +138,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 +160,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 +191,96 @@ 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`).
+
+### Nothing is attested before the brief is approved (`--override-reason`)
+
+The approval is never assumed: the agent writes the brief, stops and
+reports it, and builds nothing for that scope until the human answers.
+`canon evidence add` is the backstop for that stop (0.16 M7). It
+refuses (exit `1`, nothing staged or stored) while a subject the record
+attests for has an enforced, unapproved brief: the newest adopted
+change has a `proposal.md` under the openspec plan sources with no
+`Approved:` line (the check `canon status` and the ship guard use; see
+`canon-subject`). The subjects are the scenario's `@subject` owner for
+`--scenario-id`, and every subject adopting the task's change for
+`--task`:
+
+```
+canon evidence add: unreviewed-promotion demo-subject — evidence for world.demo.01: brief not approved — openspec/changes/c-demo/proposal.md has no `Approved:` line, so the human has not answered it
+canon evidence add: refused — stop, report the brief to the human and wait for their answer: nothing is built or attested for a subject before its brief is approved. Record their words as `Approved: <who> <when> — "<their words>"` in that proposal.md only from that answer; to attest anyway, pass --override-reason <text>, which is recorded on the evidence record
+```
+
+A subject with no brief to answer (no openspec source, no adopted change,
+no `proposal.md`) and a scenario no subject owns are unaffected.
+`canon review add` and `canon finding add` are never refused.
+`--override-reason "<one line>"` attests anyway, prints the `waived …`
+lines and `override recorded by `<actor>` for the N brief refusal(s)
+above: <reason>`, and records on the evidence record:
+
+```yaml
+brief_override:
+  reason: the human approved in chat; the line follows
+  waived:
+    - { class: unreviewed-promotion, subject: demo-subject }
+  actor: { agent_id: lead }   # from --actor-id
+```
+
+A blank or multi-line reason exits 2; an override when nothing refused is
+not recorded. `canon status` lists each such record as a `warning:`, and
+`canon gate check` prints them after the result without failing:
+
+```
+brief overrides: 1 evidence record(s) attested before their brief was approved — not failing the gate:
+  evidence for world.demo.01 was attested by `lead` at 2026-10-12T07:00:00Z while the brief of demo-subject was not approved (override: the human approved in chat; the line follows)
+```
+
 ### Review-waiver advisories
 
 A subject moved into a review-scoped status with `canon subject status
@@ -160,6 +297,58 @@ review waivers: 1 advisory(ies) — not failing the gate:
 
 The waiver lasts only until the subject's next status write.
 
+`canon subject status <id> shipped` also refuses where a brief exists and
+has no `Approved:` line (the subject's newest adopted change has a
+`proposal.md`; see `canon-subject`), as an `unreviewed-promotion` naming
+the subject. With no brief to answer it prints an advisory and does not
+refuse. Like the evidence refusal above, it is a backstop: the stop is at
+the brief. `canon gate check` does not grade briefs, so a waived ship
+brief prints no advisory here; `canon status` keeps showing the brief as
+not approved.
+
+### Reviews that predate pinning (checked against their pin)
+
+With `require_review` on, the reviews in effect (latest per reviewer and
+scenario) that carry no pins were written before 0.15. Each still names
+`pin`, the commit it reviewed, and the gate checks it there (0.16):
+
+- **current** — the scenario's digest at that commit (read with `git`,
+  normalized exactly as `canon inventory sync` computes
+  `scenario_digest`) equals its current digest, and no declared evidence
+  record of the scenario is newer than the review. It counts. When the
+  scenario lived in another `.feature` file at that commit, the spec
+  root's files at that commit are searched for its id.
+- **stale** — the scenario changed since the commit, or it has newer
+  evidence. It no longer counts, and an in-scope scenario left with no
+  other qualifying review is `unreviewed-promotion`:
+
+  ```
+  unreviewed-promotion gate.check.15 — stale review by `canon-reviewer-g1` (written before review pinning; checked against commit b556ab7529a332aa0b28d0a0f98bdd62fcbb9a63): it has declared evidence newer than the review; a review counts only while what it saw is current — review it again (`canon review add`)
+  ```
+
+  A spec change reads `its spec changed since <pin> (the scenario's
+  digest at that commit is not its current one)`.
+- **undecidable** — the pin is not a commit in this clone (a shallow
+  clone, rewritten history), or no feature file of the scenario's root
+  holds its id at that commit. It keeps counting, as in 0.15: a missing
+  commit never becomes a violation.
+
+One advisory line after the violations counts the three. A stale one
+whose scenario already has another qualifying review (current, signed,
+distinct) is counted as superseded, since nothing is owed for it; only
+the scenarios a stale one leaves without a qualifying review are named
+for re-review. The exit code is unchanged by the line itself:
+
+```
+advisory: 338 review(s) predate review pinning (0.15) and were checked against the commit each one pinned: 318 current, 12 stale, 8 undecidable; 7 stale one(s) superseded by a current review of the same scenario, so nothing is owed for them; a stale one with no current review in its place no longer counts — review its scenario again (`canon review add`): platformer.movement.01, platformer.movement.02, …; an undecidable one still counts unchecked, because its pinned commit or the scenario at it is not in this clone — check out full history (`fetch-depth: 0` in CI) to check it
+```
+
+A review of a scenario no feature file declares any more is not counted.
+In CI, check out full history (`actions/checkout` with `fetch-depth: 0`)
+for the job that runs `canon gate check`, or every legacy review is
+undecidable. Each pinned commit is read once per run through one `git
+cat-file --batch` process, and never fetched over the network.
+
 ## Experimental: evidence binding (`experimental.evidence_binding`, off by default)
 
 An evidence record is an attestation: canon never runs `--ref`, and it
@@ -252,6 +441,15 @@ 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.
 
+Files bound to a review (`canon review add --artifact`, see
+`canon-review`) are checked the same way for every in-effect review (the
+latest per `(project_id, scenario_id, reviewer)`), with one difference:
+they were stored when the review was written, so only an intact blob is
+clean. A missing or altered blob is `stale-evidence` on the review's
+scenario, and the detail names the review: ``review by `<reviewer>`
+(actor `<id>`, <time>)``. The working-tree file is reported but never
+vouches for it.
+
 `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,
@@ -313,6 +511,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 .
 ```
@@ -337,13 +543,26 @@ 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
+close` stage, and under `write: { promote: manual }` (or an absent
+`write:` key) their success line ends ``— run `canon gate promote` to
+commit it``. Under `write: { promote: auto }` (what `canon init` writes)
+or with `--promote`, they promote the one record they just staged —
+same validation and `run_seq` assignment as this command — and print
+one success line naming the committed record (`wrote kind=…/….json`), not
+the staged file, ending `— staged and promoted in this run; nothing to
+promote`, so no separate
+`canon gate promote` is needed for it; `--no-promote` keeps one write
+staged. A record another run staged is not touched: only `gate promote`
+commits everything staged. It stays safe to run anyway: with nothing
+staged it prints
+`nothing staged` and exits `0`. `divergence stage` stages for `canon
+divergence promote` and names it, under the same `write:` rule. Every
+other write — `review add`, `divergence
 resolve|defer`, `subject new|adopt|status`, `change new`, `scenario new`, `feature new`,
 `gate 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`.
+directly; nothing to promote`. Full promote-on-write contract:
+`canon-storage` (Staged writes and promotion).
 
 ## `canon gate install-hooks [--repo] [--event] [--matcher] [--command] [--timeout]`
 
@@ -367,8 +586,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-inventory.md

@@ -1,16 +1,43 @@
 # canon-inventory
 
-`canon inventory sync` is the FIRST stage of canon's unified spec loop:
-it turns a hand-authored, `canon format`-validated `.feature` corpus into
-the scenario ledger-INDEX records every downstream stage joins against.
+`canon inventory sync` builds canon's scenario ledger-INDEX: it turns a
+hand-authored, `canon format`-validated `.feature` corpus into the scenario
+records every downstream stage joins against.
 
-## The unified loop
+## You rarely run it yourself
+
+Since 0.16 the commands that read the index refresh it first:
+`canon status`, `canon gate check`, `canon evidence add`,
+`canon review add` and `canon subject status` index added, edited and
+deleted `.feature` files themselves, with the same code this command runs,
+scoped to the changed files, and say so in one stderr line:
+
+```
+canon status: refreshed the scenario index from 1 changed feature file(s) (specs/features/…): 1 record(s) written
+```
+
+So the working loop has no sync step and no `canon format` step: write the
+scenario (`canon scenario new` writes it format-clean) and run the next
+command. Run `canon inventory sync` when:
+
+- a reader prints `NOT refreshed` — a root has a format violation (a
+  hand-written `Feature:`/`Scenario:` header with no `# canon:` provenance
+  comment, an emptied file, …) or a duplicate id, so its files were not
+  indexed. `canon gate check` then fails (`uncovered-cell <root>`),
+  `shipped` is refused and `canon status` lists only the sync. `canon
+  inventory sync` names each problem (`canon format specs` names the format ones);
+  fix them and the next command indexes the files;
+- `canon status` says the ledger holds no scenario records while the
+  `.feature` files hold some (the same refusal, on an index never built);
+- you want the whole index rebuilt from every root at once.
+
+## Where the index sits in the loop
 
 ```
-author .feature corpus  →  canon format --check (validate)
+author .feature corpus (canon scenario new)
         │
         ▼
-canon inventory sync            # THIS skill — materializes scenario index records
+scenario index                  # refreshed by every reader; `canon inventory sync` rebuilds it
         │
         ▼
 canon review add                # attests a review — see canon-inventory downstream / canon-gate
@@ -23,8 +50,8 @@ canon ingest artifacts          # with artifacts.native_records: true in canon.y
                                 # (see canon-artifact-ingest)
 ```
 
-Every stage after `sync` joins on the SAME `(project_id, scenario_id)`
-pair `sync` materializes — one identity scheme, no second one.
+Every stage after the index joins on the SAME `(project_id, scenario_id)`
+pair it materializes — one identity scheme, no second one.
 
 ## `canon inventory sync [--repo <dir>] [--spec-root <dir>]`