@journeykit/canon 0.14.0 → 0.16.0

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

@@ -26,21 +26,94 @@ 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):
+`--no-policy`; an existing file is never overwritten). `--policy
+light|standard|strict` picks how much it asks for; the default is
+`strict`:
+
+| Level | `spec_coverage` |
+|---|---|
+| `light` | `require_evidence: true` — every scenario needs evidence |
+| `standard` | light, plus `require_cases: [failure]` — every feature surface needs a `@case:failure` scenario |
+| `strict` | standard, plus `require_review: {}` — verifying/shipped subjects need an independent review |
 
 ```yaml
+# canon policy level: strict
 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. 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`).
+The first line names the level. The file carries comments explaining
+each field, and a `light` or `standard` starter carries the next levels'
+keys as commented lines: to raise the level, uncomment them and change
+the level line, and a human approves the edit (next section). An
+unknown `--policy` value exits 2, and so does `--policy` with `--no-policy`.
+
+`canon status` prints the level under the policy settings
+(`level: strict`, or `level: light — raise it by …` with how to raise
+it) and in `--json` as `policy.level`. It reads the level line when the
+file's leading comment block has one naming a known level; otherwise it
+infers the level from the `spec_coverage` section, which must match a
+level exactly (no `scope`, `exclude_lanes`, `require_audit`, or
+non-default `require_review` settings); anything else is `custom`.
+`policy.level` is `null` when there is no policy.
+
+Every level loads with zero diagnostics. The policy 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 approves the policy after reviewing `.canon/policy.yaml`, in the
+same answer that approves a subject's brief (0.16; see the skill's working
+loop). The human runs this, or the agent runs it right after that answer
+as `canon policy approve --by <the human> --note "<their words>"`. 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 runs `canon policy approve` only to record a
+human's answer, never without one and never on its own behalf.
 
 ## The closed CEL profile
 
@@ -124,6 +197,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,8 +17,10 @@ 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> ... --session-id <session>`,
-   then `canon gate promote`). See `canon-gate`.
+   --scenario-id <id> --project-id <root-id> ... --session-id <session>`;
+   final when it returns under `write: { promote: auto }`, which
+   `canon init` writes, and followed by `canon gate promote` only under
+   `write.promote: manual`). 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:
 
@@ -26,15 +28,17 @@ The order an agent follows to claim a subject done:
    canon finding add --change-id c-demo --round 1 --seq 1 \
      --severity blocker --disposition open --reviewer reviewer-2 \
      --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 \
      --disposition fixed --resolution-sha "$(git rev-parse HEAD)"
-   canon gate promote
    ```
 
+   Under `write.promote: manual` (or no `write:` key), run
+   `canon gate promote` after each of the two.
+
 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 +47,13 @@ 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. A reviewer of user-visible behavior attaches
+   the screenshots or recordings it looked at with `--artifact <path>`
+   (below).
 
 4. **Move the subject**: `canon subject status <id> verifying`, later
    `shipped`. See `canon-subject`.
@@ -65,22 +75,36 @@ canon finding close --change-id <c> --round <n> --seq <n> \
   --disposition fixed --resolution-sha <sha> [--session-id <id>]   # or rejected / deferred / open
 ```
 
