@journeykit/canon 0.16.0 → 0.18.0

package/dist/skills/SKILL.src.md

@@ -25,7 +25,7 @@ a feature, a one-line request included. A human is needed once per scope:
   `.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/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.
@@ -36,6 +36,14 @@ a feature, a one-line request included. A human is needed once per scope:
   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.
+- **A follow-up on a shipped subject reopens it.** Reopen it with
+  `canon subject status <id> verifying --reason "<why>" --actor-id <unit>`
+  (no human inside the approved scope; the reason and your id are
+  recorded), add the follow-up as tasks in the approved change's
+  `tasks.md`, then its scenario, evidence and an independent review, and
+  ship again with `canon subject status <id> shipped`, which runs every
+  guard again. `canon status` flags a shipped subject whose gate went red
+  and names the reopen.
 
 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
@@ -44,17 +52,24 @@ 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). Once it is there, stop and report the brief,
+   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`. For a new subject or a scope change, this is
-   where you stop until the human answers (step 1).
+   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).
+   A change that also serves another subject is adopted there too,
+   `canon subject adopt <slug> --subject <other>`: it then belongs to both,
+   and its open blockers gate both.
 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`
@@ -66,7 +81,10 @@ work inside an approved scope, never to the approval itself.
    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.
+   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>`),
@@ -81,12 +99,20 @@ work inside an approved scope, never to the approval itself.
    `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. For a scenario about what
+   ledger) and `canon gate check` re-checks them; the bound copy is the one
+   kept, so the working-tree report itself may be gitignored. 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`.
+   One test run that proves several scenarios is bound once:
+   `canon evidence add --project-id <root-id> --all-scenarios --report <junit|cucumber|swift-testing>:<path> --kind test-run --role implementer --ref "<command>" --actor-id <unit> --session-id <session>`
+   writes one record per indexed scenario owning a case, each with the
+   verdict its own cases show; any refusal writes none. When a new record
+   makes a signed review stale, the add prints the reviewer and the
+   `canon review add … --pin <sha>` that re-pins it; the reviewer looks
+   again before running it.
    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
@@ -95,16 +121,24 @@ work inside an approved scope, never to the approval itself.
    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
+   code and evidence reviews the change. The review session must be able
+   to run the checks it signs off (the build, the tests, the app); a
+   reviewer that cannot run the tests says so and does not sign off. 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 "…"`;
+   `canon finding list --change-id <slug> [--open] [--json]` shows the
+   change's findings (round, seq, severity, disposition, reviewer, summary),
+   so the next seq and the open blockers are one command away;
    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). 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). A reviewer of user-visible
+   (written directly; nothing to promote). Repeat `--scenario-id`, or pass
+   `--scenario-ids-from <file>`, to sign off several scenarios in one
+   call, all or nothing. 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.
@@ -114,17 +148,22 @@ work inside an approved scope, never to the approval itself.
    blocker findings); fix the gap rather than overriding, and finish with
    `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
+   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.
+   the next step. `shipped → verifying` reopens a shipped subject for a
+   follow-up (see the working loop above): it needs `--reason`, and it is
+   refused, naming the brief, when the subject's newest change is not
+   approved.
 
 Every write command says whether the record is final (`written directly`,
 or `staged and promoted in this run`) or staged; only a staged record
@@ -137,13 +176,26 @@ Load only the reference the current step needs.
 ### Setup and provider projection
 
 ```bash
-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 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 and a projection a formatter rewrote; never deletes user files
 ```
 
+`install` and `doctor` end with `owned-paths:`, the globs of every path
+canon writes. Add them to the repo's formatter and linter ignore lists; a
+formatter that rewrites a projection or a ledger record makes canon read
+drift. Specs, `policy.yaml` and the changes are written by hand and are not
+on the list. `doctor` reports a projection whose bytes changed
+but whose content did not as `formatter-rewritten` and names the ignore
+entry to add; a changed file stays `stale`.
+
+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

@@ -105,7 +105,7 @@ format-clean scenario, and `canon status`, `canon gate check`,
 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.
+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
@@ -158,7 +158,7 @@ Fix it and the next command indexes the files (see `canon-inventory`).
 ## 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

