@journeykit/canon 0.25.0 → 0.27.0

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

@@ -40,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

@@ -22,7 +22,7 @@ marker, never by heading text.
 - 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
 
@@ -44,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

@@ -58,21 +58,19 @@ bytes no longer match the approved digest, or the approval cannot be read,
 the gate fails closed: the violation is reported and the exit is `1` (see
 `canon-policy`).
 
-Before it reads the scenario index, the gate rebuilds any stale part of
-it from the changed `.feature` files (the same code `canon inventory
-sync` runs) and says so in one stderr line, silent when the index is
-fresh:
-
-```
-canon gate check: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
-```
-
-A root that fails to sync (format violations, a duplicate id) is named
-instead, ending ``NOT refreshed: root `x` (N format violation(s), 0 sync
-error(s)) — `canon inventory sync` lists them``, and the gate fails
-closed: it adds `uncovered-cell <root> — the scenario index for spec root
-`<root>` is stale and could not be refreshed (…); `canon inventory sync`
-lists the problems to fix` and exits 1, since the index it would grade
+The gate is a read command: it writes nothing. A scenario index that is
+stale (a `.feature` file added, edited or deleted since the last sync) is
+graded as the refresh would leave it, built in memory from the changed
+files with the code `canon inventory sync` runs; the index on disk is
+brought up to date by the next command that writes (`canon evidence add`,
+`canon review add`, `canon subject status`) or by `canon inventory sync`.
+It prints no refresh line.
+
+A root that fails to sync (format violations, a duplicate id) cannot be
+graded in memory either, and the gate fails closed: it adds
+`uncovered-cell <root> — the scenario index for spec root `<root>` is
+stale and could not be refreshed (…); `canon inventory sync` lists the
+problems to fix` and exits 1, since the index it would grade
 does not hold the edits. The `verifying → shipped` guard refuses with
 the same violation, and `canon status` lists the sync as its only step.
 Fix what the sync lists and run the gate again. See `canon-storage`

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

@@ -6,21 +6,25 @@ records every downstream stage joins against.
 
 ## You rarely run it yourself
 
-Since 0.16 the commands that read the index refresh it first:
-`canon status`, `canon gate check`, `canon evidence add`,
-`canon review add` and `canon subject status` index added, edited and
-deleted `.feature` files themselves, with the same code this command runs,
-scoped to the changed files, and say so in one stderr line:
+Since 0.16 the commands that read the index see added, edited and deleted
+`.feature` files without a sync step. `canon evidence add`, `canon review
+add` and `canon subject status` refresh the index on disk first, with the
+same code this command runs, scoped to the changed files, and say so in one
+stderr line:
 
 ```
-canon status: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
+canon evidence add: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
 ```
 
+`canon status` and `canon gate check` are read commands and write nothing:
+they grade the index as that refresh would leave it, built in memory, and
+print no line.
+
 So the working loop has no sync step and no `canon format` step: write the
 scenario (`canon scenario new` writes it format-clean) and run the next
 command. Run `canon inventory sync` when:
 
-- a reader prints `NOT refreshed` — a root has a format violation (a
+- a command prints `NOT refreshed` — a root has a format violation (a
   hand-written `Feature:`/`Scenario:` header with no `# canon:` provenance
   comment, an emptied file, …) or a duplicate id, so its files were not
   indexed. `canon gate check` then fails (`uncovered-cell <root>`),
@@ -57,7 +61,7 @@ and the openspec source `canon init` wrote is removed only after every
 pointer brief is written and nothing unread is left under
 `openspec/changes/` (each unread directory is named).
 
-The reader's refresh treats a file as stale when its latest index
+The refresh treats a file as stale when its latest index
 generation has another `source_digest` or `scenario_digest`. A
 generation written before 0.15 has no `scenario_digest`, so a repo that
 kept an old index gets it rewritten on the first read.
@@ -68,7 +72,7 @@ kept an old index gets it rewritten on the first read.
 author .feature corpus (canon scenario new)
         │
         ▼
-scenario index                  # refreshed by every reader; `canon inventory sync` rebuilds it
+scenario index                  # refreshed by the writers; `canon inventory sync` rebuilds it
         │
         ▼
 canon review add                # attests a review — see canon-inventory downstream / canon-gate

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

@@ -272,21 +272,27 @@ fails those commands (exit `1`), and `canon init --check-config` reports
 
 `canon inventory sync` materializes one `Scenario` record per
 `(project_id, scenario_id)` under `.canon/ledger/kind=scenario/`. The
-index is derived — a pure function of the `.feature` files — so the
-commands that read it rebuild it first: `canon gate check`, `canon
-status`, `canon subject status`, `canon review add` and `canon evidence
-add`. The index is stale when a `.feature` file holds a scenario with no
-live index record, or one whose recorded source digest differs from the
-file's current bytes, or when the index holds a scenario of a spec root
-that no `.feature` file of it declares any more. The reader then runs
-`canon inventory sync`'s code on the changed files (validation still
-covers the whole root) and prints one stderr line:
+index is derived — a pure function of the `.feature` files. The index is
+stale when a `.feature` file holds a scenario with no live index record,
+or one whose recorded source digest differs from the file's current bytes,
+or when the index holds a scenario of a spec root that no `.feature` file
+of it declares any more.
+
+The commands that write records (`canon subject status`, `canon review
+add` and `canon evidence add`) rebuild a stale index on disk first: they
+run `canon inventory sync`'s code on the changed files (validation still
+covers the whole root) and print one stderr line:
 
 ```
-canon status: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
+canon evidence add: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
 ```
 
