@journeykit/canon 0.15.0 → 0.17.0

package/dist/skills/SKILL.src.md

@@ -13,31 +13,67 @@ 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 with
-  `canon policy approve --by <who>` (and again after every change to it);
-  never edit it to make the gate pass, and never approve it yourself.
-
-When no human can answer, write the question into the brief, proceed on the
-assumption you state there, and say so in your final report.
-
-1. **Brief.** Write down the request verbatim, your assumptions, and the
-   questions you could not ask. It becomes the change's
-   `openspec/changes/<slug>/proposal.md`, which
-   `canon change new <slug> --subject <id> --title "…"` scaffolds once the
-   subject exists (step 2). A human approves the brief.
+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
+  `.canon/changes/<slug>/brief.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 `.canon/changes/<slug>/brief.md`, which
+   `canon change new <slug> --subject <id> --title "…"` writes once the
+   subject exists (step 2). A change that comes from an external plan the
+   human prepared (an openspec `proposal.md` read through
+   `plans.sources`) gets its brief there too: a `brief.md` whose
+   `Source: <path>` line points at the plan; canon never edits the plan.
+   Once the brief is there, stop and report it,
+   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 `.canon/changes/<slug>/brief.md` it writes. 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. Specs live at
+   `<root>/kind=feature/area=<area>/<surface>.feature` under a
+   `specs.roots[]` root (default `.canon/specs`); a root still on
+   `features/kind=feature/` is refused until you run `canon migrate`.
 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>`),
@@ -52,31 +88,56 @@ assumption you state there, and say so in your final report.
    `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.
+   (`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. The reviewer records every defect
    the review finds as a finding:
-   `canon finding add --change-id <slug> --round <n> --seq <n> --severity <blocker|should-fix|note> --reviewer <me> --actor-id <me> --session-id <session> --summary "…"`,
-   then `canon gate promote`; once fixed,
+   `canon finding 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>`
-   (a short sha is fine; canon resolves it)
-   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
+   `.canon/changes/<slug>/brief.md` has no `Approved:` line (for a change
+   from an external plan with no canon brief yet, it names the `brief.md`
+   to create with its `Source:` 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
+   brief to answer there is nothing to refuse, 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
 
@@ -85,13 +146,18 @@ 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 skills install                         # detects .claude/.agents|.codex/.omp/.pi; if none exists, installs Claude+Codex
-canon skills install --providers=claude,codex,omp,pi
+canon init                                   # canon.yaml, starter policy (--policy light|standard|strict, default strict; see canon-policy), AGENTS.md block, commented plans examples
+canon init --providers=claude,codex          # harnesses for the canon skill; without it init asks on a terminal, else takes the detected .claude/.codex/.omp/.pi
+canon skills install                         # follows canon.yaml skills.providers (else the install lock's, else the detected ones; none detected installs nothing)
+canon skills install --providers=claude,codex,omp,pi   # any subset or none; rewrites skills.providers
 canon skills check                           # read-only drift check
-canon skills doctor                          # diagnostics; never deletes user files
+canon skills doctor                          # diagnostics, incl. a stray canon projection for an unselected provider; never deletes user files
 ```
 
+The harness list lives in `canon.yaml` as `skills: { providers: [...] }`.
+`.agents` alone never selects Codex; `.codex` does. Change the list with
+`canon skills install --providers=<list>`, never by assuming a default.
+
 The canonical bundle is read-only. Claude receives
 `.claude/skills/canon/SKILL.md`; Codex receives
 `.agents/skills/canon/SKILL.md`; OMP receives `.omp/skills/canon/SKILL.md`; and

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 <root>`) 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
@@ -151,7 +158,7 @@ canon inventory sync                                                 # index it
 ## Worked example
 
 ```
-specs/features/kind=feature/area=checkout/
+.canon/specs/kind=feature/area=checkout/
   cart.feature        # surface: the cart screen
   payment.feature     # surface: the payment step
 ```

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

@@ -3,7 +3,7 @@
 `canon format --check` is canon's read-only format validator over a
 consumer-repo artifact corpus: ledger records (run/drill/review/clear/
 code-review/design-review), divergence events (manifest/review/
-remediation), `features/`, `inventory/`, and `policy.yaml`. It never
+remediation), `kind=feature/` spec files, `inventory/`, and `policy.yaml`. It never
 rewrites or mutates the corpus — it only validates and reports.
 
 ## Running
@@ -17,7 +17,7 @@ a report grouped by failure class in this fixed order:
 
 | Failure class | Meaning | Fix |
 |---|---|---|
