@journeykit/canon 0.15.0 → 0.17.0

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

@@ -1,13 +1,34 @@
 # canon-plan-import
 
-`canon ingest plans` imports a FOREIGN plan dialect's on-disk state into
-canon's `change`/`task` records, through the same validated path every
-other ingest family uses. Imported rows carry no special marker — once
+`canon ingest plans` imports plan state into canon's `change`/`task`
+records, through the same validated path every other ingest family uses:
+canon's own changes under `.canon/changes/`, and any FOREIGN plan dialect
+listed in `canon.yaml`. Imported rows carry no special marker — once
 imported, `canon query` cannot tell an imported row from a hand-authored
 one, and neither can `canon gate`.
 
-## 1. Configure a `plans:` source
-
+## 1. Canon's own changes and external `plans:` sources
+
+`.canon/changes/` is canon's native plan source (dialect id `canon`):
+one `<slug>/` directory per change holding `brief.md` and `tasks.md`,
+written by `canon change new` (see `canon-subject`). Every plan reader —
+`canon ingest plans`, `canon gate task`, `canon evidence add --task`,
+`canon dispatch --task`, `canon status` and the brief check — reads it
+first whenever the directory exists, with no `plans:` entry. Being first,
+it owns a change id an external source also carries (the external copy
+is the later duplicate, skipped and counted under `duplicate_change_id`).
+Its records carry the actor `canon-plan-import-canon`; an external
+openspec change's carry `canon-plan-import-openspec`. A `brief.md` with a
+`Source: <path>` line is not a change of its own: it is the canon brief
+of a change imported from an external plan (it points at the external
+document and holds the human's `Approved:` line), so the native reader
+skips that directory and the external source keeps the change id.
+
+`plans.sources` lists only EXTERNAL plans — documents you prepare outside
+canon, which canon only reads. The one exception: `canon gate task`
+flips the task's checkbox in an external plan's `tasks.md` (see
+`canon-gate`). Their briefs and approvals live in
+`.canon/changes/<change>/brief.md`, never in the external document.
 `canon.yaml`:
 
 ```yaml
@@ -17,17 +38,22 @@ plans:
       root: .              # resolved relative to canon.yaml's directory
 ```
 
-- `canon init` writes exactly this source, plus an empty
-  `openspec/changes/` (so the adapter never scans the repo root itself).
-- An absent `plans:` section = zero sources (a clean no-op).
+- `canon init` writes `sources: []`, preceded by comments explaining
+  `.canon/changes/` and commented examples for `openspec` (`root: .`) and
+  `superpowers` (`root: docs/superpowers/plans`). It creates no
+  `openspec/changes/` directory.
+- An absent `plans:` section = zero external sources (a clean no-op;
+  `.canon/changes/` is still read).
 - A present section parses STRICTLY: a typo'd key, an unregistered
   `dialect`, or a nonexistent `root` fails the command loud, naming the
-  offender.
+  offender. `canon` is not a registered dialect: a source naming it is
+  refused, since `.canon/changes/` needs no entry.
 - `root` is whatever the dialect's adapter scans — for `openspec`, a
   repo root containing `openspec/changes/`, or that changes dir directly.
 
-One-shot override (bypasses `canon.yaml` for a single ad hoc import;
-either flag alone fails loud):
+One-shot override (bypasses `canon.yaml` and `.canon/changes/` for a
+single ad hoc import, reading only the source it names; either flag alone
+fails loud):
 
 ```bash
 canon ingest plans --dialect openspec --source ../other-repo
@@ -36,7 +62,7 @@ canon ingest plans --dialect openspec --source ../other-repo
 ## 2. Run the import
 
 ```bash
-canon ingest plans                 # canon.yaml-driven, every configured source
+canon ingest plans                 # .canon/changes/ + every configured source
 canon ingest plans --json          # machine-readable outcome
 canon ingest plans --repo ../svc   # a specific repo root
 ```
@@ -60,9 +86,19 @@ canon query --kind task [--json]
 No dialect/plugin filter exists or is needed — an imported `change`/
 `task` is an ordinary core record.
 
+## The `canon` dialect (`.canon/changes/`)
+
+Uses the `openspec` change-dir grammar below, with three differences:
+the brief is `brief.md` (its `## Why` first paragraph is the summary; a
+missing one is a `missing-brief-md` malformed dir), the source root is
+always `.canon/changes/` itself (archived changes under
+`.canon/changes/archive/`), and a `brief.md` carrying a `Source:` line is
+skipped (a pointer brief, above). `tasks.md` uses the same checkbox row
+grammar.
+
 ## The `openspec` dialect
 