-Both stage a candidate; `canon gate promote` commits it, and both say so
-(``… — run `canon gate promote` to commit it``). `finding close`
+Both stage a candidate. Under `write: { promote: auto }` (what
+`canon init` writes) the same run promotes it and the success line names
+the committed record (``wrote kind=finding/… — staged and promoted in this
+run; nothing to promote``); under `write.promote: manual`
+`canon gate promote` commits it, and the line says so (``staged … — 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. 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 +137,101 @@ 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>] \
+  [--artifact <path>]... [--max-artifact-mib <MiB>]
 ```
 
 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 reviewer looked at (artifacts)
+
+`--artifact <path>` (repeatable) binds a file the reviewer looked at — a
+screenshot, a recording, a trace — exactly as `canon evidence add
+--artifact` binds one: the path must resolve to a file inside the
+repository, a file over 25 MiB is refused unless `--max-artifact-mib <N>`
+raises the limit, and the bytes are copied into
+`.canon/artifacts/sha256/<hex>` (commit it with the ledger) before the
+review is written. Any refusal exits 2 and writes and stores nothing. The
+review records each distinct file once, in the order given:
+
+```json
+"artifacts": [{"path": "reports/title.png", "sha256": "<64 hex>"}]
+```
+
+The field is absent when no `--artifact` is given. `review add` prints
+`canon review add: artifact store holds <n> bound file(s) under
+.canon/artifacts/sha256/ (<k> newly stored) — commit them with the
+ledger`.
+
+`canon gate check` re-hashes the stored blob of every file bound to an
+in-effect review (the latest per `(project_id, scenario_id, reviewer)`).
+A missing or altered blob is `stale-evidence` on the review's scenario,
+naming the review, even when the working-tree file still matches (see
+`canon-gate`, "Bound evidence stays provable"):
+
+```
+stale-evidence world.demo.01 — review by `reviewer-2` (actor `reviewer-2`, 2026-10-11T09:00:00Z) bound file `reports/title.png` recorded sha256 <hex>; stored blob .canon/artifacts/sha256/<hex>: missing; working tree: <hex> — the bound bytes are gone, look again and re-record the review with `canon review add --artifact <path>`
+```
+
+The reviewer's later review replaces the earlier one, so its files are
+the ones checked. Canon binds and re-checks bytes only; it never compares
+images or judges what a screenshot shows.
+
+### 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 +275,64 @@ 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; or, written before 0.15 without pins, still
+   describes its scenario at the commit it pinned (below);
+3. passes `distinct_actor`, when that is on.
+
+### Reviews written before pinning
+
+A review written before 0.15 has no pins, only `pin`: the commit it
+reviewed. The gate reads the scenario's `.feature` file at that commit
+(`git`, with the same per-scenario normalization `canon inventory sync`
+uses for `scenario_digest`; if the scenario was in another file then, the
+spec root's files at that commit are searched for its id) and decides:
+
+- **current** when that digest equals the scenario's current one and no
+  declared evidence record of the scenario is newer than the review: it
+  counts under rules 1 and 3;
+- **stale** when the scenario changed since the commit (`its spec changed
+  since <pin>`) or has evidence newer than the review (`it has declared
+  evidence newer than the review`): it no longer counts, exactly like a
+  stale pinned review;
+- **undecidable** when the pin is not a commit in this clone (shallow
+  clone, rewritten history) or the scenario id is absent at it: it keeps
+  counting, as in 0.15. A missing commit never becomes a violation.
+
+`canon gate check` prints one advisory line with the split (exit code
+unchanged by the line itself). A stale one whose scenario already has
+another qualifying review is counted as superseded and not named:
+
+```
+advisory: 338 review(s) predate review pinning (0.15) and were checked against the commit each one pinned: 318 current, 12 stale, 8 undecidable; 7 stale one(s) superseded by a current review of the same scenario, so nothing is owed for them; a stale one with no current review in its place no longer counts — review its scenario again (`canon review add`): platformer.movement.01, platformer.movement.02, …; an undecidable one still counts unchecked, because its pinned commit or the scenario at it is not in this clone — check out full history (`fetch-depth: 0` in CI) to check it
+```
+
+`canon status` prints the same line as a warning, and `canon subject
+status` prints it on stderr for the subject's own scenarios; all three
+make the same decision. Re-review exactly the scenarios the line names:
+the new review pins what it saw and replaces the reviewer's legacy one.
+In CI, check out full history (`fetch-depth: 0`) for the job that runs
+the gate, or every legacy review is undecidable.
+
 ### `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 +351,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 +399,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,130 @@ 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. The log is local operator state: `canon init` keeps
