@journeykit/canon 0.24.1 → 0.25.0

package/dist/skills/SKILL.src.md

@@ -23,7 +23,8 @@ a feature, a one-line request included. A human is needed once per scope:
   the one thing you never assume, even when the human said they cannot
   answer until you report: the brief is that report. The one answer
   approves the brief and the policy, `.canon/policy.yaml`, which is what
-  the gate grades the work against. Record it only from the human's answer:
+  the gate grades the work against. The human may also approve it on the `canon dashboard` briefs page; you never use that form.
+  Record it only from the human's answer:
   `canon brief approve --change-id <slug> --by <the human> --note "<their words>"`.
   Never edit the policy to make the gate pass: a policy that differs from
   the approved one fails closed (`POLICY_CHANGED_SINCE_APPROVAL`, not
@@ -31,6 +32,16 @@ a feature, a one-line request included. A human is needed once per scope:
   approval is not approved (`BRIEF_CHANGED_SINCE_APPROVAL`): it needs a new
   answer. The ship guard and `canon evidence add` refuse an unapproved or
   edited brief, but those are backstops: the stop itself is at step 1.
+- **Approval is scoped.** Evidence for a scenario needs the approval of the
+  changes its `@flow:<change>.<F-id>` tags name, so a new unapproved change
+  on a live subject waits on its own scenarios only; `change new` and
+  `subject adopt` warn when the subject is live. `canon subject unadopt
+  <change> --subject-id <id>` takes a draft change back off (refused once
+  approved). The subject's scope is its newest adopted change, walking back
+  past pending drafts (brief not approved, no scenario of the subject tagged
+  `@flow:<change>.*`): reopen, evidence and ship read the newest approved or
+  tagged change, and the transition prints one line naming every draft set
+  aside; a draft a scenario is tagged for blocks until it is approved. → `reference/canon-subject.md`
 - **Inside an approved scope, never stop for a human.** Fixes, follow-ups,
   review rounds and re-reviews stay in the approved change (never
   `canon change new`: a new change is a new scope) and go straight on: scenario,
@@ -50,7 +61,7 @@ a feature, a one-line request included. A human is needed once per scope:
 1. **Brief.** The planner writes the PRD brief (`.canon/changes/<slug>/brief.md`), checks it with `canon brief check`, and stops for the human. → `reference/role-planner.md`
 2. **Subject.** `canon subject new`, then `canon change new` (`--kind chore` for work that alters no behavior); the change writes the brief skeleton. → `reference/role-planner.md`
 3. **Scenarios.** `canon scenario new --flow <F-id> --case <case>` per behavior of a flow step, failure paths (`--case failure`) included. → `reference/role-implementer.md`
-4. **Units.** Split the work; each unit has its own actor id and session id, passed on everything it records. A unit never attests another unit's work.
+4. **Units.** Split the work; one unit is one flow step's slice with a named verify command, and each unit has its own actor id and session id, passed on everything it records. A unit never attests another unit's work.
 5. **Implement.** Code with tests named by scenario id (`game.run.01: …`). → `reference/role-implementer.md`
 6. **Evidence.** `canon evidence add` binds the test run to its scenarios. → `reference/role-implementer.md`
 7. **Independent review.** A different session, a separate process with its own session id, that can run the checks it signs off, records `canon finding add` and `canon review add`. Every change. → `reference/role-reviewer.md`
@@ -135,10 +146,10 @@ Load only the reference the current step needs.
 ```bash
 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                         # follows canon.yaml skills.providers (else the install lock's, else the detected ones; none detected installs nothing); prunes projected files the bundle no longer ships when their bytes match the lock, keeps a modified one and reports `kept:`
 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, incl. a stray canon projection for an unselected provider and a projection a formatter rewrote; never deletes user files
+canon skills check                           # read-only drift check; exit 1 (SKILLS_DRIFT) names each orphan, a projected file the bundle no longer ships
+canon skills doctor                          # diagnostics, incl. a stray canon projection for an unselected provider and a projection a formatter rewrote, and `orphan:` lines for projected files the bundle no longer ships; never deletes user files
 ```
 
 `install` and `doctor` end with `owned-paths:`, the globs of every path
@@ -155,6 +166,13 @@ never by assuming a default. The projection is a read-only copy: Claude
 
 ### Route by task
 
+- **Fix a bug:** the approved change if there is one, else the planner (`canon change new`); first a failing run of the scenario (`canon scenario new --case failure`, then `canon evidence add`), then the fix. `reference/role-implementer.md`.
+- **Add or change a feature:** `canon subject new`, `canon change new`, then the brief. `reference/role-planner.md`.
+- **Pure refactor, dependency, build, CI or infra:** `canon change new <slug> --subject-id <id> --kind chore`; data or interface changes are not chores. `reference/role-planner.md`.
+- **Review someone's change:** `CANON_ROLE=reviewer`, `canon brief check --change-id <slug>`. `reference/role-reviewer.md`.
+- **Resume:** `canon status --json`, then follow `meta.next`. `reference/role-orchestrator.md`.
+- **Plan more work on a live subject:** `canon change new <slug> --subject-id <id>` (it warns until the brief is approved; `canon subject unadopt` parks a draft). `reference/canon-subject.md`, `reference/role-planner.md`.
+- **Upgrade canon in a repo:** `canon migrate --dry-run`. `reference/role-orchestrator.md`.
 - **Your role's steps:** `reference/role-planner.md`, `role-implementer.md`, `role-reviewer.md`, `role-orchestrator.md`.
 - **Where the repo stands, subjects and changes:** `reference/canon-subject.md` (`canon status`, `canon subject new|adopt|status`, `canon change new`).
 - **Write or reorganize `.feature` specs:** `reference/canon-authoring.md` before editing; use the scaffold.

package/dist/skills/reference/brief-harden.md

@@ -15,6 +15,8 @@ brief has none of them: harden its Invariants and Checks instead.
 - Each step reads sees → does → becomes, and names who and what state it starts from.
 - Acceptance states, per step, what must be observable and which failure path is covered (invalid input, empty state, interrupted, repeated, denied).
 - Step detail holds rules, states and edge cases of that step only; a rule that spans steps is stated once, where it first applies.
+- Intent states current behavior and Outcome the desired behavior; interfaces are described by behavior (inputs, outputs, errors); no file path, line number or function name stands in a section that decides the work (a `Source:` line may).
+- A flow step is one unit an implementer can verify with one named command; split a step that needs two.
 - Acceptance writes no scenario ids: scenarios do not exist yet and point at steps.
 
 ## NEVER

package/dist/skills/reference/brief-shape.md

@@ -20,6 +20,7 @@ marker, never by heading text.
 - `canon brief check --json`: each finding names the rule, section key, line and hint.
 - Every section present once, in order, with its marker; no `<!-- canon:hint … -->` comment left; no `TODO`/`TBD`; no empty section (write `None.` where nothing applies).
 - The flow is a numbered list with ids `F1`, `F2`, … each reading sees → does → becomes.
+- Intent describes what the product does today and Outcome what is true after; leftover implementation paths belong in a `Source:` line or nowhere.
 - A chore's category is exactly one of `refactor`, `dependency`, `build`, `ci`, `infra`; its invariants and checks say something.
 - A `canon:waive <rule-id> <section-key> "<reason>"` comment is well formed with a real reason.
 

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

@@ -293,7 +293,7 @@ line, was edited after its approval (`BRIEF_CHANGED_SINCE_APPROVAL`), 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
+`canon-subject`; which changes a scenario answers to is scoped by its `@flow:<change>.<F-id>` tags, described there). The subjects are the scenario's `@subject` owner for
 `--scenario-id`, and every subject adopting the task's change for
 `--task`:
 