@@ -28,7 +28,7 @@ Every violation carries one of these stable, grep-able strings:
 | `malformed-evidence` | A candidate record doesn't parse, is misfiled, or carries an unparseable interim tag. Malformed evidence is no evidence. |
 | `flagged` | The human-only `flagged` overlay is set — never green regardless of passing evidence. |
 | `unevidenced-flip` | `canon gate task <task_id>` was asked to flip a checkbox with no matching, non-`Divergent` evidence record. |
-| `fabricated-evidence` | An evidence note contains a blocklisted marker (`"would pass"`, `"TBD"`, `"n/a"`) or a bare `verified` claim with no attached command result. |
+| `fabricated-evidence` | An evidence note contains a blocklisted marker (`"would pass"`, `"TBD"`, `"n/a"`) standing as a whole word — never inside a path, a file name, a URL or a longer word, so `pack.json/atlas` is not `n/a` — or a bare `verified` claim with no attached command result. `canon evidence add` refuses such a note before writing (`canon evidence add: refused — fabricated-evidence …`, exit 1). |
 | `open-blocker` | With `spec_coverage.require_review` set (and `block_on_findings`, the default), a Finding whose latest version is severity `blocker`, disposition `open`, on a change an in-scope subject adopted. Subject string `<change_id>#<round>.<seq>`. See `canon-review`. |
 | `false-success` | The latest audit record (`canon evidence add --kind audit`) of a scenario says `refuted`: an external evaluator found a counterexample to the claimed success. Always on, regardless of policy or sampling, and takes precedence over any declared faithful verdict; only a newer audit (`confirmed` or `indeterminate`) clears it. The detail names the evaluator, its version, its sha256 and the counterexample paths. |
 
@@ -63,7 +63,7 @@ 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
+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
@@ -77,6 +77,15 @@ 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
@@ -246,19 +255,32 @@ 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
+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 — 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
+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
 ```
 
-A subject with no brief to answer (no openspec source, no adopted change,
-no `proposal.md`) and a scenario no subject owns are unaffected.
+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)
@@ -298,8 +320,9 @@ review waivers: 1 advisory(ies) — not failing the gate:
 The waiver lasts only until the subject's next status write.
 
 `canon subject status <id> shipped` also refuses where a brief exists and
-has no `Approved:` line (the subject's newest adopted change has a
-`proposal.md`; see `canon-subject`), as an `unreviewed-promotion` naming
+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
@@ -317,7 +340,10 @@ scenario) that carry no pins were written before 0.15. Each still names
   `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.
+  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`:
@@ -365,6 +391,8 @@ canon evidence add --scenario-id cart.add.04 --project-id root \
 # a JUnit XML or Cucumber JSON report: also records the matched case + outcome
 canon evidence add ... --report junit:target/nextest/default/junit.xml
 canon evidence add ... --report cucumber:reports/cucumber.json
+# a Swift Testing event stream (swift test --experimental-event-stream-output <path>)
+canon evidence add ... --report swift-testing:.build/events.jsonl
 ```
 
 A case is bound when the scenario id is its OWN: the first
@@ -382,6 +410,12 @@ verdict when ANY bound case failed or was skipped refuses (exit 1). Files
 must be inside the repository, are recorded by relative path, and are
 stored (see Bound evidence stays provable).
 
+A Swift Testing case is named by its display name (`@Test("cart.add.04
+refuses an out-of-stock item")`), else its function name
+(`cart_add_04_refuses()`). A test with a failing issue failed, a skipped
+test was skipped, a test that started and ended without one passed, and
+a test that started and never ended failed.
+
 Strength, weakest first: `attested` (no attachment) < `artifact` (any
 bound file) < `report` (a parsed report whose case passed). The policy
 decides whether the gate cares:
@@ -405,6 +439,55 @@ violation in every mode. Canon still cannot know whether the bound test
 actually exercises the scenario — binding narrows the trust gap, it does
 not close it.
 
