@journeykit/canon 0.15.0 → 0.16.0

package/dist/skills/SKILL.src.md

@@ -13,31 +13,60 @@ 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
+a feature, a one-line request included. A human is needed once per scope:
+
+- **The approval** (step 1). A new subject, or a change to an approved
+  subject's scope, needs the human to approve its brief: the request, your
+  assumptions, your open questions. Write the brief, then stop and report
+  it: build nothing for that scope (no scenarios, code or evidence) before
+  the human answers. The approval is the one thing you never assume, even
+  when the human said they cannot answer until you report: the brief is
+  that report. In the same answer the human approves the policy,
+  `.canon/policy.yaml` (written by `canon init`), which is what the gate
+  grades the work against. When the human answers, record both at once:
+  an `Approved: <who> <when> — "<the human's words>"` line in the change's
+  `proposal.md`, and
+  `canon policy approve --by <the human> --note "<their words>"`. Never
+  approve without a human answer, and never edit the policy to make the
+  gate pass.
+- **Inside an approved scope, never stop for a human.** Fixes, follow-ups,
+  review rounds and re-reviews go straight on: add or extend the scenario,
+  implement, gather evidence, and get an independent review in another
+  session. Independent review happens on every change. A fix or follow-up
+  stays in the approved change: add it as tasks in that change's
+  `tasks.md`, never with `canon change new`, because a new change is a new
+  scope and needs the human's approval.
+
+When no human can answer one of the brief's questions, write the question
+into the brief, state the assumption you will build on, and say so in your
+report. Proceeding on an assumption applies to the brief's questions and to
+work inside an approved scope, never to the approval itself.
+
+1. **Brief.** For a new subject or a scope change, write down the request
+   verbatim, your assumptions, and the questions you could not ask. It
+   becomes the change's `openspec/changes/<slug>/proposal.md`, which
    `canon change new <slug> --subject <id> --title "…"` scaffolds once the
-   subject exists (step 2). A human approves the brief.
+   subject exists (step 2). Once it is there, stop and report the brief,
+   asking the human once for the brief and the policy; go on to step 3
+   only after the human answers, and record the answer as above. Inside an
+   approved scope there is no new brief: go to step 3 under the existing
+   subject and change.
 2. **Subject.** `canon subject new <id> --domain <domain> --title "…"`, then
    `canon change new <slug> --subject <id> --title "…"`, and put the brief in
-   the change's `proposal.md`.
+   the change's `proposal.md`. For a new subject or a scope change, this is
+   where you stop until the human answers (step 1).
 3. **Scenarios.** `canon feature new <area>.<surface> --title "…"`, then one
    `canon scenario new <area>.<surface>.<nn> --subject <id> --case <case> --title "…"`
    per behavior, with failure paths (`--case failure`) as well as `happy`
    and `edge`. When the gate asks for a missing case (`require_cases`), add
-   a new scenario; never retag an existing one to satisfy it. Check the
-   corpus with `canon format specs` and index it with `canon inventory sync`.
+   a new scenario; never retag an existing one to satisfy it. There is no
+   sync or format step: `canon status`, `canon gate check`,
+   `canon evidence add`, `canon review add` and `canon subject status`
+   index added, edited or deleted `.feature` files themselves. Only when
+   one of them prints `NOT refreshed` (a format violation, such as a
+   hand-written header with no `# canon:` provenance comment, or a
+   duplicate id) run `canon inventory sync`: it names each problem; fix
+   them, and the next command indexes the files.
 4. **Units.** Split the work into units (for example specs, domain code,
    assets, review). Give each unit its own actor id and session id, and pass
    them on everything the unit records (`--actor-id <unit> --session-id <session>`),
