@journeykit/canon 0.24.1 → 0.26.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-align.md

@@ -39,4 +39,4 @@ Implement, evidence and review (loop steps 5 to 7). If the brief had to change,
 - Explaining writes nothing. Asked what a finding means or what a pass would do, answer in chat and leave the brief untouched.
 - No pass requires another as a prerequisite. Run the one the findings or the human point at, in any order.
 - A pass closes only the findings it rechecked: rerun `canon brief check` after the edit and report a finding as closed only when it is gone from that run. Never claim a rule you did not rerun.
-- Write in the brief's language (`language:` in `canon.yaml`). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and `canon brief approve` again.
+- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and `canon brief approve` again.

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

@@ -39,4 +39,4 @@ Every open line is a question with a proposed default or a stated assumption. `c
 - Explaining writes nothing. Asked what a finding means or what a pass would do, answer in chat and leave the brief untouched.
 - No pass requires another as a prerequisite. Run the one the findings or the human point at, in any order.
 - A pass closes only the findings it rechecked: rerun `canon brief check` after the edit and report a finding as closed only when it is gone from that run. Never claim a rule you did not rerun.
-- Write in the brief's language (`language:` in `canon.yaml`). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and `canon brief approve` again.
+- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and `canon brief approve` again.

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
@@ -38,4 +40,4 @@ brief has none of them: harden its Invariants and Checks instead.
 - Explaining writes nothing. Asked what a finding means or what a pass would do, answer in chat and leave the brief untouched.
 - No pass requires another as a prerequisite. Run the one the findings or the human point at, in any order.
 - A pass closes only the findings it rechecked: rerun `canon brief check` after the edit and report a finding as closed only when it is gone from that run. Never claim a rule you did not rerun.
-- Write in the brief's language (`language:` in `canon.yaml`). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and `canon brief approve` again.
+- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and `canon brief approve` again.

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

@@ -1,33 +1,236 @@
 # Brief pass: polish
 
-Tighten the prose of the normative sections so a reader can act on it. Run it
-last or whenever `canon brief` reports prose advisories; it never blocks
-approval.
+Make the brief something a human reads once and understands. Run it whenever
+`canon brief check` reports `prose.*` advisories; `canon status` and
+`meta.next` name it before the human stop. It never blocks approval, and it
+is not finished by silencing rules: it is finished when the brief reads
+plainly and each advisory is gone or waived with a reason.
 
-## Scope
+## Mode first, style second
 
-Sections with `role=normative`: Desired outcome, User flow, Step detail,
-Acceptance (feature) or Invariants and Checks (chore). Context and question
-sections are not judged. Prose rules ship for `language: en` and `ko`; any
-other language gets the structure rules only.
+Fix what the document is before touching a word. Style rules cannot rescue a
+brief that says the wrong thing.
+
+- **Intent** states the current behavior: what a user sees and does today, and the gap. Not the history of how it got there.
+- **Desired outcome** states what is true afterwards, as behavior a user can observe.
+- **Interfaces** are described by behavior: inputs, outputs, errors, limits. Not by file, line or function.
+- **Acceptance** gives, per step, a check a reader can run without asking the author, and one failure path naming the condition and what the user sees.
+- **Provenance** goes on one line, `Source: <where this came from>`. That line is the only place a path or an identifier belongs.
+- **No** paths, line numbers, identifiers, dates or decision history in the prose. A fact stated in one section is not restated in another; point to the section instead.
+
+## Scope and language
+
+Rules read the brief by section role. Intent and Questions and assumptions
+get the phrase rules (`evaluative`, `connective`, `contrast`, `colloquial`,
+`degree`) and the five newer ones; `decision-history` reads normative text
+and Intent, not Questions. `sentence-length`, `paragraph-length` and
+`key-sentence` read the normative sections only (Desired outcome, User flow,
+Step detail, Acceptance; for a chore, Invariants and Checks). Out of scope
+is not judged. Headings, code spans, fenced code, URLs, code-like tokens and
+the `Source:` and `Approved:` lines are not counted as prose.
+
+`canon brief check` detects the language of the text from the script of its
+prose letters: Hangul is `ko`, Latin is `en`, kana or Han text is named
+(`ja`, `zh`) and gets the structure rules only. A section in another script
+than the rest is judged in its own language, and a section with too few
+letters to tell inherits the brief's. The output prints one line,
+`language: ko (detected)`; the JSON carries `language` and `languageSource`
+(`detected` or `configured`). `language:` in `canon.yaml` is an override: when
+set it decides, and `brief check` adds `languageNote` (one line in the human
+output) if the text looks like another language. Report that note to the
+human; do not translate the brief to fit the setting.
+
+## The rules
+
+Each finding carries the matched text or the measured value, and a hint.
+Fix the sentence by saying the concrete thing; swapping in a near synonym only
+moves the finding. The examples are invented.
+
+### `prose.evaluative`
+
+Catches a verdict standing in for a fact (en "it is important", "it is
+crucial", "it is essential"; ko "중요하", "핵심이", "필요가 있", "바람직하",
+"의미가 있"). Fix: state the fact the verdict stood for.
+
+- en. Before: "It is important that export keeps the old file." After: "A failed export keeps the previous file."
+- ko. 전: "내보내기가 실패해도 이전 파일을 유지하는 것이 중요하다." 후: "내보내기가 실패하면 이전 파일을 그대로 둔다."
+
+### `prose.connective`
+
+Catches a sentence that opens with a decorative connective (en "therefore",
+"in conclusion"; ko "따라서", "결론적으로", "이처럼", "사실", "참고로"). Fix:
+delete it; the order of the sentences already carries the link. Keep the
+link only as a condition ("if", "unless").
+
+- en. Before: "Therefore the list is sorted by date." After: "The list is sorted by date, newest first."
+- ko. 전: "따라서 목록은 날짜순으로 정렬한다." 후: "목록은 날짜 내림차순으로 정렬한다."
+
+### `prose.contrast`
+
+Catches the rhetorical "not X but Y" (ko "A가 아니라 B"). Fix: state Y alone.
+
+- en. Before: "This is not a rename but a new way to find notes." After: "Renaming a note updates its search entry at once."
+- ko. 전: "이것은 이름 변경이 아니라 노트를 찾는 새로운 방식이다." 후: "노트 이름을 바꾸면 검색 항목이 바로 바뀐다."
+
+### `prose.colloquial`
+
+Korean only. Catches a spoken ending on a written sentence (~세요, ~어요,
+~아요, ~해요, ~에요, ~네요, ~죠, …). Fix: the plain written form (`~다`).
+
+- ko. 전: "이름이 겹치면 뒤에 숫자를 붙여 주세요." 후: "이름이 겹치면 뒤에 숫자를 붙인다."
+
+### `prose.degree`
+
+Catches a degree word nobody can check (en "very", "really", "extremely";
+ko "매우", "겨우", "무려", "고작"). Fix: the number or the condition.
+
+- en. Before: "The page loads very quickly." After: "The page accepts input within one second on the reference laptop."
+- ko. 전: "화면이 매우 빠르게 열린다." 후: "화면은 기준 노트북에서 1초 안에 입력을 받는다."
+
+### `prose.sentence-length`
+
+Normative sections. Catches a sentence over 30 words (en) or 80 characters
+(ko). Fix: one statement per sentence, split at the condition, the action
+and the result.
+
+- en. Before: "When a user who has not signed in opens a shared link that has already expired, the page, which also logs the attempt, shows a notice and a sign-in button and offers a way back to the list." After: "A signed-out user opens an expired shared link. The page shows the notice 'Link expired' and a sign-in button. The attempt is logged."
+- ko. 전: "로그인하지 않은 사용자가 만료된 공유 링크를 열면 시도를 기록하면서 안내 문구와 로그인 버튼을 함께 보여 주고 이후 목록 화면으로 돌아가는 경로도 제공한다." 후: "로그인하지 않은 사용자가 만료된 공유 링크를 연다. 화면에 '링크가 만료되었습니다' 문구와 로그인 버튼이 뜬다. 시도는 기록한다."
+
+### `prose.paragraph-length`
+
+Normative sections. Catches a paragraph of more than five sentences. Fix: the
+compression pass in `role-planner.md`: keep the sentences that state a
+condition, an action, a result or a number; make three or more parallel
+items a list; delete or move the rest.
+
+### `prose.key-sentence`
+
+Normative sections. Each carries exactly one key sentence marked `==**…**==`:
+the line a reader must not miss. Fix: mark the single rule or result the
+section turns on, and nothing else.
+
+- en: `==**A deleted note stays recoverable for 30 days.**==`
+- ko: `==**삭제한 노트는 30일 동안 복구할 수 있다.**==`
+
+### `prose.code-citation`
+
+Catches code references in sentences: paths with a known extension,
+`path:line`, paths of two or more segments (`a/b/c`, `./x`), and backticked
+code-shaped identifiers (`a::b`, `f()`, `snake_case`, `obj.member`,
+`camelCase`). It does not catch UI labels, product names (`Next.js`, `iPhone`),
+flags, commands, dates, routes or URLs, or the `Source:` line. Fix: say what the code does as behavior;
+provenance goes on the one `Source:` line.
+
+- en. Before: "`NoteStore.save` in `src/store/notes.ts:212` drops the tag list." After: "Saving a note drops its tags." and, once, `Source: the note store's save path.`
+- ko. 전: "`src/store/notes.ts:212`의 `NoteStore.save`가 태그를 버린다." 후: "노트를 저장하면 태그가 사라진다." 그리고 한 번 `Source: 노트 저장소의 저장 경로.`
+
+### `prose.parenthetical`
+
+Catches a section with three or more parenthetical asides at a density over
+four per 1000 characters. Labels like `(F1)` or `(30초)` do not count. Fix:
+if the aside is a condition or a result, make it its own sentence; if it is
+background, delete it; if it is a doubt, move it to Questions and assumptions.
+
+- en. Before: "Sync runs (every hour), on open (when online), and retries (at most twice)." After: "Sync runs every hour and when the app opens while online. A failed sync retries twice."
+- ko. 전: "동기화는 (한 시간마다), 앱을 열 때 (온라인이면 언제나) 실행되고 (최대 두 번) 재시도한다." 후: "동기화는 매시간, 그리고 온라인 상태에서 앱을 열 때 실행한다. 실패한 동기화는 두 번 재시도한다."
+
+### `prose.decision-history`
+
+Normative text, Intent and table cells. One finding per sentence that holds
+a calendar date, in any language (`2026-10-21`, `2026년 10월`, `10월 21일`,
+`Oct 21`, `21 October`, `October 2026`), or, in Korean text, one of
+`결정했다`, `결정했고`, `결정하여`, `결정됐다`, `결정되었다`, `정해졌다`, `합의했다`,
+`확정했다`, `~기로 했다`, `논의 결과`, `운영자 결정`, or, in English text, "we
+decided", "we agreed", "was decided", "it was agreed". There is no gating: a
+date next to 부터 or after is a finding too. Fix: delete the history and write
+the decision as present behavior; a decision still open goes to Questions and
+assumptions. When the date is part of the behavior (an effective date, a
+deadline) or a quoted label, keep it and waive it with `match=` set to the
+date (it compares the date or phrase the finding matched and the excerpt, nothing else), so the waiver clears that date only and every other note in the section
+still draws a finding. Never waive the rule for the whole section.
+
+- en. Before: "On 3 March the team agreed on a grid as the default view." After: "The default view is a grid."
+- ko. 전: "3월 3일 회의에서 기본 보기를 격자로 하기로 했다." 후: "기본 보기는 격자다."
+- waive one date: `<!-- canon:waive prose.decision-history detail "연체 요금은 2026-12-01부터 적용되는 동작이다" match="2026-12-01" -->`
+
+What it misses: a decision written in other words ("회의에서 정한 대로" is not
+listed on purpose, it reads as behavior). Over-reports: a date that is
+behavior, and the closed-list phrases in behavior text; waive those with `match=`.
+
+### `prose.ai-vocabulary`
+
+Catches a short closed list of stock words and metaphors (en "seamless",
+"robust", "leverage", "streamline", "empower", "north star", "game-changer",
+…; ko "원활", "견고", "시너지", "패러다임", "북극성", "토대", …). Fix: the plain
+verb and its object.
+
+- en. Before: "This leverages the sync engine for a seamless experience." After: "A note edited on one device appears on the others within a minute."
+- ko. 전: "동기화 엔진으로 원활한 사용 경험을 제공한다." 후: "한 기기에서 고친 노트가 1분 안에 다른 기기에 나타난다."
+
+### `prose.ko-ending`
+
+Korean only. Flagged everywhere, list items included: polite `~ㅂ니다`,
+`~ㅂ니까`, `~ㅂ시다` (합니다, 입니다, 없습니다; a plain word like 아니다 is not
+polite), `~십시오`, and a plain imperative: a terminated, unlabeled sentence
+whose last word ends in 라 after a syllable with no final consonant (하라,
+해라, 두라, 오라, 넣으라, 남겨라, 줘라). A syllable with a final consonant
+(달라, 갈라) never counts. The `~요` forms in `prose.colloquial`'s list
+(`~세요`, `~해요`, …) belong to that rule. Outside list items any terminated
+sentence not ending in `~다` is flagged, a plain hortative `~자` included. In a
+list item the plain `~자` is not detected: it is the noun suffix in 참가자,
+후보자, 하자, 주자, so keep a hortative out of lists yourself. Not flagged:
+questions, `없음.`, sentences ending in code or a quote, flow steps, list
+fragments without a verb, a `label:` item, and an unterminated list item.
+
+What it over-reports: a class of nouns, often loanwords, that end in an open
+syllable plus 라 (보라 'purple', 카메라, 오페라, 인프라) as a terminated list
+item; keep the sentence and waive with `match="<the noun>"`. What it misses: the
+prohibitive `~말라` (`지우지 말라`: 말 has a final consonant), any consonant-stem
+imperative written `~라` (달라 as a verb), and any hortative inside a list.
+Fix: end the statement in `~다`.
+
+- ko. 전: "목록이 비어 있으면 안내를 보여 줍니다." 후: "목록이 비어 있으면 안내를 보여 준다."
+- ko. 전: "- 재고를 확인해라." 후: "- 재고를 확인한다."
+
+### `prose.length`
+
+Catches a section or the whole brief over its character budget; the finding
+states the measured value and the budget. Section budgets (ko / en
+characters): Intent 400 / 700, Outcome 500 / 900, Flow 800 / 1500, Detail
+2500 / 3500, Acceptance 1000 / 1800, Questions 800 / 1200, Invariants and
+Checks 800 / 1500 each (Out of scope has none); whole brief 4000 / 6000. Fix: the
+compression pass in `role-planner.md`: delete sentences that restate another
+section, turn parallel items into a list or table, move assumptions to
+Questions and assumptions and a not-doing list to Out of scope. A brief this
+long usually says several things twice. A waiver for the whole-brief budget
+uses the section key `brief`.
 
 ## Inspect
 