+### One report, many scenarios (0.18)
+
+One test run proves many scenarios. Bind it once:
+
+```bash
+canon evidence add --project-id root --all-scenarios \
+  --report junit:target/nextest/default/junit.xml \
+  --kind test-run --ref "cargo nextest run" --role implementer
+```
+
+Each indexed scenario of `--project-id` that owns a case (the rule above)
+gets its own record, with only its own cases. Its verdict comes from
+them: `faithful` when every case passed, `divergent` when one failed,
+`not-applicable` when one was skipped and none failed. `--verdict <v>`
+claims the same verdict for every record instead. A case whose id is not
+indexed is named and skipped (`skipped <id> — not an indexed scenario`);
+a report no indexed scenario owns is refused (exit 2). The records share
+the stored report and every `--artifact`, and the output lists each
+scenario with its verdict on its own line.
+
+It is all or nothing: a claimed `faithful` verdict over a failed case,
+a fabrication marker in `--summary`, an unapproved brief for any
+scenario's subject, or a scenario whose latest record binds a file the
+batch does not refuses the whole batch, and nothing is written.
+`--scenario-id`, `--task`, `--report-case`, `--kind audit`,
+`--drop-attachment` and the approval flags name one subject and are
+refused with `--all-scenarios`.
+
+A task's evidence with `--report` and no `--scenario-id` binds EVERY case
+in the report, so a `faithful` verdict needs all of them to pass.
+
+### A write that makes a review stale says so (0.18)
+
+When new evidence (one record or a batch) supersedes the evidence a
+current pinned review saw, `canon evidence add` prints one line per
+review it makes stale, with the command that re-pins it:
+
+```
+canon evidence add: review by `reviewer-2` of cart.add.01 is now stale (it pinned the evidence this record supersedes); re-pin it: canon review add --project-id root --scenario-id cart.add.01 --reviewer reviewer-2 --actor-id reviewer-2 --role reviewer --pin <HEAD sha> --original-spec-ref specs/kind=feature/area=cart/add.feature
+```
+
+The decision is the gate's own (the same stale-review rule `canon gate
+check` reports). The command repeats the review's reviewer, actor, role,
+session, provenance ref, runtime labels and artifacts, pinned at `HEAD` (`<sha>`
+when the repository has no commit). A record that is only staged says
+the review "goes stale once this evidence is promoted": promote first,
+then re-pin. The reviewer re-reviews before re-pinning; several
+scenarios re-pin in one `canon review add` (see `canon-review`).
+
 ## Bound evidence stays provable (the artifact store)
 
 `canon evidence add --artifact/--report` copies each bound file into
@@ -442,20 +525,29 @@ 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-review`) are checked by the same rule for every CURRENT in-effect
+review: the latest per `(project_id, scenario_id, reviewer)`, less any
+that went stale against its scenario (its spec or evidence pin moved, or
+a review from before pinning is stale at its commit). A stale review is
+superseded — the gate reads the newer review, or reports the missing
+one as `unreviewed-promotion` — so its files are not re-checked, as a
+superseded evidence record's are not. A missing blob whose working-tree
+file still matches is an advisory, listed with the reviewer:
+
+```
+  unstored cart.add.01 reports/cart-badge.png (sha256 9848…, review by `reviewer-2`) is verified against the working tree only
+```
+
+Anything else is `stale-evidence` on the review's scenario, and the
+detail names the review: ``review by `<reviewer>` (actor `<id>`,
+<time>)``.
 
 `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,
-with both digests. It exits `0` whenever it ran (the gate decides whether
-an unstored file matters), `2` when the ledger cannot be read or a write
-fails.
+existing evidence records and current reviews (a superseded review's files are not vaulted): every attachment whose
+working-tree file still matches its digest is copied in, and everything
+else is listed as not stored, with both digests. It exits `0` whenever it
+ran (the gate decides whether an unstored file matters), `2` when the
+ledger cannot be read or a write fails.
 
 ## Effect-aware risk approvals (`risk_tiers`)
 
@@ -489,12 +581,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
@@ -526,6 +625,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

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

@@ -13,7 +13,7 @@ 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
+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
@@ -25,12 +25,43 @@ command. Run `canon inventory sync` when:
   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);
+  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
 
 ```
@@ -66,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
@@ -100,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
@@ -113,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).
 

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

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

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