-A deleted scenario is not erased: `canon inventory sync` — and a reader's
+The commands that only read (`canon gate check`, `canon status`) write
+nothing: they grade a stale index as the refresh would leave it, built in
+memory, and print no refresh line. `canon query --kind scenario` and the
+report panels read the index on disk as it is.
+
+A deleted scenario is not erased: `canon inventory sync` — and a writer's
 refresh, identically — appends a tombstone, a new generation of its
 record with `removed: true`. The gate, `canon status`, `canon query` and
 the report panels then treat it as absent; re-adding the scenario writes
@@ -294,7 +300,7 @@ a live generation that supersedes the tombstone. A root that fails to
 sync writes no tombstone either.
 
 ```
-canon status: refreshed the scenario index from 1 scenario(s) no longer in any feature file (cart.pay.01): 1 record(s) written
+canon evidence add: refreshed the scenario index from 1 scenario(s) no longer in any feature file (cart.pay.01): 1 record(s) written
 ```
 
 `canon inventory sync` and every refresh hold an OS file lock on
@@ -303,17 +309,16 @@ index one change twice; a refresh that waited checks staleness again and
 is silent if another run already did the work. The lock is released when
 its holder exits, however it exits, so it never goes stale; a writer
 gives up after 30 s with a message naming the file (`canon inventory
-sync` exits `2`; a reader skips the refresh and still runs).
+sync` exits `2`; a writer's refresh is skipped and the command still runs).
 
 A fresh index prints nothing. A root that fails to sync (format
 violations, a duplicate id) is named and left as it was, and the command
 still runs; `canon gate check` then fails with `uncovered-cell <root>`,
 the `verifying → shipped` guard refuses, and `canon status` lists only
-`canon inventory sync`, while the reporting readers (`query`, `context`)
-keep only this line:
+`canon inventory sync`:
 
 ```
-canon gate check: found the scenario index stale for 1 changed feature file(s) (…): 0 record(s) written; NOT refreshed: root `root` (2 format violation(s), 0 sync error(s)) — `canon inventory sync` lists them
+canon evidence add: found the scenario index stale for 1 changed feature file(s) (…): 0 record(s) written; NOT refreshed: root `root` (2 format violation(s), 0 sync error(s)) — `canon inventory sync` lists them
 ```
 
 Nothing is written in a directory without `canon.yaml`. `canon inventory
@@ -342,10 +347,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

@@ -21,11 +21,13 @@ authored in one place:
   adopt`.
 - **Scenarios**: the `@subject:<id>` tag on each Gherkin scenario,
   indexed onto `Scenario.subject_id` by the scenario index (rebuilt by
-  `canon inventory sync`, and refreshed by every command that reads it).
+  `canon inventory sync`, and refreshed on disk by the commands that write
+  records; `canon status` and `canon gate check` read it as the refresh
+  would leave it, without writing).
   The Subject record carries no scenario list — the spec corpus is the
   only source, and the Subjects report panel, `spec_coverage.scope`, and
   the shipped gate all read it from there. To link a scenario, tag it;
-  the next `canon status` or `canon gate check` indexes the tag. There is
+  the next `canon status` or `canon gate check` reads the tag. There is
   no subject-side command for it.
 
 ## The 4-step loop
@@ -483,11 +485,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
@@ -605,9 +611,9 @@ uses, so status and the gate cannot disagree about a gap:
   unreadable one → `canon init --check-config`; a scenario tagged with a
   subject that has no record → `canon subject new <that id>`; no subject
   at all → `canon subject new`; subjects and `.feature` scenarios but no
-  scenario records → `canon inventory sync` (status refreshes the index
-  itself first, so this means the refresh refused on a format violation
-  or a duplicate id, which the sync names). Then per subject, verifying
+  scenario records → `canon inventory sync` (status reads the index as a
+  refresh would leave it, so this means the refresh would be refused on a
+  format violation or a duplicate id, which the sync names). Then per subject, verifying
   first, then building, specced, proposed, shipped: an unapproved brief
   (building and later, and proposed once its change has a brief)
   → the human step below, which is then the subject's

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

@@ -24,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
@@ -55,21 +57,37 @@ unapproved. A policy that no longer matches its approval fails closed
    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, and say they can approve it in `canon dashboard`
    (the briefs page, `/briefs.html`) or answer in chat. You never click

package/package.json

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