-- `canon brief check --json`, the `prose.*` findings: `evaluative`, `connective`, `contrast`, `colloquial` (ko), `degree`, `sentence-length`, `paragraph-length`, `key-sentence`. Each carries the matched phrase or the threshold and the measured value.
-- Replace an evaluative or degree word with the observable fact it stood for. Split a long sentence or paragraph. Cut connectives that only decorate.
-- Each normative section carries exactly one key sentence marked `==**…**==`: the one line a reader must not miss.
-- A finding is a prompt to reread, not a verdict: if the phrase is the precise term (a state name, a quoted label), keep it and waive that rule in that section with `<!-- canon:waive <rule-id> <section-key> "<reason>" -->`.
+- `canon brief check --json`: read the `prose.*` findings, then the sections they sit in. Fix by section, not by rule.
+- A finding is a prompt to reread, not a verdict. When the flagged text is the precise term (a state name, a quoted label, a command), keep it and waive that rule in that section:
+  `<!-- canon:waive <rule-id> <section-key> "<reason>" -->`
+  To waive one finding and keep the rest of the rule live in that section, add the text the finding names: `<!-- canon:waive <rule-id> <section-key> "<reason>" match="<text>" -->` (after the reason's closing quote only a whole `match="<text>"` is allowed; `match =`, `MATCH=`, an unquoted or empty match or extra text is a blocker, and a reason holds no double quote).
+  A waiver is right when the text is a quotation or a fixed term, and wrong when it excuses a sentence you could simply rewrite. One rule, one section, a reason the human can read.
+
+## The loop
+
+1. Fix the mode problems above, then the findings, section by section.
+2. Run `canon brief check --change-id <slug> --json`.
+3. Repeat until no advisory remains, or each remaining one is waived with a reason.
+4. Stop and report to the human, in the brief's language. Do not loop further: a clean run says nothing about whether the brief is good, only that these counts are within budget.
 
 ## NEVER
 
 - Never change meaning: no flow step, rule, limit or failure path added, removed or softened while rewording.
-- Never rewrite to dodge a rule (swap a listed phrase for a near synonym); say the concrete thing.
-- Never polish sections that are not normative, or touch flow ids and subheadings.
-- Never treat a clean prose run as a claim about who wrote the brief or whether it is good.
+- Never rewrite to dodge a rule (a near synonym, a list used to hide a long sentence); say the concrete thing.
+- Never touch flow ids or subheadings, and never polish the markers.
+- Never translate the brief to match a `language:` setting.
+- Never treat a clean run as a claim about who wrote the brief.
 
 ## Verify
 
-`canon brief check` no longer lists the `prose.*` findings you rewrote (or lists them as waived with a reason); no blockers appeared.
+`canon brief check` no longer lists the `prose.*` findings you rewrote, or lists them as waived with a reason; no blockers appeared.
 
 ## Next
 
@@ -39,4 +242,4 @@ Report to the human and `canon brief approve` from their answer.
 - Explaining writes nothing. Asked what a finding means or what a pass would do, answer in chat and leave the brief untouched.
 - No pass requires another as a prerequisite. Run the one the findings or the human point at, in any order.
 - A pass closes only the findings it rechecked: rerun `canon brief check` after the edit and report a finding as closed only when it is gone from that run. Never claim a rule you did not rerun.
-- Write in the brief's language (`language:` in `canon.yaml`). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and `canon brief approve` again.
+- Write in the brief's language (detected from the text, or `language:` in `canon.yaml` when set). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and `canon brief approve` again.

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

@@ -20,8 +20,9 @@ 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.
+- A `canon:waive <rule-id> <section-key> "<reason>"` comment (optionally with `match="<text>"`) is well formed with a real reason.
 
 ## NEVER
 
@@ -43,4 +44,4 @@ marker, never by heading text.
 - Explaining writes nothing. Asked what a finding means or what a pass would do, answer in chat and leave the brief untouched.
 - No pass requires another as a prerequisite. Run the one the findings or the human point at, in any order.
 - A pass closes only the findings it rechecked: rerun `canon brief check` after the edit and report a finding as closed only when it is gone from that run. Never claim a rule you did not rerun.
-- Write in the brief's language (`language:` in `canon.yaml`). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and `canon brief approve` again.
+- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and `canon brief approve` again.

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,
@@ -342,10 +342,17 @@ comment, only the missing ones):
 - `.canon/audit/` — the query/export/purge access log.
 - `.canon/ledger/kind=scenario/` — the scenario index; every reader
   rebuilds it.