@@ -135,7 +135,8 @@ fixed finding reopened with `--disposition open` counts as open again.
 ## `canon review add`
 
 ```bash
-canon review add --project-id <root-id> --scenario-id <id> \
+canon review add --project-id <root-id> --scenario-id <id> [--scenario-id <id>]... \
+  [--scenario-ids-from <file|->] \
   --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] \
@@ -143,7 +144,7 @@ canon review add --project-id <root-id> --scenario-id <id> \
   [--artifact <path>]... [--max-artifact-mib <MiB>]
 ```
 
-One attributed Review record for one scenario, joined on
+One attributed Review record per scenario, joined on
 `(project_id, scenario_id)` — both are required because two spec roots
 may carry the same scenario id. Exactly one provenance ref is required.
 `--actor-id` defaults to `canon`; `--session-id` fills `actor.session_id`.
@@ -153,6 +154,18 @@ 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`.
 
+### Several scenarios in one call (0.18)
+
+`--scenario-id` is repeatable, and `--scenario-ids-from <file>` (`-` reads
+stdin) adds one id per line; `#` starts a comment and blank lines are
+skipped. One reviewer, pin, provenance ref and set of artifacts cover
+every review; each review pins its own scenario and evidence, and each
+gets its own `pinned` and `wrote` line. The artifacts are stored once.
+It is all or nothing: a scenario with no record, or a line in the file
+that is not a scenario id, refuses the call (exit 2) and writes no review.
+This is also the batch re-pin after `canon evidence add` reports reviews
+it made stale (see `canon-gate`).
+
 ### What the reviewer looked at (artifacts)
 
 `--artifact <path>` (repeatable) binds a file the reviewer looked at — a
@@ -173,19 +186,25 @@ The field is absent when no `--artifact` is given. `review add` prints
 .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"):
+`canon gate check` re-checks every file bound to a current in-effect
+review (the latest per `(project_id, scenario_id, reviewer)`, unless it
+went stale against its scenario) by the evidence rule (see `canon-gate`,
+"Bound evidence stays provable"). A missing blob whose working-tree file
+still matches is an advisory naming `canon evidence vault`, which stores
+it back. A missing blob with a changed or missing working-tree file, or
+an altered blob, is `stale-evidence` on the review's scenario, naming
+the review:
 
 ```
-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>`
+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: <other 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.
+the ones checked. A review that went stale (its scenario's spec or
+evidence moved since) is not checked either: it no longer counts, and the
+scenario's newer review is the one whose files are checked. Canon binds
+and re-checks bytes only; it never compares images or judges what a
+screenshot shows.
 
 ### What the review saw (pins)
 

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

@@ -104,11 +104,12 @@ canon query --kind trajectory --json
 
 canon exposes layered `stg_`/`int_`/`mart_` query views; `canon report`
 builds its numbers from the `mart_` views. Those read ONLY local roots
-— the git ledger and a LOCAL `.canon/r2` parquet mirror. `canon report`
+— the git ledger, the sqlite `hot` db file (local, no credential; read
+since 0.18) and a LOCAL `.canon/r2` parquet mirror. `canon report`
 never opens a live DB connection or the live bucket, so:
 
-- Kinds routed to `hot` (sqlite/postgres) do NOT appear in `canon
-  report`.
+- Kinds routed to a postgres `hot` rung do NOT appear in `canon
+  report`; kinds routed to `canon init`'s default sqlite `hot` rung do.
 - Kinds routed to `cold` (s3) appear only if a local `.canon/r2` mirror
   has been separately materialized — there is no automatic sync.
 
@@ -192,6 +193,29 @@ write (promote: manual)`, or `[FAIL] write: …`. `canon gate promote` still
 works under `auto` and is idempotent: with nothing staged it prints
 `nothing staged` and exits `0`.
 
+## Harnesses: the `skills:` section
+
+`canon.yaml`'s `skills:` section names the harnesses the canon skill is
+installed for (0.17):
+
+```yaml
+skills:
+  providers: [claude, codex]   # any of claude, codex, omp, pi; [] for none
+```
+
+`canon init` writes it: on a terminal it asks, with the harnesses whose
+`.claude`, `.codex`, `.omp` or `.pi` directory exists checked;
+`--providers a,b` (or `none`) answers without asking; with neither it takes
+the detected ones, and with none detected it writes only a commented example
+and installs nothing. `.agents` alone never selects Codex. `canon skills
+install|check|doctor` follow the section; `canon skills install
+--providers=<list>` rewrites it in place. Without the section they use the
+install lock's providers, then the detected ones; nothing undetected is ever
+added. A present section that is not this shape, or names another harness,
+fails those commands (exit `1`), and `canon init --check-config` reports
+`[PASS] skills (providers: …)`, `[not configured] skills (…)`, or
+`[FAIL] skills: …`.
+
 ## The scenario index
 
 `canon inventory sync` materializes one `Scenario` record per
@@ -207,7 +231,7 @@ that no `.feature` file of it declares any more. The reader then runs
 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
+canon status: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
 ```
 
 A deleted scenario is not erased: `canon inventory sync` — and a reader's

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