@@ -52,31 +81,54 @@ 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 `proposal.md`
+   has no `Approved:` line, and `canon evidence add` refuses the subject's
+   scenarios and tasks the same way. Both are backstops: the stop itself
+   is at step 1, so you never reach them for a brief the human has not
+   answered. You record the line only from the human's answer (with no
+   `proposal.md` there is no brief to answer: neither refuses, and the
+   ship guard only prints an advisory). Move the subject to
+   `shipped` yourself once `canon subject status <id> shipped` passes its
+   guard, unless the brief says the human ships. `canon status` shows
+   whether each subject's brief is approved, by the same check, and names
+   the next step.
+
+Every write command says whether the record is final (`written directly`,
+or `staged and promoted in this run`) or staged; only a staged record
+needs `canon gate promote`, and only `write.promote: manual` leaves one.
 
 ## Command reference
 
@@ -85,7 +137,7 @@ Load only the reference the current step needs.
 ### Setup and provider projection
 
 ```bash
-canon init                                   # canon.yaml, starter policy, AGENTS.md block, plans home
+canon init                                   # canon.yaml, starter policy (--policy light|standard|strict, default strict; see canon-policy), AGENTS.md block, plans home
 canon skills install                         # detects .claude/.agents|.codex/.omp/.pi; if none exists, installs Claude+Codex
 canon skills install --providers=claude,codex,omp,pi
 canon skills check                           # read-only drift check

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

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

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

@@ -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,26 @@ approved: …` or `advisory: policy changed since approval: …` after its
 result, naming `canon policy approve --by <who>`; the exit code is
 unchanged (see `canon-policy`).
 
+Before it reads the scenario index, the gate rebuilds any stale part of
+it from the changed `.feature` files (the same code `canon inventory
+sync` runs) and says so in one stderr line, silent when the index is
+fresh:
+
+```
+canon gate check: refreshed the scenario index from 1 changed feature file(s) (specs/features/kind=feature/area=cart/add.feature): 1 record(s) written
+```
+
+A root that fails to sync (format violations, a duplicate id) is named
+instead, ending ``NOT refreshed: root `x` (N format violation(s), 0 sync
+error(s)) — `canon inventory sync` lists them``, and the gate fails
+closed: it adds `uncovered-cell <root> — the scenario index for spec root
+`<root>` is stale and could not be refreshed (…); `canon inventory sync`
+lists the problems to fix` and exits 1, since the index it would grade
+does not hold the edits. The `verifying → shipped` guard refuses with
+the same violation, and `canon status` lists the sync as its only step.
+Fix what the sync lists and run the gate again. See `canon-storage`
+(The scenario index).
+
 ### The spec-derived worklist (`spec_coverage`, opt-in)
 
 Coverage groups the EVIDENCE corpus, so it can only ever enumerate
@@ -219,6 +239,48 @@ actually dropped, a multi-line reason, or a drop without
 `--scenario-id` (task-only evidence has no drop guard). `canon status`
 lists recorded drops (`dropped bindings (N):`; `drops[]` in `--json`).
 