-| `layout-grammar` | Wrong Hive path shape — a `features/`/`inventory/` file not under a `kind=<kind>/area=<area>/` prefix, a wrong leaf filename, or `assets.lock`'s ad-hoc format. | Move the file under the correct `kind=…/area=…/` prefix with the expected leaf name. |
+| `layout-grammar` | Wrong Hive path shape — a spec or `inventory/` file not under a `kind=<kind>/area=<area>/` prefix, a wrong leaf filename, or `assets.lock`'s ad-hoc format. A spec root still on the pre-0.17 layout (any `.feature` file under `<root>/features/`) is refused with one violation at path `features`. | Move the file under the correct `kind=…/area=…/` prefix with the expected leaf name. For a pre-0.17 root, run `canon migrate`, which moves `features/kind=feature/` to `<root>/kind=feature/`. |
 | `missing-envelope` | A YAML file (`inventory/`, `policy.yaml`) has no top-level `schema`/`kind`/`at`/`actor` keys. | Add the four envelope keys at the top level. |
 | `missing-provenance` | A `.feature` file's `Feature:`/`Scenario:` header has no `# canon: {...}` comment either directly above it (with its tags, no blank line) or directly below it. | Use `canon scenario new` / `canon feature new`, which stamp it; never hand-type the line. See `canon-authoring`. |
 | `missing-actor` | No structured `actor` object — a bare `by` string, or absent. | Replace `by: <name>` with a structured `actor` object. |

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

@@ -24,7 +24,7 @@ Every violation carries one of these stable, grep-able strings:
 | `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, 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. |
@@ -57,6 +57,35 @@ 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) (.canon/specs/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).
+
+A spec root still on the pre-0.17 layout (a `.feature` file under
+`<root>/features/`) fails closed the same way, whether or not the index
+already holds its scenarios: the gate adds `uncovered-cell <root> — spec
+root `<root>` (`<path>`) is on the pre-0.17 layout (…)…; until then its
+scenarios are not graded` and exits 1, the ship guard refuses with the
+same violation, and `canon status` names `canon migrate` as its only
+step. `canon migrate` moves `features/kind=feature/` to
+`<root>/kind=feature/`; run it, then the gate again.
+
 ### The spec-derived worklist (`spec_coverage`, opt-in)
 
 Coverage groups the EVIDENCE corpus, so it can only ever enumerate
@@ -219,6 +248,61 @@ 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's canon `.canon/changes/<change>/brief.md` has no `Approved:`
+line, or there is no canon `brief.md` yet but the change comes from an
+external openspec plan with a `proposal.md` under the plan sources (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 — .canon/changes/c-demo/brief.md has no `Approved:` line, so the human has not answered it; once they do, record their words as `Approved: <who> <when> — "<their words>"` in .canon/changes/c-demo/brief.md
+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 brief.md only from that answer; to attest anyway, pass --override-reason <text>, which is recorded on the evidence record
+```
+
+For a change from an external plan with no canon brief yet, the first
+line says instead ``.canon/changes/c-ext/brief.md does not exist yet:
+change `c-ext` comes from the external plan
+openspec/changes/c-ext/proposal.md, which canon reads and never edits, so
+its approval lives in that canon file, so the human has not answered it;
+once they do, create .canon/changes/c-ext/brief.md holding a `Source:
+openspec/changes/c-ext/proposal.md` line and record their words there as
+`Approved: <who> <when> — "<their words>"` ``. An `Approved:` line in the
+external `proposal.md` itself is never read.
+
+A subject with no brief to answer (no adopted change, or a newest change
+with neither a canon `brief.md` nor an external `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
@@ -235,17 +319,62 @@ review waivers: 1 advisory(ies) — not failing the gate:
 
 The waiver lasts only until the subject's next status write.
 
-### Reviews that predate pinning
+`canon subject status <id> shipped` also refuses where a brief exists and
+has no `Approved:` line (the subject's newest adopted change has a canon
+`brief.md`, or an external `proposal.md` and no canon `brief.md` yet;
+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. They keep
-counting, and one advisory line after the violations counts them; the
-exit code is unchanged:
+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, then the files
+  under each of the root's `former_roots` (where `canon migrate` moved
+  it from, e.g. `specs` for a root now at `.canon/specs`). Only the
+  root's own directories are searched, never another root's.
+- **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: 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
 ```
 
+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
@@ -338,6 +467,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,
@@ -377,12 +515,19 @@ empty clean map.
 ## `canon gate task <task_id> [--repo <dir>]`
 
 The evidence-gated task checkbox flip. Resolves `<task_id>`
-(`<change_id>#<n>`) through `canon.yaml`'s `plans:` sources — the first
-configured dialect whose `PlanWriteBack` locates the task's document
-wins, so the flip is plan-dialect agnostic (`openspec` change dirs,
-`superpowers` plan docs). A repo with no `plans:` section falls back to
-the compat default `[{ dialect: openspec, root: <repo> }]`; no source
-locating the task at all is a loud failure naming every source consulted.
+(`<change_id>#<n>`) through `.canon/changes/` (canon's own changes, read
+first whenever the directory exists, with no `plans:` entry) and then
+`canon.yaml`'s `plans.sources` — the first dialect whose `PlanWriteBack`
+locates the task's document wins, so the flip is plan-dialect agnostic
+(canon's own `tasks.md`, external `openspec` change dirs, `superpowers`
+plan docs). A repo with no `plans:` section falls back to the compat
+default `[{ dialect: openspec, root: <repo> }]`; no source locating the
+task at all is a loud failure naming every source consulted. A repo with
+no `.canon/changes/` and `sources: []` is refused: "this repo configures
+no plan sources (no `.canon/changes` and no `plans.sources` entries in
+canon.yaml) … write the change with `canon change new`, or list your
+external plans under `plans.sources`" (`canon dispatch --task` says the
+same).
 It requires
 a matching non-`Divergent` evidence record, and flips `- [ ]` → `- [x]`
 with an appended evidence note ONLY on a clean check. The note