+- `.canon/archive/kind=scenario/` — superseded scenario index rows;
+  derived like the index.
 - `.canon/scenario-index.lock` — the lock serializing index rebuilds.
 - `.canon/artifact-store.lock` — the lock serializing artifact store
   writes.
+- `.canon/dashboard-snapshot/` — the snapshot `canon dashboard`
+  regenerates on every run.
+- `.canon/learn/` and `.canon/r2/` — local learn scratch and the local
+  object-store stand-in `canon report` writes.
 
 A rerun on a repo that already has `canon.yaml` only refreshes
-`AGENTS.md`, so an existing repo's `.gitignore` is unchanged; add the
-lines by hand to adopt them.
+`AGENTS.md`; `canon migrate` adds the lines an existing `.gitignore`
+lacks, and `canon skills doctor` and `canon init --check-config` name a
+missing one.

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
@@ -432,11 +483,15 @@ advisory, and is read as before.
   or later, a flow step no scenario points at (`brief.flow-uncovered`) or
   one with no failure scenario (`brief.flow-no-failure`): these two
   **gate shipping, never approval**.
-- **Advisories (prose, `prose.*`)**: phrase lists, sentence and
-  paragraph length, and key-sentence marking in `role=normative`
-  sections, for `language: en` and `ko`. Never an authorship verdict.
+- **Advisories (prose, `prose.*`)**: judged in the language the text is
+  written in (`language:` overrides): phrase lists, code citations,
+  asides, dates and decision notes, stock vocabulary, Korean endings and
+  length budgets, in the normative sections plus Intent and Questions;
+  sentence, paragraph and key-sentence rules in normative sections.
+  Never an authorship verdict. `reference/brief-polish.md` has each rule.
 - **Waivers**: `<!-- canon:waive <rule-id> <section-key> "<reason>" -->`,