@@ -103,7 +103,7 @@ this subject and domain — the exact memory step 2 retrieves next time.
 
 ## Status lifecycle + the shipped evidence gate
 
-`canon subject status <id> <state> [--override-reason <text>] [--actor-id <id>]`
+`canon subject status <id> <state> [--override-reason <text>] [--reason <text>] [--actor-id <id>]`
 performs a policy-gated transition.
 The legal chain:
 
@@ -111,9 +111,10 @@ The legal chain:
 proposed → specced → building → verifying → shipped
 ```
 
-plus **any state → retired** (a subject can be retired from anywhere).
-Any other transition is rejected by failure class, exits 1, and leaves
-the record UNCHANGED (fail closed).
+plus **shipped → verifying** to reopen a shipped subject (with
+`--reason`, below) and **any state → retired** (a subject can be retired
+from anywhere). Any other transition is rejected by failure class, exits
+1, and leaves the record UNCHANGED (fail closed).
 
 ```bash
 canon subject status subject-domain-loop specced
@@ -148,27 +149,39 @@ 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
+**The brief (0.16, 0.17):** `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:
+newest adopted change has a canon `.canon/changes/<change>/brief.md`
+with no `Approved:` line outside HTML comments and code fences, or has no
+canon `brief.md` yet but comes from an external openspec plan with a
+`proposal.md` under the plan sources. 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: unreviewed-promotion demo-subject — verifying → shipped: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line; a human must answer the brief, and only from that answer the agent will record their words as `Approved: <who> <when> — "<their words>"` in .canon/changes/c-demo/brief.md
 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
 ```
 
+For an external change with no canon brief yet, the reason reads
+``.canon/changes/<c>/brief.md does not exist yet: change `<c>` comes from
+the external plan <proposal>, which canon reads and never edits, so its
+approval lives in that canon file`` and the agent will ``create
+.canon/changes/<c>/brief.md holding a `Source: <proposal>` line and
+record their words there as `Approved: <who> <when> — "<their words>"` ``.
+
 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.
+answer (no adopted change, or a newest change with neither a canon
+`brief.md` nor an external `proposal.md`), the move is not refused: it
+prints ``canon subject status: advisory: <id>'s brief is not approved —
+its newest adopted change `<c>` has no brief (no
+.canon/changes/<c>/brief.md, no openspec proposal.md), so there is no
+brief to answer and shipping is not refused`` (or `— <id> adopts no
+change, so …`), 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,
@@ -230,6 +243,39 @@ raised later, a scenario tagged later) still fails the gate. Without
 `require_review`, nothing is printed and nothing changes, except that
 `shipped` still runs the brief check above.
 