+`.canon/audit/` out of git (below). `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.
+
+## Staged writes and promotion
+
+Four writes stage their record instead of committing it: `canon evidence
+add`, `canon finding add` and `canon finding close` (under
+`.canon/ledger/_staging/`, committed by `canon gate promote`) and `canon
+divergence stage` (committed by `canon divergence promote`). `canon.yaml`'s
+`write:` section decides whether they promote in the same run:
+
+```yaml
+write:
+  promote: auto   # or manual
+```
+
+- `auto` — the command stages, then promotes that one record through the
+  same validation and assignment `canon gate promote` (or `canon
+  divergence promote`) applies. Records other runs staged stay staged;
+  only `canon gate promote` / `canon divergence promote` commit
+  everything staged. The one success line names the committed record
+  (`wrote kind=…/….json`; promotion renames it, so the staged file is not
+  named) and ends `— staged and promoted in this run; nothing to
+  promote`. `canon init` writes `auto`.
+- `manual` — the record stays staged and the line ends ``— run `canon
+  gate promote` to commit it``. An absent `write:` key (or `promote:`
+  field) is `manual`, so a repo that never set it is unchanged.
+
+`--promote` / `--no-promote` decide for one write and win over the config
+without reading it; both at once is a usage error (exit `2`). If the
+promotion refuses the command's own record, the record stays staged, the
+line ends ``— run `canon gate promote` to commit it`` (`canon divergence
+promote` for a divergence), and the command exits `1`. With neither flag,
+a malformed `write:` section (anything but `promote: auto | manual`)
+refuses the write, exit `2`, before anything is staged. `canon init
+--check-config` reports `[PASS] write (promote: auto)`, `[not configured]
+write (promote: manual)`, or `[FAIL] write: …`. `canon gate promote` still
+works under `auto` and is idempotent: with nothing staged it prints
+`nothing staged` and exits `0`.
+
+## The scenario index
+
+`canon inventory sync` materializes one `Scenario` record per
+`(project_id, scenario_id)` under `.canon/ledger/kind=scenario/`. The
+index is derived — a pure function of the `.feature` files — so the
+commands that read it rebuild it first: `canon gate check`, `canon
+status`, `canon subject status`, `canon review add` and `canon evidence
+add`. The index is stale when a `.feature` file holds a scenario with no
+live index record, or one whose recorded source digest differs from the
+file's current bytes, or when the index holds a scenario of a spec root
+that no `.feature` file of it declares any more. The reader then runs
+`canon inventory sync`'s code on the changed files (validation still
+covers the whole root) and prints one stderr line:
+
+```
+canon status: refreshed the scenario index from 1 changed feature file(s) (specs/features/kind=feature/area=cart/add.feature): 1 record(s) written
+```
+
+A deleted scenario is not erased: `canon inventory sync` — and a reader's
+refresh, identically — appends a tombstone, a new generation of its
+record with `removed: true`. The gate, `canon status`, `canon query` and
+the report panels then treat it as absent; re-adding the scenario writes
+a live generation that supersedes the tombstone. A root that fails to
+sync writes no tombstone either.
+
+```
+canon status: refreshed the scenario index from 1 scenario(s) no longer in any feature file (cart.pay.01): 1 record(s) written
+```
+
+`canon inventory sync` and every refresh hold an OS file lock on
+`.canon/scenario-index.lock` while they write, so concurrent runs never
+index one change twice; a refresh that waited checks staleness again and
+is silent if another run already did the work. The lock is released when
+its holder exits, however it exits, so it never goes stale; a writer
+gives up after 30 s with a message naming the file (`canon inventory
+sync` exits `2`; a reader skips the refresh and still runs).
+
+A fresh index prints nothing. A root that fails to sync (format
+violations, a duplicate id) is named and left as it was, and the command
+still runs; `canon gate check` then fails with `uncovered-cell <root>`,
+the `verifying → shipped` guard refuses, and `canon status` lists only
+`canon inventory sync`, while the reporting readers (`query`, `context`)
+keep only this line:
+
+```
+canon gate check: found the scenario index stale for 1 changed feature file(s) (…): 0 record(s) written; NOT refreshed: root `root` (2 format violation(s), 0 sync error(s)) — `canon inventory sync` lists them
+```
+
+Nothing is written in a directory without `canon.yaml`. `canon inventory
+sync` stays the explicit command, and the one that lists violations and
+tag diagnostics.
+
+## The artifact store lock
+
+Every write to the evidence artifact store (`.canon/artifacts/sha256/`:
+`canon evidence add`, `canon review add`, `canon evidence vault`) holds an
+OS file lock on `.canon/artifact-store.lock` from its "already stored?"
+check through its last rename, so a write that fails and rolls back never
+removes a blob another writer published or counted as stored. A rollback
+removes only the blobs its own write renamed into place; a blob already
+stored intact counts as stored and is not written again. The lock is
+released when its holder exits, however it exits, so it never goes stale;
+a writer gives up after 30 s with a message naming the file and saying to
+retry (the command exits `2` and writes no record).
+
+## What `canon init` keeps out of git
+
+A fresh `canon init` writes these lines to `.gitignore` (each under a
+comment, only the missing ones):
+
+- `.canon/hot.db*` — the sqlite hot tier and its WAL/SHM sidecars.
+- `.canon/audit/` — the query/export/purge access log.
+- `.canon/ledger/kind=scenario/` — the scenario index; every reader
+  rebuilds it.
+- `.canon/scenario-index.lock` — the lock serializing index rebuilds.
+- `.canon/artifact-store.lock` — the lock serializing artifact store
+  writes.
+
+A rerun on a repo that already has `canon.yaml` only refreshes
+`AGENTS.md`, so an existing repo's `.gitignore` is unchanged; add the
+lines by hand to adopt them.