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

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

@@ -483,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/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.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.25.0",
-    "@journeykit/canon-core-linux-x64": "0.25.0",
-    "@journeykit/canon-core-win32-x64": "0.25.0"
+    "@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",