+### Reopening a shipped subject (0.18)
+
+A follow-up on a shipped subject (a fix, a review round, a scenario its
+gate now misses) reopens it: reopen, add tasks to the approved change,
+scenario, evidence, review, ship.
+
+```bash
+canon subject status demo-subject verifying \
+  --reason "follow-up: the retry path leaks a file handle" --actor-id impl
+```
+
+```
+canon subject status: reopened `demo-subject` from shipped, recorded by `impl`: follow-up: the retry path leaks a file handle; add the follow-up as tasks in its approved change `c-demo`, then scenario, evidence and review; shipping again runs every guard
+canon subject status: demo-subject → verifying — written directly; nothing to promote
+```
+
+- `--reason "<one line>"` is required for `shipped → verifying` and
+  refused on any other transition (exit 2, as is a blank one). The new
+  record carries it with the actor and the change the work goes into:
+  `reopen: { reason: …, change: c-demo, actor: { agent_id: impl } }`. The
+  next status write clears it, as it clears a waiver.
+- Inside the approved scope it needs no human: the subject's newest
+  adopted change's brief is approved, or there is no brief to answer.
+  Otherwise it refuses, exit 1, naming the brief to approve, and
+  `--override-reason` does not waive it:
+  ``unreviewed-promotion demo-subject — shipped → verifying: reopening needs the approved scope, and the brief is not approved — .canon/changes/c-next/brief.md has no `Approved:` line; …``.
+- The review guard does not run on a reopen (it prints `skipped … — a
+  reopen moves the subject back to fix its gaps; shipping again runs
+  it`). `verifying → shipped` afterwards runs every guard above again.
+- `canon status` flags a shipped subject whose gate went red (whatever
+  `verifying → shipped` would now refuse it on) and its only step is
+  this reopen.
+
 ## Adopt flow
 
 Planning docs written outside canon become change/task records via
@@ -249,37 +295,63 @@ 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
-the side that lacks the link, so rerunning it on a linked pair writes
-nothing and exits `0`.
+`adopt` adds the subject to the change's `subject_ids` and the change 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 the side that lacks the link, so rerunning it on a linked
+pair writes nothing and exits `0`.
+
+A change may belong to several subjects (0.18). Adopting it under a
+second subject adds that subject, never re-points the change, and says
+so:
+
+```
+canon subject adopt: linked change `refactor-core` to subject `editing` as well; the change now belongs to `perception` and `editing` — written directly; nothing to promote
+```
+
+Every reader joins a subject to its changes from both sides (the
+subject's `change_ids`, and every change whose `subject_ids` names it):
+the open-blocker rule, the status guard, `canon status`, the brief and
+the evidence refusal. An open blocker on a shared change gates each
+subject it belongs to. A change written before 0.18 names one subject as
+`subject_id`; it reads, and `canon query --kind change --json` shows it,
+as a one-element `subject_ids`.
 
 The two records cannot be written atomically, so the subject is written
-first: its `change_ids` is what the gate reads a subject's adopted
-changes from (`open-blocker`, the status guard), so a half-done adoption
-still has that change's open blockers counted. If the change write then
-fails, `adopt` exits `2`, names the subject that now lists the change,
-and prints `canon subject adopt <change_id> --subject <id>` to complete
-it.
+first: a half-done adoption still has that change's open blockers
+counted. If the change write then fails, `adopt` exits `2`, names the
+subject that now lists the change, and prints `canon subject adopt
+<change_id> --subject <id>` to complete it.
 
 ### Starting a new change: `canon change new`
 
-For a change that does not exist yet, one command scaffolds it and
-records it adopted:
+For a change that does not exist yet, one command writes it and records
+it adopted:
 
 ```bash
 canon change new add-login --subject auth --title "Add login"
 ```
 
-- **Writes** `openspec/changes/<slug>/proposal.md` (the title is its
-  `## Why`, which imports as the change summary) and `tasks.md` (no rows
-  yet, so the change imports as `proposed`), under the repo's first
-  `openspec` plans source. `canon init` configures that source
-  (`{dialect: openspec, root: .}`), so `canon.yaml` needs no edit.
-- **Reads** the files with the same `openspec` adapter `canon ingest
+```
+canon change new: wrote .canon/changes/add-login/brief.md
+canon change new: wrote .canon/changes/add-login/tasks.md
+canon change new: recorded change `add-login` adopted into subject `auth` — written directly; nothing to promote
+```
+
+- **Writes** canon's own change dir, `.canon/changes/<slug>/`:
+  `brief.md` (`# <title>`, `## Why` holding the title, which imports as
+  the change summary, `## What Changes` with a comment saying what goes
+  there, and a comment naming where the human's `Approved:` line goes,
+  so the file starts unapproved) and `tasks.md` (no rows yet, so the
+  change imports as `proposed`; the openspec checkbox row grammar).
+  `.canon/changes/` is canon's native plan source: every plan reader
+  reads it with no `plans:` entry, so `canon.yaml` needs no edit and no
+  external plans source is needed (see `canon-plan-import`).
+- **Reads** the files with the native `canon` plan adapter `canon ingest
   plans` uses, then **records** the change already adopted, through the