-Maps `openspec/changes/**` onto core kinds:
+Maps an external `openspec/changes/**` onto core kinds:
 
 | openspec construct | Core mapping |
 | --- | --- |
@@ -76,7 +112,9 @@ Maps `openspec/changes/**` onto core kinds:
 A missing/unreadable `proposal.md`, or a basename that isn't a valid
 `change_id`, skips the WHOLE dir (counted `malformed`); siblings
 unaffected. A proposal-only dir imports as `Change { status: proposed }`
-with zero tasks and zero diagnostics.
+with zero tasks and zero diagnostics. An `Approved:` line in an external
+`proposal.md` is not read: the change's approval lives in
+`.canon/changes/<change>/brief.md` (see `canon-subject`).
 
 ## The `superpowers` dialect
 
@@ -136,9 +174,10 @@ downstream reader's job.
 
 ## What this skill does NOT cover
 
-- **Authoring an openspec change dir** (`proposal.md`/`tasks.md`
-  conventions) — `canon change new` scaffolds one and adopts it into a
-  subject (see `canon-subject`); this skill covers IMPORTING that shape.
+- **Authoring a change** — `canon change new` writes
+  `.canon/changes/<slug>/brief.md` and `tasks.md` and adopts the change
+  into a subject (see `canon-subject`); it never scaffolds an openspec
+  change dir. This skill covers IMPORTING plans.
 - **`canon gate check`/`canon gate task`** (the hand-authored one-task-at-
   a-time path this complements at bulk) — see `canon-gate`.
 - **Wiring an imported `Task`/`Change` into a `canon gate` decision** —

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

@@ -26,21 +26,45 @@ 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 (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`).
+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
 
@@ -48,8 +72,11 @@ only for subjects in those statuses (see `canon-gate`).
 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):
+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
 {
@@ -85,8 +112,8 @@ An approval file that does not parse reads
 `--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.
+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
 

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,13 +28,14 @@ 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, after
    the evidence is in (the review pins what it saw):
@@ -48,7 +51,9 @@ The order an agent follows to claim a subject done:
    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.
+   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`.
@@ -70,8 +75,12 @@ 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
@@ -130,7 +139,8 @@ 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>] \
   [--outcome signed|indeterminate|unavailable] \
-  [--reviewer-provider <p>] [--reviewer-model <m>] [--reviewer-harness <h>]
+  [--reviewer-provider <p>] [--reviewer-model <m>] [--reviewer-harness <h>] \
+  [--artifact <path>]... [--max-artifact-mib <MiB>]
 ```
 
 One attributed Review record for one scenario, joined on
@@ -143,6 +153,40 @@ 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
@@ -245,20 +289,43 @@ 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;
+   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.
 
-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):
+### 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: 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
+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. Reviewing
-the scenario again pins it and drops it from the count.
+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`
 

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

@@ -149,7 +149,150 @@ Every query, export, and purge appends an actor-stamped record to
 `.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
+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`.
+
+## Harnesses: the `skills:` section
+
+`canon.yaml`'s `skills:` section names the harnesses the canon skill is
+installed for (0.17):
+
+```yaml
+skills:
+  providers: [claude, codex]   # any of claude, codex, omp, pi; [] for none
+```
+
+`canon init` writes it: on a terminal it asks, with the harnesses whose
+`.claude`, `.codex`, `.omp` or `.pi` directory exists checked;
+`--providers a,b` (or `none`) answers without asking; with neither it takes
+the detected ones, and with none detected it writes only a commented example
+and installs nothing. `.agents` alone never selects Codex. `canon skills
+install|check|doctor` follow the section; `canon skills install
+--providers=<list>` rewrites it in place. Without the section they use the
+install lock's providers, then the detected ones; nothing undetected is ever
+added. A present section that is not this shape, or names another harness,
+fails those commands (exit `1`), and `canon init --check-config` reports
+`[PASS] skills (providers: …)`, `[not configured] skills (…)`, or
+`[FAIL] skills: …`.
+
+## 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) (.canon/specs/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.