@@ -354,7 +354,8 @@ review waivers: 1 advisory(ies) — not failing the gate:
 The waiver lasts only until the subject's next status write.
 
 `canon subject status <id> --to shipped` also refuses where a brief exists and
-is not approved (the subject's newest adopted change has a canon
+is not approved (the subject's scope, its newest adopted change walking back past pending drafts
+no scenario is tagged `@flow:<change>.*` for, has a canon
 `brief.md` with no `Approved:` line or one the brief's text no longer
 matches, or an external `proposal.md` and no canon `brief.md` yet;
 see `canon-subject`), as an `unreviewed-promotion` naming

package/dist/skills/reference/canon-report-dashboard.md

@@ -115,9 +115,6 @@ canon report --snapshot /tmp/canon-snap
 Serves the dashboard web app locally, pointed at a real snapshot:
 
 ```bash
-# build the app once
-bun install && bun run --cwd packages/dashboard build
-
 canon dashboard                       # regenerates a fresh snapshot every run, serves it
 canon dashboard --snapshot /tmp/canon-snap --port 8080
 ```
@@ -129,8 +126,32 @@ canon dashboard --snapshot /tmp/canon-snap --port 8080
   `manifest.json` (a separately generated snapshot, or a downloaded CI
   artifact) — never silently regenerated over it. If it has no
   `manifest.json`, one is generated there once.
-- Prints the URL to open, then serves until Ctrl-C. If the app is not
-  built, `canon dashboard` fails with the exact build command to run.
+- Runs in any repo: the released binary carries the app (in canon's own
+  checkout a built `packages/dashboard/dist` is used instead). It prints the
+  panels URL and a briefs URL (`/briefs.html`), then serves until Ctrl-C.
+  A taken port fails with `DASHBOARD_PORT_IN_USE`: pass `--port <n>` or
+  `--port 0`.
+- Without the `duckdb` CLI on `PATH` the server still runs; the panels page
+  says why there is no snapshot and how to get one (it never shows demo
+  data), and the briefs page works regardless.
+
+### The briefs page (where a human approves briefs)
+
+`/briefs.html` lists every live change whose brief awaits the human (no
+`Approved:` line, or edited since) with its intent, outcome, flow steps,
+acceptance, questions and assumptions, and its `canon brief check`
+blockers and advisories. The human types their name and their answer and
+clicks Approve: that records exactly what `canon brief approve --change-id
+<id> --by <name> --note <text>` records, the `Approved:` line bound to the
+brief digest and the policy approval. It is refused when the brief changed
+after the page loaded (`BRIEF_CHANGED_SINCE_PAGE_LOAD`: reload) or while it
+has blockers (`BRIEF_HAS_BLOCKERS`). The server is localhost only and
+refuses requests from other origins (`DASHBOARD_ORIGIN_REFUSED`).
+
+For an agent the human stop is unchanged: when clean briefs are waiting,
+tell the human they can approve them in `canon dashboard` (briefs page) or
+answer in chat. An agent never clicks Approve or fills the form, and runs
+`canon brief approve` only from the human's own words.
 
 The dashboard renders SEVEN panels — trust matrix, session costs, role
 memory, flywheel funnel, review burn-down, review rounds, review totals.

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

@@ -73,8 +73,16 @@ canon finding add --change-id <c> --round <n> --seq <n> \
   [--reviewed-sha <sha>] [--file-ref path/to/file.rs:120-134] [--scenario-id <id> …] [--actor-id <id>] [--session-id <id>]
 canon finding close --change-id <c> --round <n> --seq <n> \
   --disposition fixed --resolution-sha <sha> [--session-id <id>]   # or rejected / deferred / open
+canon finding close --change-id <c> --round <n> --seq <n> \
+  --disposition rejected|deferred --reason "<why, one line>"
 ```
 
+`--reason` is required for `rejected` and `deferred` (refused with
+`FINDING_REASON_REQUIRED` otherwise) and optional for `fixed`. It is stored
+on the closing version, shown by `finding list` as `[reason: …]` and carried
+in the JSON. Give the reason when you reject or defer: it is the only record
+of why the finding was not fixed.
+
 `--scenario-id` (repeatable, each a scenario the index knows; refused with
 `FINDING_UNKNOWN_SCENARIO` otherwise) names the scenarios the finding is
 about. After a `fixed` close, fresh evidence for those scenarios alone
@@ -122,14 +130,18 @@ found it: `--introduced-by self` is a usage error (exit 2) that points at
 
 Severity is the reviewer's own judgement, never a score canon derives.
 
+Write a review's or finding's `--summary` as prose that also names the blast
+radius: what else the change touches that the checks do not exercise. It is
+text in the summary, not a field.
+
 ### Dispositions
 
 | Disposition | Meaning |
 |---|---|
 | `open` | Raised and not yet dealt with. The default on `finding add`; `finding close --disposition open` reopens. |
 | `fixed` | Fixed by a commit. Requires `--resolution-sha <sha>` naming a commit this repo holds; only `fixed` may carry one. |
-| `rejected` | The reviewer's point was considered and declined. |
-| `deferred` | Accepted, but postponed to later work. |
+| `rejected` | The reviewer's point was considered and declined. Needs `--reason`. |
+| `deferred` | Accepted, but postponed to later work. Needs `--reason`. |
 
 ### How findings fold
 

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

@@ -260,7 +260,7 @@ skills:
 `--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
+install|check|doctor` follow the section; `install` prunes projected files the bundle no longer ships when their bytes match the lock (a modified one stays, reported as `kept:`), `check` exits 1 (`SKILLS_DRIFT`) naming each orphan and `doctor` prints `orphan:` lines; `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,

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

@@ -159,7 +159,7 @@ exits 1, and the status stays `verifying`. `retired` is not gated.
 **The brief (0.16, 0.17, 0.19):** `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 canon `.canon/changes/<change>/brief.md`
+scope (its newest adopted change, except pending drafts, see below) has a canon `.canon/changes/<change>/brief.md`
 with no `Approved:` line outside HTML comments and code fences, whose
 `Approved:` line carries a digest the brief's text no longer matches
 (`BRIEF_CHANGED_SINCE_APPROVAL`; the brief was edited after the human
@@ -204,6 +204,30 @@ scenario whose `@subject` owner, or a task whose change
 an adopting subject, has an enforced, unapproved brief, through the same
 check; see `canon-gate`.
 
+**Approval is scoped to the scenarios a change names.** The evidence
+refusal asks the approval of each change the scenario's `@flow:<change>.<F-id>`
+tags name. An untagged scenario answers to the subject's newest adopted
+change whose brief carries an `Approved:` line; if no adopted change ever
+did, a scenario with evidence recorded before the subject first adopted a
+change (and without a brief override) needs no brief, and one without
+answers to the newest adopted change. A task answers to its own
+change. So planning the next change for a `building`, `verifying` or
+`shipped` subject does not freeze re-verification of its existing
+scenarios; scenarios written for the new change (`canon scenario new
+--flow <F-id>` tags them) wait for its approval. The ship guard above is
+unchanged, except for a pending draft: the subject cannot ship until its
+scope is approved, where the scope is found walking the adopted changes from
+the newest back: a change whose brief was never approved and that no scenario
+of the subject is tagged `@flow:<change>.*` for is a pending draft and is
+skipped; the first approved or tagged change is the scope. A tagged unapproved
+draft anywhere above the newest approved change therefore blocks. The reopen
+and ship transitions print one line naming every change set aside (stderr, and
+`meta.warnings` with `--json`): ``<change> is a pending draft (brief not
+approved, no scenario tagged `@flow:<change>.*`): not part of this transition,
+which reads the subject's newest approved or tagged change``, and `canon status`
+marks them "not yet part of the subject's scope" (`pendingDrafts` in JSON)
+while still asking the human to answer a draft's brief.
+
 ### The review guard (`spec_coverage.require_review`, opt-in)
 
 When `.canon/policy.yaml` sets `spec_coverage.require_review` (see
@@ -279,8 +303,10 @@ canon subject status: demo-subject → verifying — written directly; nothing t
   records the change the work goes into:
   `reopen: { reason: …, change: c-demo, actor: { agent_id: impl } }`. The
   next status write clears both, 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.
+- Inside the approved scope it needs no human: the subject's scope (its
+  newest adopted change, walking back past pending drafts no scenario is
+  tagged for) has an approved brief, 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; …``.
@@ -345,6 +371,31 @@ 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 <id>` to complete it.
 
+`canon change new <slug> --subject-id <S>` and `canon subject adopt
+<change> --subject-id <S>` print a warning on stderr, and in JSON
+`meta.warnings`, when `<S>` is `building`, `verifying` or `shipped` and the
+change's brief is not approved. The warning says the subject's existing
+scenarios keep accepting evidence and the subject can still be reopened and
+shipped for its approved scope while no scenario is tagged `@flow:<change>.*`;
+once one is, the subject cannot ship until the brief is approved. The draft is
+pending until then: the reopen and ship guards read the newest adopted change
+with an `Approved:` line instead, so a shipped subject can reopen, re-verify
+and ship again while the draft waits; `canon status` still lists it.
+
+### Taking a draft change back out: `canon subject unadopt`
+
+```bash
+canon subject unadopt <change> --subject-id <S> --as planner --json
+```
+
+Removes the link on both records and keeps the change and its brief, so the
+draft can be adopted elsewhere (a `proposed` holding subject, say) while the
+live subject keeps shipping. It is refused with `SUBJECT_UNADOPT_REFUSED`
+for a change whose brief carries an `Approved:` line, and while a scenario
+the subject owns carries a `@flow:<change>.*` tag (it would fall back to an
+older approval; remove or retag those scenarios first, the hint names them);
+an unlinked pair is a no-op.
+
 ### Starting a new change: `canon change new`
 
 For a change that does not exist yet, one command writes it and records

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

@@ -101,6 +101,10 @@ NOT an attr value) and satisfies that directive's attrs:
       - "cargo test"
 ```
 
+When the body carries a continuation for another session, `summary` holds
+the next command and the claims already verified; reference artifacts and
+record ids instead of pasting them, and redact secrets.
+
 It's validated and compiled to a canon handoff body. Each
 `handoff-<domain>` directive declares its own attrs (e.g. `design` /
 `content` domains may require `acceptance-criteria` instead of

package/dist/skills/reference/role-implementer.md

@@ -45,12 +45,27 @@ After the first `status`, follow `meta.next` of each write; do not call
    root (default `.canon/specs`); `reference/canon-authoring.md` has the
    scaffold. When you fill in a scenario, keep its `# canon: {...}` provenance
    lines: dropping one aborts `inventory sync` on `missing-provenance`.