-  one rule in one section, reason required; listed in the output.
+  one rule in one section, reason required; add `match="<text>"` to waive
+  only the findings whose matched text contains it. Listed in the output.
 - **`approve`** records the human's answer: it writes
   `Approved: <who> <when> — "<words>" (brief sha256:<digest>)` into the
   brief and records the policy approval in the same call. It refuses

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
 ```
@@ -23,8 +24,10 @@ After the first `status`, follow `meta.next` of each write. `brief check`
 lists blockers and advisories; bare `canon brief --as planner` names the next
 steps. While the brief has blockers, `status` and `change new`'s `meta.next`
 send you to write it (`write the brief: canon brief check --change-id <slug>
-lists N blockers`); the human step appears only once the brief is clean and
-unapproved. A policy that no longer matches its approval fails closed
+lists N blockers`); then, while prose advisories remain, to the polish pass
+(`polish the brief in <path> (reference/brief-polish.md), then run canon
+brief check --change-id <slug>`, with the advisory count and the top rule
+ids); the human step comes after it. A policy that no longer matches its approval fails closed
 (`POLICY_CHANGED_SINCE_APPROVAL`): never edit it; the human re-approves.
 
 ## Steps
@@ -34,28 +37,61 @@ 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`;
-   unset, in the request's language, and add "which language?" to the
-   questions. Anything that could change policy goes to the questions: never
-   decide it yourself. A change that comes from an external plan the human
+   assumptions, out of scope. Write it in the language of the request, or
+   the `language:` of `canon.yaml` when it is set (`brief check` detects the
+   language of the text and reports whether it used the detected or the
+   configured one; a `languageNote` means they disagree: tell the human, and
+   ask "which language?" in the questions). Anything that could change
+   policy goes to the questions: never decide it yourself. A change that
+   comes from an external plan the human
    prepared (an openspec `proposal.md` read through `plans.sources`) gets a
    `brief.md` whose `Source: <path>` line points at the plan; canon never
    edits the plan.
 3. **Check it.** `brief check` (read-only) lists findings: fix every blocker
-   (structure) before you stop; advisories (prose) are optional. Five optional
-   refinement passes, each standing alone and none needing another first:
+   (structure) before you stop. Four optional refinement passes, each
+   standing alone and none needing another first:
    - `reference/brief-shape.md`: structure (sections, order, leftover template text).
    - `reference/brief-clarify.md`: open questions.
    - `reference/brief-harden.md`: flow and step detail agree.
    - `reference/brief-align.md`: scenarios cover the flow.
-   - `reference/brief-polish.md`: prose.
+
+   **Compress, then polish.** Before the human reads it, shorten the brief.
+   A human reads it once, so every sentence has to earn its place:
+   - Per paragraph, keep only sentences that state a condition, an action, a result or a number. Delete the rest.
+   - Three or more parallel items become a list or a table.
+   - Delete a sentence that restates another section: each fact lives in one place (single source of truth).
+   - An assumption goes to Questions and assumptions. A "not doing" list goes to Out of scope.
+
+   Then, when `brief check` reports prose advisories (`prose.*`; `status` and
+   `meta.next` name the step), the polish pass is required before the human
+   stop: follow `reference/brief-polish.md` and rerun `brief check` until
+   the advisories are gone or each remaining one is waived with a reason.
+   It never blocks approval, but you do not hand the human a brief with
+   unexamined advisories.
 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 +122,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.26.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.26.0",
+    "@journeykit/canon-core-linux-x64": "0.26.0",
+    "@journeykit/canon-core-win32-x64": "0.26.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",