+### Nothing is attested before the brief is approved (`--override-reason`)
+
+The approval is never assumed: the agent writes the brief, stops and
+reports it, and builds nothing for that scope until the human answers.
+`canon evidence add` is the backstop for that stop (0.16 M7). It
+refuses (exit `1`, nothing staged or stored) while a subject the record
+attests for has an enforced, unapproved brief: the newest adopted
+change has a `proposal.md` under the openspec plan sources with no
+`Approved:` line (the check `canon status` and the ship guard use; see
+`canon-subject`). The subjects are the scenario's `@subject` owner for
+`--scenario-id`, and every subject adopting the task's change for
+`--task`:
+
+```
+canon evidence add: unreviewed-promotion demo-subject — evidence for world.demo.01: brief not approved — openspec/changes/c-demo/proposal.md has no `Approved:` line, so the human has not answered it
+canon evidence add: refused — stop, report the brief to the human and wait for their answer: nothing is built or attested for a subject before its brief is approved. Record their words as `Approved: <who> <when> — "<their words>"` in that proposal.md only from that answer; to attest anyway, pass --override-reason <text>, which is recorded on the evidence record
+```
+
+A subject with no brief to answer (no openspec source, no adopted change,
+no `proposal.md`) and a scenario no subject owns are unaffected.
+`canon review add` and `canon finding add` are never refused.
+`--override-reason "<one line>"` attests anyway, prints the `waived …`
+lines and `override recorded by `<actor>` for the N brief refusal(s)
+above: <reason>`, and records on the evidence record:
+
+```yaml
+brief_override:
+  reason: the human approved in chat; the line follows
+  waived:
+    - { class: unreviewed-promotion, subject: demo-subject }
+  actor: { agent_id: lead }   # from --actor-id
+```
+
+A blank or multi-line reason exits 2; an override when nothing refused is
+not recorded. `canon status` lists each such record as a `warning:`, and
+`canon gate check` prints them after the result without failing:
+
+```
+brief overrides: 1 evidence record(s) attested before their brief was approved — not failing the gate:
+  evidence for world.demo.01 was attested by `lead` at 2026-10-12T07:00:00Z while the brief of demo-subject was not approved (override: the human approved in chat; the line follows)
+```
+
 ### Review-waiver advisories
 
 A subject moved into a review-scoped status with `canon subject status
@@ -235,17 +297,58 @@ 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
+`proposal.md`; see `canon-subject`), as an `unreviewed-promotion` naming
+the subject. With no brief to answer it prints an advisory and does not
+refuse. Like the evidence refusal above, it is a backstop: the stop is at
+the brief. `canon gate check` does not grade briefs, so a waived ship
+brief prints no advisory here; `canon status` keeps showing the brief as
+not approved.
+
+### Reviews that predate pinning (checked against their pin)
 
 With `require_review` on, the reviews in effect (latest per reviewer and
-scenario) that carry no pins were written before 0.15. 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.
+- **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 +441,15 @@ subject's status, and a repo with no `spec_coverage` would otherwise never
 have its bindings checked. A superseded record is not checked —
 re-attesting is the fix.
 
+Files bound to a review (`canon review add --artifact`, see
+`canon-review`) are checked the same way for every in-effect review (the
+latest per `(project_id, scenario_id, reviewer)`), with one difference:
+they were stored when the review was written, so only an intact blob is
+clean. A missing or altered blob is `stale-evidence` on the review's
+scenario, and the detail names the review: ``review by `<reviewer>`
+(actor `<id>`, <time>)``. The working-tree file is reported but never
+vouches for it.
+
 `canon evidence vault [--max-artifact-mib <N>]` stores the bytes for
 existing records: every attachment whose working-tree file still matches
 its digest is copied in, and everything else is listed as not stored,
@@ -431,13 +543,26 @@ canon gate promote --repo . --dry-run  # preview only
 ```
 
 Which writes need this step: `evidence add`, `finding add` and `finding
-close` stage, and their success line ends ``— run `canon gate promote`
-to commit it``. `divergence stage` stages for `canon divergence promote`
-and names it. Every other write — `review add`, `divergence
+close` stage, and under `write: { promote: manual }` (or an absent
+`write:` key) their success line ends ``— run `canon gate promote` to
+commit it``. Under `write: { promote: auto }` (what `canon init` writes)
+or with `--promote`, they promote the one record they just staged —
+same validation and `run_seq` assignment as this command — and print
+one success line naming the committed record (`wrote kind=…/….json`), not
+the staged file, ending `— staged and promoted in this run; nothing to
+promote`, so no separate
+`canon gate promote` is needed for it; `--no-promote` keeps one write
+staged. A record another run staged is not touched: only `gate promote`
+commits everything staged. It stays safe to run anyway: with nothing
+staged it prints
+`nothing staged` and exits `0`. `divergence stage` stages for `canon
+divergence promote` and names it, under the same `write:` rule. Every
+other write — `review add`, `divergence
 resolve|defer`, `subject new|adopt|status`, `change new`, `scenario new`, `feature new`,
 `gate task` (it edits the plan document and re-ingests it)
 — is final when it returns, and its success line ends `— written
-directly; nothing to promote`.
+directly; nothing to promote`. Full promote-on-write contract:
+`canon-storage` (Staged writes and promotion).
 
 ## `canon gate install-hooks [--repo] [--event] [--matcher] [--command] [--timeout]`
 

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

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

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,127 @@ 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`.
+
+## 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.

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