-2. **Units.** Give each unit its own actor id and session id and pass them on
-   everything it records. A delegated unit attests its own work; never attest
-   another unit's work under your id.
+2. **Units.** One unit is one flow step's complete path (sees, does,
+   becomes) that can be verified on its own, sized to one session. Name the
+   command that proves it (a test filter, a script) before you start it, and
+   run that command before you call the unit done. Give each unit its own
+   actor id and session id and pass them on everything it records. A
+   delegated unit attests its own work; never attest another unit's work
+   under your id. Units stay inside the one approved change; `tasks.md` is a
+   note, not a record.
 3. **Code and tests.** Name tests by scenario id (`game.run.01: …`) so a test
    report binds to its scenario. Record a defect you find in your own work
    with `finding add` the moment you find it, before review.
+   **A fix fails first.** For a bug fix, write or extend the scenario's test
+   and run it red on the unfixed code, then bind that failing run before you
+   change the code (`evidence add --scenario-id <id> --report <fmt>:<path> …`
+   with `--verdict divergent`; a failed case never records `faithful`, and
+   `--all-scenarios` derives `divergent` from it).
+   Fix the code, run again and bind the passing run: the green record
+   supersedes the red one, and `canon query --kind evidence --history
+   --scenario-id <id>` shows the red-then-green pair to the reviewer. A red
+   run is never an accepted gap. When no executable reproduction is
+   possible, say in `--ref` what the closest check is and why.
 4. **Evidence.** One test run that proves several scenarios is bound once with
    `--all-scenarios`: one record per indexed scenario owning a case, each with
    the verdict its own cases show; any refusal writes none. For one scenario