-  same write as `canon subject adopt`.
+  same write as `canon subject adopt`. Its records carry the actor
+  `canon-plan-import-canon` (canon-written); an external openspec
+  change's carry `canon-plan-import-openspec`.
 - **What a failure leaves behind.** The files are staged under `.canon/`
   and the change dir is moved into place only once they parse. A failure
   before any record is written (staging, publishing the dir, or the
@@ -291,14 +363,23 @@ canon change new add-login --subject auth --title "Add login"
   plans && canon subject adopt <slug> --subject <id>`, which completes
   the link and is safe to rerun.
 - **Refuses** with exit `2`, writing nothing, when the subject does not
-  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.
+  exist, or when the slug already has a `.canon/changes/<slug>` dir
+  (active or under `.canon/changes/archive/`) or a `change` record.
 
 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.
 
+A change from an external plan (an openspec change listed under
+`plans.sources`, imported by `canon ingest plans` and adopted with
+`canon subject adopt`) gets its brief as a canon file too:
+`.canon/changes/<change>/brief.md` holding a `Source: <path>` line that
+points at the external document and, once the human answers, the
+`Approved:` line. Canon never edits the external document. Such a
+pointer `brief.md` is not a change of its own: the native reader skips
+it, so the external source keeps the change, its summary and its tasks.
+
 ## Where are we: `canon status`
 
 ```bash
@@ -332,24 +413,42 @@ uses, so status and the gate cannot disagree about a gap:
   `require_review` on, a `warning:` line counts the in-effect reviews that
   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`
+- **Brief** (0.16, 0.17) — 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
+  brief (a canon `brief.md`, or an external `proposal.md`), a `brief:`
+  line under it says whether the brief is approved:
+  `brief: approved in <brief> — <the recorded words>`, or
+  `brief: not approved (…)`. Approval is an `Approved:` line in
+  `.canon/changes/<change>/brief.md` for the subject's newest adopted
+  change (the last one adopted; a live dir before an archived one), and
+  only there: 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).
+  new scope: an older change's approval does not cover it. A change from
+  an external plan has its brief in the same canon file, with a
+  `Source: <path>` line pointing at the external document; an `Approved:`
+  line inside an external `proposal.md` is not read. Before that canon
+  file exists, an external openspec `proposal.md` under the plan sources
+  (the first source holding the change; with no `plans:` section, the
+  `openspec` source rooted at the repo that `canon gate task` also falls
+  back to) still makes the brief one to answer, and the line reads
+  ``brief: not approved (.canon/changes/<c>/brief.md does not exist yet:
+  change `<c>` comes from the external plan <proposal>, which canon reads
+  and never edits, so its approval lives in that canon file)``. With a
+  canon brief and no line it reads
+  ``brief: not approved (<brief> has no `Approved:` line)``.
   There is no record kind for it; the file is the record.
+- **Red shipped subject** (0.18) — a `shipped` subject that the
+  `verifying → shipped` guard would now refuse, by the guard's own checks
+  (owned scenarios, verdicts, required cases, audits, and, where
+  `require_review` covers `shipped`, reviews and open blockers under
+  `block_on_findings`; a gap its waiver recorded is not counted), prints
+  ``gate: red — <n> <class> (first: <subject>), …; reopen with `canon subject status <id> verifying --reason "<why it reopens>" --actor-id <unit>` ``,
+  carries `red: [...]` in `--json`, and that reopen is its only `next:`
+  step. Open blockers count against every subject a change belongs to.
 - **Unowned** — scenarios with no `@subject:` tag.
 - **Audits** — how many scenarios are sampled for
   `spec_coverage.require_audit`, confirmed, owed (no audit or
@@ -372,7 +471,7 @@ uses, so status and the gate cannot disagree about a gap:
   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`)
+  (building and later, and proposed once its change has a brief)
   → 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
@@ -389,12 +488,20 @@ uses, so status and the gate cannot disagree about a gap:
   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>"`.