@@ -414,6 +559,13 @@ canon gate task my-change#5.2 --repo .
 This is canon's own authority for the checkbox grammar — always flip
 through `canon gate task`, never by hand.
 
+Canon only reads external plans, with this one exception: for a task
+from an external plan source, `canon gate task` flips the checkbox in
+that plan's own `tasks.md` (or plan document). It is the one place canon
+writes into an external plan; their briefs and approvals still live in
+`.canon/changes/<change>/brief.md`. (Open for the maintainer: record
+external flips only in the ledger instead.)
+
 ## `canon gate promote [--repo <dir>] [--dry-run]`
 
 Staging → committed: every well-formed record under
@@ -431,13 +583,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]`
 

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

@@ -1,16 +1,74 @@
 # 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) (.canon/specs/kind=feature/area=cart/add.feature): 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 <root>` 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.
+
+A spec root still on the pre-0.17 layout (a `.feature` file under
+`<root>/features/`) is not refreshed and fails closed the same way: the
+reader names the root and `canon migrate` on stderr and writes no
+tombstones, `canon gate check` fails (`uncovered-cell <root>`) whether or
+not the index already holds its scenarios, `shipped` is refused, and
+`canon status` lists only `canon migrate`. `canon inventory sync` does not
+fix it; run `canon migrate`, which moves `features/kind=feature/` to
+`<root>/kind=feature/`.
+
+`canon migrate --dry-run` prints the plan without writing anything, and
+`canon migrate` applies it. Commit first: it refuses while a path it
+moves has uncommitted changes, and when a destination already exists.
+A root at the repo-level `specs` moves to `.canon/specs`, and
+`canon.yaml` records `former_roots: [specs]`, so reviews pinned before
+the move still find their scenarios. Changes `canon change new` wrote
+under `openspec/changes/` move to `.canon/changes/<slug>/`
+(`proposal.md` becomes `brief.md`). An `Approved:` line in an external
+`proposal.md` is copied into a canon pointer `brief.md`. The command
+also writes `skills.providers` from the install lock, adds the missing
+canon `.gitignore` lines, and ends with a full index rebuild. It is
+idempotent, and a run that stopped partway is finished by the next run:
+`canon.yaml` is written atomically, a half-moved change is completed,
+and the openspec source `canon init` wrote is removed only after every
+pointer brief is written and nothing unread is left under
+`openspec/changes/` (each unread directory is named).
+
+The reader's refresh treats a file as stale when its latest index
+generation has another `source_digest` or `scenario_digest`. A
+generation written before 0.15 has no `scenario_digest`, so a repo that
+kept an old index gets it rewritten on the first read.
+
+## 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 +81,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>]`
 
@@ -39,7 +97,7 @@ Per configured root, in order:
 1. **Validate** — runs `canon format --check` over the root. ANY violation
    (missing provenance, layout-grammar, …) ABORTS THE WHOLE ROOT: zero
    records written for it, the violation(s) reported. Never a partial sync.
-2. **Scan** — walks `<root>/features/**/*.feature`, pairing each
+2. **Scan** — walks `<root>/kind=feature/area=<area>/<surface>.feature`, pairing each
    `@<area>.<surface>.<nn>` tag with its header label as `title` and a
    `source_digest` (sha256 over the raw `.feature` bytes). `@subject:<id>`
    → `subject_id`, `@lane:<v>` → `lane`, `@case:<v>` → `case` (first tag
@@ -73,7 +131,10 @@ specs:
       root: apps/b/specs
 ```
 
-- **Absent `specs:` key** → the single default root `{id: root, root: specs}`.
+- **Absent `specs:` key** → the single default root
+  `{id: root, root: .canon/specs}`, the one `canon init` writes. An entry
+  with no `root:` also resolves to `.canon/specs`. The default root is
+  authored and git-tracked; no canon gitignore line covers it.
 - **Present `specs:` with an empty/missing `roots[]`** → fails LOUD; a
   present-but-incomplete config never silently resolves to zero roots.
 - **A malformed entry** (missing `id`, `roots` not a list, `id` not a
@@ -86,6 +147,10 @@ specs:
 
 - **A `canon format --check` validation violation** in the root's corpus →
   whole root aborts, 0 writes, violations reported.
+- **A root on the pre-0.17 layout** (a `.feature` file under
+  `<root>/features/`) → a `layout-grammar` violation at path `features`;
+  the root aborts, 0 writes, exit 1. Run `canon migrate`. An empty
+  leftover `features/` directory is not a refusal.
 - **A duplicate `scenario_id`** within one root → that root aborts, 0
   writes, reported as a sync error (a distinct lane from fmt violations).