@@ -99,6 +114,16 @@ After the first `status`, follow `meta.next` of each write; do not call
    was accepted is accepted again by the reviewer once new evidence says
    something different.
 
+## Excuses that fail
+
+| The thought | The reality |
+|---|---|
+| "The suite is slow; record `faithful` to pass." | `faithful` over a failed case is refused; a limit outside this change is recorded `divergent` with the reason in `--ref`. |
+| "I fixed it, the test would pass." | Run the test red first and bind it, then green. Evidence is a claim; the history is what the reviewer reads. |
+| "The brief is as good as approved." | `evidence add` refuses an unapproved brief's scenarios. Say so and wait. |
+| "I will attest the other unit's work under my id." | Each unit records under its own actor id and session id. |
+| "I was told this twice already." | A correction repeated across runs belongs in a scenario, the policy or a gate; tell the orchestrator. |
+
 ## Retry safety
 
 Repeating `evidence add` with identical input returns the existing record

package/dist/skills/reference/role-orchestrator.md

@@ -48,6 +48,36 @@ shell).
 Order: planner, then (after the human's answer) implementer, then reviewer.
 Give each a unit: its own `--actor-id` and a session id.
 
+### Spawn contract
+
+Every spawn prompt names, in this order: the goal (the change slug and the
+one flow step or review it serves); the scope it owns (the scenarios or
+paths it may write); what it must not touch (the brief, the policy, other
+units' scenarios, anything outside its scope); the command that proves it is
+done (the unit's verify command, or `canon gate check` for the reviewer); and
+its own `--actor-id` and `--session-id`. Two agents never write the same
+paths: give parallel implementers disjoint scopes, and where the harness can
+isolate a child in its own worktree, use it. The child reports what it
+verified apart from what it only claims.
+
+### What each harness gives you
+
+Last reviewed 2026-10-21. A cell marked `verify` is unconfirmed here: check
+the harness before relying on it; a harness version moves faster than this
+text.
+
+| Harness | In-harness subagents | Isolation | Ask the human | Hooks | Skipped |
+|---|---|---|---|---|---|
+| claude (`.claude`) | yes, a subagent tool; a child shares your environment, so pass the role in the task | a subagent can run in its own git worktree | yes, a question tool | yes, in the harness settings; `scripts/canon-retrieve-pre-dispatch.sh` is a sidecar, not installed | none |
+| codex (`.agents`) | `verify`: none when #39 was filed; start the reviewer as a new `codex exec` run | none from canon: use a separate worktree you create | no in `codex exec`; stop and report | `verify` | in-harness spawn, unless a newer version provides it |
+| omp (`.omp`) | yes, the task tool | `verify` | yes, an ask tool | yes | none |
+| pi (`.pi`) | `verify`: assume none; start a new `pi` process | none from canon | `verify` | `verify` | in-harness spawn, isolation |
+
+Where a harness has no subagent tool, the reviewer is still a separate
+process with its own session id: start it from the shell with its own
+`CANON_ROLE=reviewer`. A harness that cannot ask the human means you stop
+and report in your final message; you never assume the answer.
+
 The reviewer is a separate process with its own session id, never your
 session or the implementer's under another label. Start it as a new process
 (a new `codex exec` run, or the harness's subagent), pass nothing of the
@@ -59,7 +89,9 @@ not sign off.
 
 When `status` or `meta.next` shows a step with `actor: human` (the brief's
 approval), stop everything for that scope, report the brief to the human in
-its language, and wait. Do not start the implementer before the answer.
+its language, and wait. Tell the human they can approve the clean briefs in
+`canon dashboard` (the briefs page) or answer in chat; you never click
+Approve or fill the form, and you run `brief approve` only from their words. Do not start the implementer before the answer.
 Record the answer with `brief approve`. Never approve it yourself and never
 edit the policy to pass the gate. A policy that no longer matches the
 approval fails closed (`POLICY_CHANGED_SINCE_APPROVAL`, or
@@ -70,6 +102,27 @@ the approved policy from git; never edit the policy yourself. Inside an
 approved scope never stop for a human: fixes, follow-ups and re-reviews go
 straight to the implementer and reviewer in the same change.
 
+## Hand off a note, not a copy
+
+A note one session leaves for another (a resume note, a spawn prompt, a
+`Handoff` body) points to artifacts and record ids instead of pasting them:
+name the change slug, the scenario ids, the evidence or finding keys and the
+files, and the next command. Say what was verified (a command that ran, with
+its result) apart from what is only claimed. Redact secrets: tokens, keys,
+passwords and private URLs never go into a note, a `--ref`, a `--summary`
+or a brief. When a `Handoff` body carries a continuation, its `summary`
+holds the next command and the verified claims (`reference/canon-vocab.md`).
+
+## Excuses that fail
+
+| The thought | The reality |
+|---|---|
+| "Edit the policy so the gate passes." | A changed policy fails closed (`POLICY_CHANGED_SINCE_APPROVAL`); ask the human to re-approve or restore it from git. |
+| "The reviewer can be me under another label." | The reviewer is a separate process with its own real session id (#39). |
+| "Approve the brief; the human said they are busy." | Never approve for the human; report the brief and wait. |
+| "Override the refusal to ship." | Fix the gap the refusal names; `--override-reason` does not waive an approval. |
+| "I have corrected this agent before." | A correction repeated across runs belongs in a scenario, the policy or a gate, not more prose. Tell the human. |
+
 ## Move the subject
 
 Move along `proposed → specced → building → verifying → shipped` with

package/dist/skills/reference/role-planner.md

@@ -15,6 +15,7 @@ canon subject new <subject-id> --domain <domain> --title "<title>" --actor-id <u
 canon change new <slug> --subject-id <subject-id> --title "<title>" --as planner --json
 canon change new <slug> --subject-id <subject-id> --kind chore --title "<title>" --as planner --json
 canon subject adopt <slug> --subject-id <other-subject-id> --as planner --json
+canon subject unadopt <slug> --subject-id <subject-id> --as planner --json   # a draft change off a live subject; refused once its brief is approved
 canon brief check --change-id <slug> --as planner --json
 canon brief approve --change-id <slug> --by "<the human>" --note "<their words>" --as planner --json
 ```
@@ -34,9 +35,24 @@ unapproved. A policy that no longer matches its approval fails closed
    `tasks.md` (`tasks.md` is an optional work note nothing gates on). A
    change that also serves another subject is adopted there too
    (`subject adopt`): it then belongs to both,
-   and its open blockers gate both. Inside an approved scope there is no new
+   and its open blockers gate both. Planning the next change for a
+   `building`, `verifying` or `shipped` subject warns (stderr and JSON
+   `meta.warnings`) until its brief is approved: evidence for its existing scenarios is not
+   frozen and the subject can still be reopened and shipped for its approved
+   scope while no scenario is tagged for the draft (a pending draft); once one
+   is, the subject cannot ship before the approval.
+   A scenario answers to the changes its `@flow:<change>.<F-id>`
+   tags name (`canon scenario new --flow <F-id>` tags one for this change).
+   To park a draft that should not gate a live subject, `subject unadopt`
+   it and adopt it into a `proposed` subject. Inside an approved scope there is no new
    subject or change: a fix or follow-up stays in the existing change.
-2. **Write the brief.** A PRD: intent, desired outcome, the user flow as
+2. **Write the brief.** Briefs outlive the code that exists today and are
+   read by sessions that did not write them. Intent says what the product
+   does today, in behavior words, and why that is not enough; Desired outcome
+   says what is true afterwards. Describe an interface by its behavior
+   (inputs, outputs, errors), and keep file paths, line numbers and function
+   names out of the sections that decide the work; a `Source: <path>`
+   provenance line is the one exception. A PRD: intent, desired outcome, the user flow as
    numbered steps `F1`, `F2`, … (sees → does → becomes), step detail per
    step, acceptance per step with its failure path, questions and
    assumptions, out of scope. Write it in the `language:` of `canon.yaml`;
@@ -55,7 +71,9 @@ unapproved. A policy that no longer matches its approval fails closed
    - `reference/brief-align.md`: scenarios cover the flow.
    - `reference/brief-polish.md`: prose.
 4. **Stop for the human.** Report the brief to the human, in the brief's
-   language, asking once. Build nothing for that scope (no scenarios, code
+   language, asking once, and say they can approve it in `canon dashboard`
+   (the briefs page, `/briefs.html`) or answer in chat. You never click
+   Approve or fill that form yourself. Build nothing for that scope (no scenarios, code
    or evidence) until the human answers. The approval is never assumed, even
    when the human said they cannot answer until you report: the brief is
    that report. The one answer approves the brief and the policy
@@ -86,6 +104,28 @@ shipped subject `change new` prints the reopen command for the orchestrator
 ship again until the suite is evidenced after the chore's approval. Work that
 changes behavior is never a chore: it is a feature change.
 
+### A migration is cut in phases
+
+A migration (a column, a format, a dependency swap) is cut as expand,
+migrate, contract: one change per phase, each adopting only after the
+previous one shipped. A phase that alters nothing a user or a caller can
+observe (a behavior-preserving internal rename, a build step) is a chore. A
+phase that changes data, a public interface or output is never a chore: it
+is a feature change with a PRD brief, whose Acceptance names the down path
+(how it is undone), the safety condition of any backfill (idempotent,
+resumable, checked before and after), and the destructive cleanup (drop the
+old column, delete the old format) in its own later change.
+
+## Excuses that fail
+
+| The thought | The reality |
+|---|---|
+| "The human is unavailable; I will assume the approval." | Never. The brief is the report; stop, and put open questions into Questions and assumptions. |
+| "This could change policy, but I will decide it." | Anything that could change policy goes to the questions. |
+| "A small follow-up needs no new answer." | A follow-up that adds or changes a flow step is a scope change and needs a new `brief approve`. |
+| "This migration is just a chore." | Data, interface or output changes are feature changes. |
+| "Put the file and line in the brief so nobody has to look." | Paths rot; describe behavior. |
+
 ## Hand-off
 
 After the approval the implementer takes the scenarios, then the reviewer.

package/dist/skills/reference/role-reviewer.md

@@ -15,12 +15,14 @@ canon gate check --as reviewer --json                 # once, before review add
 canon finding add --change-id <slug> --round <n> --seq <n> --severity <blocker|should-fix|note> --reviewer <me> --actor-id <me> --session-id <session> --summary "<defect>" --scenario-id <id> --scenario-id <id> --as reviewer --json   # one --scenario-id per scenario the defect is about
 canon finding list --change-id <slug> --open --as reviewer --json
 canon finding close --change-id <slug> --round <n> --seq <n> --disposition fixed --resolution-sha <sha> --as reviewer --json
+canon finding close --change-id <slug> --round <n> --seq <n> --disposition rejected|deferred --reason "<why, one line>" --as reviewer --json   # --reason is required here (FINDING_REASON_REQUIRED); optional for fixed
 canon review add --project-id <root-id> --scenario-id <id> --scenario-id <id> --reviewer <me> --actor-id <me> --role reviewer --session-id <session> --pin <sha> --upstream-ref <ref> --as reviewer --json
 canon review add --project-id <root-id> --scenario-ids-from - --reviewer <me> --actor-id <me> --role reviewer --session-id <session> --pin <sha> --upstream-ref <ref> --as reviewer --json   # ids on stdin, one per line
 canon review add --project-id <root-id> --change-id <chore-slug> --reviewer <me> --actor-id <me> --role reviewer --session-id <session> --pin <sha> --upstream-ref <ref> --as reviewer --json   # a chore: one change-level review of its invariants and checks against the diff
 canon divergence accept --project-id <root-id> --scenario-id <id> --reason "<why the gap stays>" --tracking <issue-url-or-ref> [--expiry YYYY-MM-DD] --reviewer <me> --actor-id <me> --session-id <session> --as reviewer --json
 canon artifacts verify --full --as reviewer --json    # the files the evidence and reviews bind are in the artifact store; refuses when an object store is unreachable
 canon query --kind evidence --history --as reviewer --json   # every version, not only the current record
+canon query --kind evidence --history --scenario-id <id> --as reviewer --json   # one scenario's red-then-green pair
 ```
 
 `review add` needs `--upstream-ref <ref>` or `--original-spec-ref <path>`;
@@ -70,10 +72,28 @@ does not sign off; record that instead (`--outcome indeterminate`, or
 
 ## Check the checks
 
-Passing is not enough: read each bound test against its scenario's Then
-steps. Record a finding (`finding add`) when a check pins behavior the
-scenario does not require, or skips a Then step the scenario states: such a
-test passes without proving the scenario. Do this before you sign.
+Passing is not enough. Read each bound test against its scenario's Then
+steps, in two separate passes, and say which pass a finding came from:
+
+1. **Spec fidelity.** The brief's step and the scenario against the test
+   (the PRD read above). Finding: the check pins behavior the scenario does
+   not require, or skips a Then step it states.
+2. **Standards.** The diff and the test against the code it claims to prove.
+   Finding: the test passes without proving anything. The usual ways:
+   - the expected value is computed by the code under test (tautology);
+   - it asserts an implementation detail (a call count, a private name), not behavior;
+   - it never reaches the real path or the real side effect (a file written, a record stored, a request sent);
+   - it asserts only that no error happened;
+   - it mocks the unit it is meant to test.
+
+When a check looks weak, you may name the one-line change to the code that
+should make it fail and run it if it is cheap; if the test stays green, record
+the finding. For a fix, read `canon query --kind evidence --history
+--scenario-id <id>`: expect an earlier non-faithful version, or a named
+closest reproduction in `--ref`; record a finding when neither exists. Put
+one blast-radius fact in the finding or review `--summary`: what else the
+change touches that the checks do not exercise. Do all of this before you
+sign.
 
 ## Accept a known gap
 
@@ -93,7 +113,10 @@ ship guard and stays listed as `accepted-divergence` in `status` and
 
 - Every defect is a finding; `finding list` shows round, seq, severity and
   disposition, so the next seq and the open blockers are one command away.
-  Close a finding once it is fixed.
+  Close a finding once it is dealt with. When you close it `rejected` or
+  `deferred`, give the reason in one line with `--reason "<why>"`: the close
+  is refused without it (`FINDING_REASON_REQUIRED`), and `finding list` shows
+  it as `[reason: …]` so the next reader sees why it was not fixed.
 - Sign off in one batch with `review add`, all or nothing. It writes
   directly; nothing to promote. canon stores and re-checks attached bytes
   and never compares images.
@@ -114,4 +137,14 @@ ship guard and stays listed as `accepted-divergence` in `status` and
   brief stales it. The chore also needs evidence recorded after its approval
   (the implementer's `--all-scenarios` run) before it ships.
 
+## Excuses that fail
+
+| The thought | The reality |
+|---|---|
+| "I will review this under a new session label." | A review is a separate process with its own real session id; a relabelled self-review is not independent (#39). |
+| "The tests pass, so I can sign." | Read the test against the Then steps first; a green test can prove nothing. |
+| "I cannot run the tests, but the evidence looks right." | Say so and record `indeterminate` or `unavailable`; never sign what you could not run. |
+| "This is a minor defect; I will skip the finding." | Every defect is a finding; severity says how much it matters. |
+| "I will edit the brief to fix it." | A brief defect is a finding, not an edit. |
+
 Reference: `reference/canon-review.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@journeykit/canon",
-  "version": "0.24.1",
+  "version": "0.25.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.24.1",
-    "@journeykit/canon-core-linux-x64": "0.24.1",
-    "@journeykit/canon-core-win32-x64": "0.24.1"
+    "@journeykit/canon-core-darwin-arm64": "0.25.0",
+    "@journeykit/canon-core-linux-x64": "0.25.0",
+    "@journeykit/canon-core-win32-x64": "0.25.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",