+  a subject whose brief is enforced (its newest change's canon
+  `brief.md` has no `Approved:` line, or it has no canon `brief.md` yet
+  and comes from an external openspec `proposal.md`) gets
+  `human: stop and report the brief in <brief>; build and attest nothing for <id> until the human answers (one answer approves brief and policy)`,
+  where `<brief>` is the canon `brief.md`, or the external `proposal.md`
+  when no canon brief exists yet. Its reason reads ``<id>: <why
+  unanswered> (an older change's approval does not cover a new scope),
+  and the approval is never assumed: `canon evidence add` refuses <id>'s
+  scenarios and tasks until it is recorded; once the human answers,
+  <record> and run `canon policy approve --by <the human> --note "<their
+  words>"` ``, where `<record>` is ``record their words as `Approved: <who>
+  <when> — "<their words>"` in <brief>``, or, for an external change,
+  ``create <brief> holding a `Source: <proposal>` line and record their
+  words there as `Approved: <who> <when> — "<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
@@ -402,9 +509,9 @@ uses, so status and the gate cannot disagree about a gap:
   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
+  ``not approved (change `<id>` has no brief; 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
+  brief, 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.
 
@@ -424,21 +531,21 @@ Status fails closed rather than suggest progress the gate would refuse:
 
 ```json
 {
-  "statusVersion": 2,
-  "canonVersion": "0.16.0",
+  "statusVersion": 3,
+  "canonVersion": "0.17.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": [],
-      "brief": { "approved": true, "enforced": false, "change": "c-cart", "proposal": "openspec/changes/c-cart/proposal.md", "approval": "Journey 2026-10-11 — \"approved\"" } },
+      "brief": { "approved": true, "enforced": false, "change": "c-cart", "brief": ".canon/changes/c-cart/brief.md", "briefExists": true, "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" } }
+      "brief": { "approved": false, "enforced": true, "change": "c-promo", "brief": ".canon/changes/c-promo/brief.md", "briefExists": false, "source": "openspec/changes/c-promo/proposal.md" } }
   ],
   "unowned": ["cart.promo.01"],
   "next": [
-    { "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": "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: .canon/changes/c-promo/brief.md does not exist yet: change `c-promo` comes from the external plan openspec/changes/c-promo/proposal.md, which canon reads and never edits, so its approval lives in that canon file (an older change's approval does not cover a new scope), and the approval is never assumed: … once the human answers, create .canon/changes/c-promo/brief.md holding a `Source: openspec/changes/c-promo/proposal.md` line and record their words there as `Approved: <who> <when> — \"<their words>\"` and run `canon policy approve --by <the human> --note \"<their words>\"`", "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" }
@@ -451,21 +558,29 @@ 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).
+and for a `proposed` subject whose newest adopted change has a brief (a
+canon `brief.md` or an external `proposal.md`). `change` is the newest
+adopted change (omitted when the subject adopts none); `brief` its canon
+`.canon/changes/<change>/brief.md`, the one file the approval is read
+from (omitted when the change has no brief to answer); `briefExists`
+(always present) whether that file exists (`false` for an external
+change whose canon brief is still to be created); `source` the external
+plan document the change comes from (the canon brief's `Source:` line,
+or, before that file exists, the external `proposal.md`; omitted for a
+canon-written change); `approval` the text after `Approved:`; and
+`enforced` whether the missing approval blocks (a brief exists to
+answer). The 0.16 `proposal` field is gone.
 
 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. It is `2`
-since 0.16, when `next[].command` stopped always being a command line
-(`actor` tells which); `brief` was added alongside.
+changes only when a field changes meaning or is removed. It became `2`
+in 0.16, when `next[].command` stopped always being a command line
+(`actor` tells which), and `brief` was added alongside. It is `3` since
+0.17, when `brief.proposal` was removed: the canon `brief.md` is
+`brief.brief`, with `briefExists` and `source`.
 
 `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.16.0",
+  "version": "0.18.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.16.0",
-    "@journeykit/canon-core-linux-x64": "0.16.0",
-    "@journeykit/canon-core-win32-x64": "0.16.0"
+    "@journeykit/canon-core-darwin-arm64": "0.18.0",
+    "@journeykit/canon-core-linux-x64": "0.18.0",
+    "@journeykit/canon-core-win32-x64": "0.18.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",