@@ -20,11 +20,13 @@ authored in one place:
 - **Changes**: `change_ids` on the Subject, appended by `canon subject
   adopt`.
 - **Scenarios**: the `@subject:<id>` tag on each Gherkin scenario,
-  indexed onto `Scenario.subject_id` by `canon inventory sync`. The
-  Subject record carries no scenario list — the spec corpus is the only
-  source, and the Subjects report panel, `spec_coverage.scope`, and the
-  shipped gate all read it from there. To link a scenario, tag it and
-  re-sync; there is no subject-side command for it.
+  indexed onto `Scenario.subject_id` by the scenario index (rebuilt by
+  `canon inventory sync`, and refreshed by every command that reads it).
+  The Subject record carries no scenario list — the spec corpus is the
+  only source, and the Subjects report panel, `spec_coverage.scope`, and
+  the shipped gate all read it from there. To link a scenario, tag it;
+  the next `canon status` or `canon gate check` indexes the tag. There is
+  no subject-side command for it.
 
 ## The 4-step loop
 
@@ -81,9 +83,10 @@ canon retrieve --role dev --domain dev --subject subject-domain-loop --k 5
 ### 3. Work → pin every artifact to `subject_id`
 
 - **Scenarios**: `canon scenario new <tag> --subject <subject-id>` emits
-  the `@subject:<subject-id>` tag; `canon inventory sync` maps the tag
-  onto the scenario's `subject_id`. A malformed/absent tag leaves it
-  unset (fail-soft), never an error. See `canon-authoring`.
+  the `@subject:<subject-id>` tag; the scenario index maps the tag onto
+  the scenario's `subject_id` the next time a command reads it (no sync
+  step; see `canon-inventory`). A malformed/absent tag leaves it unset
+  (fail-soft), never an error. See `canon-authoring`.
 - **Changes**: adopt imported plan changes under the Subject (see
   [Adopt flow](#adopt-flow)).
 - **Reviews / evidence / divergences**: authored as usual (`canon review
@@ -145,6 +148,36 @@ empty set; so is one whose `scenario` records route away from the
 gate's rung. Each refusal prints by failure class (`uncovered-cell`),
 exits 1, and the status stays `verifying`. `retired` is not gated.
 
+**The brief (0.16):** `verifying → shipped` also refuses where a brief
+exists and is not approved, read exactly as `canon status` reads it (one
+shared check, so status says `ship` only when this passes): the subject's
+newest adopted change has a `proposal.md` under the openspec plan sources,
+and it carries no `Approved:` line outside HTML comments and code fences.
+It runs with or without a policy. The refusal is an `unreviewed-promotion`
+naming the subject, and says what to do:
+
+```
+canon subject status: unreviewed-promotion demo-subject — verifying → shipped: brief not approved — openspec/changes/c-demo/proposal.md has no `Approved:` line; a human must answer the brief, and the agent records `Approved: <who> <when> — "<their words>"` there only from that answer
+canon subject status: refused — get the human's answer to the brief and record it as its `Approved:` line, or pass --override-reason <text> to move anyway; the waiver is recorded on the subject
+```
+
+Never write the line without the human's answer. When there is no brief to
+answer (no openspec plan source, no adopted change, or a change with no
+`proposal.md`), the move is not refused: it prints
+`canon subject status: advisory: <id>'s brief is not approved — <why>, so
+there is no brief to answer and shipping is not refused`, and status shows
+the brief as not approved, as an advisory. `subjects[].brief.enforced` in
+`canon status --json` says which case applies. A brief that says the human
+ships changes who runs the transition, not the check.
+
+This refusal is a backstop, and so is the evidence one: shipping is not
+the first thing an unapproved brief stops. The agent writes the brief,
+then stops and reports it, and nothing is built or attested for the
+subject until the human answers. `canon evidence add` refuses (exit 1,
+nothing staged) a scenario whose `@subject` owner, or a task whose change
+an adopting subject, has an enforced, unapproved brief, through the same
+check; see `canon-gate`.
+
 ### The review guard (`spec_coverage.require_review`, opt-in)
 
 When `.canon/policy.yaml` sets `spec_coverage.require_review` (see
@@ -172,9 +205,11 @@ canon subject status demo-subject verifying \
   --override-reason "reviewer out until Monday" --actor-id lead
 ```
 
-`--override-reason "<one line>"` waives ONLY `unreviewed-promotion` and
-`open-blocker` — never a ship-gate verdict or case gap, never unreadable
-routing. It prints the `waived ...` lines and `override recorded by
+`--override-reason "<one line>"` waives ONLY `unreviewed-promotion` (the
+review gaps and the brief check) and `open-blocker` — never a ship-gate
+verdict or case gap, never unreadable routing. A waived brief is recorded
+as `{ class: unreviewed-promotion, subject: <subject id> }`. It prints
+the `waived ...` lines and `override recorded by
 `lead` for the N violation(s) above: <reason>`, and records on the new
 Subject record exactly the violations it let through:
 
@@ -192,13 +227,14 @@ subject's next status write, so it never outlives the status it was
 granted for. While it stands, `canon gate check` lists the recorded gaps
 as advisories instead of failing; a gap it did not record (a blocker
 raised later, a scenario tagged later) still fails the gate. Without
-`require_review`, nothing is printed and nothing changes.
+`require_review`, nothing is printed and nothing changes, except that
+`shipped` still runs the brief check above.
 
 ## Adopt flow
 
-Planning docs become change/task records via `canon ingest plans` (see
-`canon-plan-import`), but that stops at import. `canon subject adopt`
-lifts an imported change into a managed Subject:
+Planning docs written outside canon become change/task records via
+`canon ingest plans` (see `canon-plan-import`), but that stops at import.
+`canon subject adopt` lifts an imported change into a managed Subject:
 
 ```bash
 canon ingest plans --repo .                          # import → change/task rows
@@ -206,6 +242,13 @@ canon subject adopt subject-domain-loop-plan \
   --subject subject-domain-loop                        # link change → subject
 ```
 
+A change made with `canon change new` (below) is recorded and adopted
+already, and editing its `tasks.md` needs no import either:
+`canon evidence add --task` and `canon gate task` read the file as it is,
+and a flip re-imports that change itself. Run `canon ingest plans` for a
+plan written outside canon, or when `canon query --kind task` must list
+rows nobody has flipped yet.
+
 `adopt` stamps the change's `subject_id` and adds it to the Subject's
 `change_ids`, so `canon query --kind change --change-id …` and `canon
 query --kind subject` agree on the link from both ends. It writes only
@@ -251,9 +294,10 @@ canon change new add-login --subject auth --title "Add login"
   exist, when the slug already has a change dir (active or archived) or a
   `change` record, or when `canon.yaml` has no `openspec` plans source.
 
-Add task rows to `tasks.md` as `- [ ] <n> <title>`, rerun `canon ingest
-plans`, and flip each with `canon gate task <slug>#<n>` once evidence
-exists.
+Add task rows to `tasks.md` as `- [ ] <n> <title>`, and flip each with
+`canon gate task <slug>#<n>` once evidence exists. `canon evidence add
+--task` and the flip read `tasks.md` as it is, so a new row needs no
+`canon ingest plans` run.
 
 ## Where are we: `canon status`
 
@@ -286,7 +330,26 @@ uses, so status and the gate cannot disagree about a gap:
   stale or whose latest reviews are all `indeterminate`/`unavailable`
   (see `canon-review`), and the `canon review add` step names both. With
   `require_review` on, a `warning:` line counts the in-effect reviews that
-  predate review pinning (0.15).
+  predate review pinning (0.15), checked against the commit each pinned:
+  current, stale (named) and undecidable.
+- **Brief** (0.16) — for each `building`, `verifying` or `shipped`
+  subject, and each `proposed` subject whose newest adopted change has a
+  `proposal.md`, a `brief:` line under it says whether the brief is approved:
+  `brief: approved in <proposal.md> — <the recorded words>`, or
+  `brief: not approved (…)`. Approval is an `Approved:` line in the
+  `proposal.md` of the subject's newest adopted change (the last one
+  adopted): a line that starts with `Approved:` (indent allowed), says
+  something after it, and sits outside HTML comments (`<!-- … -->`,
+  multi-line included) and fenced code blocks (```` ``` ```` or `~~~`),
+  written by the agent once the human answers, as
+  `Approved: <who> <when> — "<the human's words>"`. Fixes and follow-ups
+  live as tasks in the approved change, so a newly adopted change is a
+  new scope: an older change's approval does not cover it. Status reads
+  the line from the change dir under the repo's `openspec` plans sources,
+  in config order (the first source holding the change owns it, a live
+  dir before an archived one; with no `plans:` section, the `openspec`
+  source rooted at the repo that `canon gate task` also falls back to).
+  There is no record kind for it; the file is the record.
 - **Unowned** — scenarios with no `@subject:` tag.
 - **Audits** — how many scenarios are sampled for
   `spec_coverage.require_audit`, confirmed, owed (no audit or
@@ -296,23 +359,54 @@ uses, so status and the gate cannot disagree about a gap:
   one).
 - **Dropped bindings** — `dropped bindings (N):` lists every recorded
   `--drop-attachment` (scenario, paths, reason); `drops[]` in `--json`.
-- **`next:`** — at most five commands, each with a one-line reason; the
+- **Brief overrides** — a `warning:` line per evidence record attested
+  with `canon evidence add --override-reason` while its subject's brief
+  was not approved: what it attests, who, when, the subject and the
+  reason (see `canon-gate`).
+- **`next:`** — at most five steps, each with a one-line reason; the
   rest are counted. Rules, in order: no `canon.yaml` → `canon init`; an
   unreadable one → `canon init --check-config`; a scenario tagged with a
   subject that has no record → `canon subject new <that id>`; no subject
-  at all → `canon subject new`; subjects but no scenario records →
-  `canon inventory sync`. Then per subject, verifying first, then
-  building, specced, proposed, shipped: no scenario → `canon scenario new
-  … --subject <id>`; a missing case → `canon scenario new <surface>.<next
-  nn> … --case <case>`; (building and later) an unevidenced or divergent
-  scenario → `canon evidence add --scenario-id …`; an open blocker →
-  `canon finding close …`; a due, unreviewed, evidenced scenario →
-  `canon review add …` from another session; none of these →
-  `canon subject status <id> <next status>`. Last, unowned scenarios →
-  tag them and `canon inventory sync`. With more than one `specs.roots[]`
-  entry, every suggested `canon scenario new` carries `--project`: the
-  owning root for a missing case, `<root-id>` (the reason lists the
-  roots) for a subject that owns no scenario yet.
+  at all → `canon subject new`; subjects and `.feature` scenarios but no
+  scenario records → `canon inventory sync` (status refreshes the index
+  itself first, so this means the refresh refused on a format violation
+  or a duplicate id, which the sync names). Then per subject, verifying
+  first, then building, specced, proposed, shipped: an unapproved brief
+  (building and later, and proposed once its change has a `proposal.md`)
+  → the human step below, which is then the subject's
+  only step; no scenario → `canon scenario new … --subject <id>` (and, when no
+  `.feature` file holds a scenario yet, `canon feature new` first, unless
+  every subject waits on its brief); a missing case → `canon scenario new
+  <surface>.<next nn> … --case <case>`; (building and later) an
+  unevidenced or divergent scenario → `canon evidence add --scenario-id
+  …` (its reason adds "then `canon gate promote`" only under
+  `write.promote: manual`); an open blocker → `canon finding close …`; a
+  due, unreviewed, evidenced scenario → `canon review add …` from another
+  session; none of these → `canon subject status <id> <next status>`.
+  Last, unowned scenarios → `canon status`, after tagging them in their
+  `.feature` files (status re-indexes the edit; no sync step). With more
+  than one `specs.roots[]` entry, every suggested `canon scenario new`
+  carries `--project`: the owning root for a missing case, `<root-id>`
+  (the reason lists the roots) for a subject that owns no scenario yet.
+- **The one human step.** Every step is the agent's to run except one:
+  a subject whose brief is enforced (its newest change has a
+  `proposal.md` with no `Approved:` line) gets
+  `human: stop and report the brief in <proposal.md>; build and attest nothing for <id> until the human answers (one answer approves brief and policy)`,
+  whose reason names that `proposal.md`, says `canon evidence add`
+  refuses the subject's scenarios and tasks until the line is recorded,
+  and names `canon policy approve --by <the human> --note "<their words>"`.
+  It is the subject's only step, whatever its status: nothing suggests
+  `canon feature new`, `canon scenario new`, `canon evidence add`, a
+  review or a move-on for it before the human answers, and
+  `canon subject status <id> shipped` refuses on the same check. The
+  approval is never assumed. A subject with no brief to answer gets no human step;
+  its `brief:` line says
+  `not approved (no adopted change; advisory, nothing to approve yet)` or
+  ``not approved (change `<id>` has no proposal.md; advisory, nothing to
+  approve yet)`` and nothing is withheld (a `proposed` subject with no
+  `proposal.md`, and a `specced` subject, show no `brief:` line at all). Once nothing blocks, a
+  ship-ready verifying subject gets the agent's own
+  `canon subject status <id> shipped`; status never asks a human to ship.
 
 Status fails closed rather than suggest progress the gate would refuse:
 
@@ -330,19 +424,24 @@ Status fails closed rather than suggest progress the gate would refuse:
 
 ```json
 {
-  "statusVersion": 1,
-  "canonVersion": "0.14.0",
+  "statusVersion": 2,
+  "canonVersion": "0.16.0",
   "policy": { "present": true, "spec_coverage": { "require_evidence": true, "scope": [], "exclude_lanes": [], "require_cases": ["failure"], "require_review": { "scope": ["verifying", "shipped"], "distinct_actor": true, "block_on_findings": true } } },
   "warnings": [],
   "subjects": [
     { "id": "cart", "title": "Cart", "status": "building", "scenarios": 2, "excluded": 0, "evidenced": 2, "divergent": 0,
-      "reviewed": 1, "staleReviews": 0, "unsignedReviews": 0, "reviewDue": true, "openBlockers": 1, "missingCases": [] }
+      "reviewed": 1, "staleReviews": 0, "unsignedReviews": 0, "reviewDue": true, "openBlockers": 1, "missingCases": [],
+      "brief": { "approved": true, "enforced": false, "change": "c-cart", "proposal": "openspec/changes/c-cart/proposal.md", "approval": "Journey 2026-10-11 — \"approved\"" } },
+    { "id": "promo", "title": "Promo", "status": "verifying", "scenarios": 1, "excluded": 0, "evidenced": 1, "divergent": 0,
+      "reviewed": 1, "staleReviews": 0, "unsignedReviews": 0, "reviewDue": true, "openBlockers": 0, "missingCases": [],
+      "brief": { "approved": false, "enforced": true, "change": "c-promo", "proposal": "openspec/changes/c-promo/proposal.md" } }
   ],
   "unowned": ["cart.promo.01"],
   "next": [
-    { "command": "canon finding close --change-id c-cart --round 1 --seq 1 --disposition fixed --resolution-sha <sha> --actor-id <unit> --session-id <session>", "why": "cart: 1 open blocker finding(s) (first: …); fix it, commit, then close it" },
-    { "command": "canon review add --project-id root --scenario-id cart.add.02 --reviewer <reviewer> --actor-id <reviewer> --session-id <review-session> --role reviewer --pin <sha> --original-spec-ref \"<feature file>\"", "why": "cart: 1 of 2 scenario(s) lack a qualifying review; …" },
-    { "command": "canon inventory sync", "why": "1 scenario(s) carry no @subject tag (first: cart.promo.01); …" }
+    { "command": "stop and report the brief in openspec/changes/c-promo/proposal.md; build and attest nothing for promo until the human answers (one answer approves brief and policy)", "why": "promo: its newest adopted change's proposal.md carries no `Approved:` line …", "actor": "human" },
+    { "command": "canon finding close --change-id c-cart --round 1 --seq 1 --disposition fixed --resolution-sha <sha> --actor-id <unit> --session-id <session>", "why": "cart: 1 open blocker finding(s) (first: …); fix it, commit, then close it", "actor": "agent" },
+    { "command": "canon review add --project-id root --scenario-id cart.add.02 --reviewer <reviewer> --actor-id <reviewer> --session-id <review-session> --role reviewer --pin <sha> --original-spec-ref \"<feature file>\"", "why": "cart: 1 of 2 scenario(s) lack a qualifying review; …", "actor": "agent" },
+    { "command": "canon status", "why": "1 scenario(s) carry no @subject tag (first: cart.promo.01); add `@subject:<id>` above each in its .feature file, then check again: …", "actor": "agent" }
   ],
   "nextOmitted": 0
 }
@@ -351,9 +450,22 @@ Status fails closed rather than suggest progress the gate would refuse:
 Each `missingCases` entry is `{ "projectId", "surface", "case" }`: the
 spec root, the `<area>.<surface>`, and the required case it lacks.
 
+`brief` is present for `building`, `verifying` and `shipped` subjects,
+and for a `proposed` subject whose newest adopted change has a
+`proposal.md`. `change` is the newest adopted change (omitted when the
+subject adopts none), `proposal` its `proposal.md` (omitted when no
+`openspec` source holds one), `approval` the text after `Approved:`, and
+`enforced` whether the missing approval blocks (a `proposal.md` exists to
+carry it).
+
+Each `next` entry's `actor` is `agent` (its `command` is a canon command
+line) or `human` (its `command` says what to get from the human).
+
 `policy.spec_coverage` has the shape `canon context --json` prints
 (`null` when absent, `{"invalid": …}` when unusable). `statusVersion`
-changes only when a field changes meaning or is removed.
+changes only when a field changes meaning or is removed. It is `2`
+since 0.16, when `next[].command` stopped always being a command line
+(`actor` tells which); `brief` was added alongside.
 
 `subject new`, `adopt` and `status` write their records directly; the
 human-readable success line ends `— written directly; nothing to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@journeykit/canon",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "canon — harness knowledge substrate. JS launcher: platform detection + native binary resolution.",
   "license": "MIT",
   "type": "module",
@@ -30,9 +30,9 @@
   },
   "dependencies": {},
   "optionalDependencies": {
-    "@journeykit/canon-core-darwin-arm64": "0.15.0",
-    "@journeykit/canon-core-linux-x64": "0.15.0",
-    "@journeykit/canon-core-win32-x64": "0.15.0"
+    "@journeykit/canon-core-darwin-arm64": "0.16.0",
+    "@journeykit/canon-core-linux-x64": "0.16.0",
+    "@journeykit/canon-core-win32-x64": "0.16.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",