@journeykit/canon 0.30.0 → 0.32.0

package/dist/skills/SKILL.src.md

@@ -26,33 +26,54 @@ a feature, a one-line request included. A human is needed once per scope:
 
 - **The approval** (step 1). For a new subject or a scope change, the
   human must approve the brief. Write the brief,
-  run `canon brief check` until it reports no blockers, then stop and
-  report the brief to the human: build nothing for that scope (no
+  run `canon brief check` until it reports no blockers, then show it, ask and
+  record the answer: build nothing for that scope (no
   scenarios, code or evidence) before the human answers. The approval is
   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
+  answer until you show it. The one answer
   approves the brief and the policy, `.canon/policy.yaml`, which is what
   the gate grades the work against. The human may also approve it on the `canon dashboard` briefs page; you never use that form.
-  The human records the answer, never you:
-  `canon brief approve <slug> --approver <their name> --note "<their words>"`
-  refuses every agent role (`HUMAN_ONLY`). Report that exact call, slug filled in, and
-  wait; never remove or unset your role (`env -u CANON_ROLE`, dropping `--as`) to run it yourself.
+  1. **Show** with `canon brief show <slug> --body`: the brief file's bytes and,
+     last, `digest: sha256:<hex>`. Send it to the human's own view without
+     retyping it (omp: redirect it to `out://`, which is off for subagents and
+     non-TUI sessions and caps at 64 KiB; there, and in a harness with no such
+     channel, leave the tool output visible). A subagent has no question tool:
+     the orchestrator shows, asks and records.
+  2. **Ask** with the harness question tool (`ask` in omp, `AskUserQuestion` in
+     Claude Code, otherwise in the chat): approve or request changes, several
+     briefs in one question.
+  3. **Count only an explicit approval.** A question or a condition is a
+     revision request (change the brief, check, show and ask again); no answer
+     records nothing.
+  4. **Record it** with the relay option:
+     `canon brief approve <slug> <slug> --approver <their name> --note "<their words>" --relayed-via <ask|AskUserQuestion|chat> --actor <your actor id> --digest <slug>=<digest shown>`
+     (one or more slugs, each with its own `--digest`, one answer for all, nothing written if any is refused).
+     The `Approved:` line then carries `(relayed by <role> <actor> via <tool>)`.
+     A digest that no longer matches the brief is `RELAY_DIGEST_MISMATCH`: show
+     it again. Without `--relayed-via` an agent role gets `HUMAN_ONLY`, and so
+     does a repo whose `canon.yaml` says `approval: { relay: deny }`: then the
+     human runs the call themselves. Never remove or unset your role
+     (`env -u CANON_ROLE`, dropping `--as`) to run it yourself.
   Never edit the policy to make the gate pass: a policy that differs from
   the approved one fails closed (`POLICY_CHANGED_SINCE_APPROVAL`, not
   waivable); stop and ask the human. A brief edited after its
   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 <subject-id> --change-id <change>`
-  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. `canon skills show canon-subject`
+- **Approval is scoped.** Evidence for a scenario tagged `@flow:<change>.<F-id>`
+  needs the approval of the changes its tags name only, so a new unapproved
+  change on a live subject waits on its own scenarios; an untagged scenario
+  answers to every change with an `Approved:` line (an edited one refuses); `change new` and
+  `subject adopt` warn when the subject is live. `canon subject unadopt <subject-id> --change <change>`
+  takes a draft change back off (refused once approved). The subject
+  answers for every adopted change that is tagged (a scenario of the subject
+  is tagged `@flow:<change>.*`), has an `Approved:` line, or is a chore:
+  reopen and ship pass only when all of them are approved now, whatever the
+  order they were adopted or approved in, and `canon status` lists one entry
+  per such change in `briefs`. A pending draft (never approved, not a chore,
+  tagged by no scenario) blocks nothing and the transition prints one line
+  naming every draft; a draft a scenario is tagged for blocks until it is
+  approved. `canon skills show canon-subject`
 - **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,
@@ -69,7 +90,7 @@ a feature, a one-line request included. A human is needed once per scope:
   so in your report. That covers the brief's questions and work inside an
   approved scope, never the approval itself.
 
-1. **Brief.** The planner writes the PRD brief (`.canon/changes/<slug>/brief.md`), checks it with `canon brief check`, and stops for the human. `canon skills show role-planner`
+1. **Brief.** The planner writes the PRD brief (`.canon/changes/<slug>/brief.md`), checks it with `canon brief check`, shows it to the human, asks, and records their explicit approval. `canon skills show role-planner`
 2. **Subject.** `canon subject new`, then `canon change new` (`--change-kind chore` for work that alters no behavior); the change writes the brief skeleton. `canon skills show role-planner`
 3. **Scenarios.** `canon scenario new --flow <F-id> --case <case>` per behavior of a flow step, failure paths (`--case failure`) included; many at once with `--input` (below). `canon skills show role-implementer`
 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.
@@ -110,7 +131,7 @@ needs its change-level review alone. What counts as code is `code.exclude` in
 `canon status`, `meta.next` and the refusal hint lead with one batch over
 every report, for example
 `canon evidence add --all-scenarios --report junit:a.xml --report junit:b.xml --role implementer`
-(with the real report paths, and `--project-id <id>` when the repo has several
+(with the real report paths, and `--project <id>` when the repo has several
 spec roots), never a loop per scenario. With a `--report`, `--class` defaults
 to `test-run` and `--ref` to the report paths, and the bound cases decide the
 verdict: any failed case `divergent`, a skipped one and none failed
@@ -137,6 +158,25 @@ refuse, never pass, when it cannot be reached. Moving an existing store with
 `canon artifacts move --tier <tier>` is the repo owner's decision, not a step
 of the loop.
 
+### Search and trace
+
+`canon search "<text>"` finds a record, a brief section or flow step, or a
+scenario's text (title, steps, tables, `Examples`, the Background and Rule it
+inherits) and lists each hit with its neighbors in the record graph: the
+records it names or that name it, the review loop around a finding, the brief
+step a scenario covers. A reference no committed source holds is a neighbor
+marked `placeholder`, never an error. `--kind` (repeatable) keeps hits of those
+kinds, `--expand <N>` sets the hops (default 1), `--limit <N>` the hits (default
+20). Korean is found from three characters; a shorter text is found as a part of
+a node's text, in id order. The text is read as typed: quotes and `AND` are not
+syntax. `canon trace <finding key|review id|sha>` follows the review, finding,
+fix, re-review and evidence chain of a loop in time order, the archive's
+earlier versions included. Both read, and first refresh, a derived index,
+`.canon/index/search.db`: gitignored, never a source of records, safe to delete
+(the next run rebuilds it, and only `data.index.rebuilt` differs). Records still
+staged, and those in postgres or an object store, are not in it; `data.index`
+names the stores not read.
+
 ## Know your role
 
 canon cannot detect a role; you declare it. Pass `--as <role>` or set
@@ -175,7 +215,7 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
   `warnings` and, for a repeated write that changed nothing, `unchanged: true`.
   On failure branch on `error.code`, fix the option `error.field` names
   using the `error.expected` values (`field` is an option name, or a JSON
-  pointer such as `/items/2/scenarioId` into an `--input` document), and
+  pointer such as `/items/2/scenario` into an `--input` document), and
   follow `error.hint`: every refusal carries a working invocation. The codes
   are stable; `canon schema --errors --json` lists them and
   `canon schema --error <CODE>` explains one.
@@ -185,22 +225,27 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
   A refusal leaves the tree unchanged.
 - Repeating a write is safe: a record that already exists with identical
   content is reported `unchanged` (`meta.unchanged`), not duplicated.
-- Flags that name an id are spelled `--<noun>-id` everywhere (`--change-id`,
-  `--project-id`, `--subject-id`, `--scenario-id`, `--actor-id`,
-  `--session-id`), the primary object of a command is its operand
+- An option that takes an id is the bare noun (`--change add-login`,
+  `--scenario auth.login.01`, `--actor reviewer-1`, `--project root`,
+  `--session s-1`), and an `--input` document key is that name without `Id`
+  (`scenario`, `actor`; the stored record and report JSON keep `scenario_id`,
+  `scenarioId`). The primary object of a command is its operand
   (`canon subject move <id> --to verifying`, `canon change new <slug>`), and
   `--kind` values carry no `_record` suffix (`--kind evidence`).
 - `canon status` sends the planner to write the brief while `brief check`
-  has blockers; the human stop appears only when the brief is clean and
+  has blockers; the approval step appears only when the brief is clean and
   unapproved.
 - Page long lists with `--limit <n>` and `--cursor <nextCursor>` (`--all`
   for everything), and project fields with `--fields a,b` (`status`, `export`,
   `query`, `finding list`, `divergence list`, `context`).
 - `--override-reason <text>` is the only way to proceed past a waivable
   refusal; it is recorded, echoed in `data.overrides[]` and listed by `status`
-  for the human. There is no `--force`. `brief approve`, `policy approve` and
-  `divergence accept` are human-only and refuse every agent role: report the
-  exact call, ids filled in, and wait; never unset your role to run one.
+  for the human. There is no `--force`. `brief approve`, `policy approve`,
+  `divergence accept` and the `migrate --commit` that re-binds `Approved:`
+  lines record a human's decision and refuse every agent role (`HUMAN_ONLY`)
+  unless they record the explicit answer the human gave you, with
+  `--relayed-via <tool>` (show, ask, record, as for the brief; `canon skills
+  show role-planner`); never unset your role to run one.
 
 ### Many records at once: `--input`
 
@@ -218,8 +263,8 @@ before anything is written: an invalid element writes nothing and exits 2,
 
 ```text
 canon scenario new --input '[{"operands":["auth.login.01"],"title":"Logs in","case":"happy"},{"operands":["auth.login.02"],"title":"Wrong password","case":"failure"}]'
-canon evidence add --input '[{"scenarioId":"auth.login.01","class":"test-run","ref":"npm test","role":"implementer"},{"scenarioId":"auth.login.02","class":"test-run","ref":"npm test","role":"implementer"}]'
-canon finding add --input '[{"changeId":"add-login","round":1,"seq":1,"severity":"note","actorId":"reviewer-1","summary":"Token is logged"},{"changeId":"add-login","round":1,"seq":2,"severity":"blocker","introducedUnknown":true,"actorId":"reviewer-1","summary":"No rate limit"}]'
+canon evidence add --input '[{"scenario":"auth.login.01","class":"test-run","ref":"npm test","role":"implementer"},{"scenario":"auth.login.02","class":"test-run","ref":"npm test","role":"implementer"}]'
+canon finding add --input '[{"change":"add-login","round":1,"seq":1,"severity":"note","actor":"reviewer-1","summary":"Token is logged"},{"change":"add-login","round":1,"seq":2,"severity":"blocker","introducedUnknown":true,"actor":"reviewer-1","summary":"No rate limit"}]'
 ```
 
 `--input` never carries `--commit` or `--plan-digest`, and the destructive
@@ -293,10 +338,10 @@ on the list.
 
 - **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. `canon skills show role-implementer`.
 - **Add or change a feature:** `canon subject new`, `canon change new`, then the brief. `canon skills show role-planner`.
-- **Pure refactor, dependency, build, CI or infra:** `canon change new <slug> --subject-id <id> --change-kind chore`; data or interface changes are not chores. `canon skills show role-planner`.
+- **Pure refactor, dependency, build, CI or infra:** `canon change new <slug> --subject <id> --change-kind chore`; data or interface changes are not chores. `canon skills show role-planner`.
 - **Review someone's change:** `CANON_ROLE=reviewer`, `canon brief check <slug>`. `canon skills show role-reviewer`.
 - **Resume:** `canon status --json`, then follow `meta.next`. `canon skills show role-orchestrator`.
-- **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). `canon skills show canon-subject`, `canon skills show role-planner`.
+- **Plan more work on a live subject:** `canon change new <slug> --subject <id>` (it warns until the brief is approved; `canon subject unadopt` parks a draft). `canon skills show canon-subject`, `canon skills show role-planner`.
 - **Upgrade canon in a repo:** `canon migrate` (previews), then `canon migrate --commit --plan-digest <digest>`, then `canon skills install`. See "Upgrading a repo from 0.27" above and `canon skills show role-orchestrator`.
 
 **Done when:** you have named your role and loaded its guide, and `canon status --json` lists your next step in `meta.next`.
@@ -317,7 +362,7 @@ current step needs.
 | Name | What it is for |
 | --- | --- |
 | `canon` | This core guide: the loop, driving the CLI, routing. |
-| `role-planner` | Planner steps 1–2: subject, change, PRD brief, the human stop. |
+| `role-planner` | Planner steps 1–2: subject, change, PRD brief, the approval. |
 | `role-implementer` | Implementer steps 3–6: scenarios, units, code, evidence. |
 | `role-reviewer` | Reviewer step 7: findings and signed reviews in a separate session. |
 | `role-orchestrator` | Orchestrator step 8: dispatch, transitions, resuming, upgrading. |

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

@@ -33,7 +33,7 @@ A chore adds no scenarios and has no flow: this pass does not apply to it.
 
 ## Next
 
-Implement, evidence and review (loop steps 5 to 7). If the brief had to change, the human answers again with `canon brief approve` (theirs; agent roles are refused).
+Implement, evidence and review (loop steps 5 to 7). If the brief had to change, the human answers again: show the brief, ask, and record an explicit approval with `--relayed-via` (`canon skills show role-planner`).
 
 ## Invariants (every brief pass)
 
@@ -41,4 +41,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 (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 the human's `canon brief approve` again (agent roles are refused).
+- 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, shown and asked again, and a new `canon brief approve` (recorded with `--relayed-via` from that answer).

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

@@ -33,7 +33,7 @@ Every open line is a question with a proposed default or a stated assumption. `c
 
 ## Next
 
-`harden` if the flow changed; otherwise report to the human, who answers the questions and approves (`canon brief approve` is theirs; agent roles are refused).
+`harden` if the flow changed; otherwise put the questions and the brief to the human and ask; record an explicit approval with `brief approve` with `--relayed-via <tool>` (`canon skills show role-planner`).
 
 ## Invariants (every brief pass)
 
@@ -41,4 +41,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 (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 the human's `canon brief approve` again (agent roles are refused).
+- 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, shown and asked again, and a new `canon brief approve` (recorded with `--relayed-via` from that answer).

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

@@ -34,7 +34,7 @@ brief has none of them: harden its Invariants and Checks instead.
 
 ## Next
 
-`align` (`canon skills show brief-align`) once scenarios exist; `polish` (`canon skills show brief-polish`) for prose; otherwise report to the human.
+`align` (`canon skills show brief-align`) once scenarios exist; `polish` (`canon skills show brief-polish`) for prose; otherwise show the brief to the human and ask (`canon skills show role-planner`).
 
 ## Invariants (every brief pass)
 
@@ -42,4 +42,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 (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 the human's `canon brief approve` again (agent roles are refused).
+- 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, shown and asked again, and a new `canon brief approve` (recorded with `--relayed-via` from that answer).

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

@@ -2,7 +2,7 @@
 
 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
+`meta.next` name it before the approval step. 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.
 
@@ -151,7 +151,7 @@ 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" -->`
+- waive one date: frontmatter entry `rule: prose.decision-history`, `section: detail`, `reason: "연체 요금은 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
@@ -209,8 +209,8 @@ uses the section key `brief`.
 
 - `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).
+  an entry of the frontmatter `waive` list: `- rule: <rule-id>`, `section: <section-key>`, `reason: "<reason>"`.
+  To waive one finding and keep the rest of the rule live in that section, add the text the finding names as `match: "<text>"` (an empty reason or match, an unknown rule id or an unknown key is a blocker).
   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
@@ -218,13 +218,13 @@ uses the section key `brief`.
 1. Fix the mode problems above, then the findings, section by section.
 2. Run `canon brief check <slug> --json`: the findings are in `data.findings[]`.
 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.
+4. Stop polishing and show the brief to the human (`canon brief show <slug> --body`), in the brief's language, and ask. 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 (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 touch flow ids or subheadings, and never polish the headings.
 - Never translate the brief to match a `language:` setting.
 - Never treat a clean run as a claim about who wrote the brief.
 
@@ -236,7 +236,7 @@ uses the section key `brief`.
 
 ## Next
 
-Report to the human, who approves with `canon brief approve` (theirs; agent roles are refused).
+Show the brief to the human and ask (`canon brief show <slug> --body`, then the harness question tool); record an explicit approval with `brief approve` with `--relayed-via <tool>` (`canon skills show role-planner`).
 
 ## Invariants (every brief pass)
 
@@ -244,4 +244,4 @@ Report to the human, who approves with `canon brief approve` (theirs; agent role
 - 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 (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 the human's `canon brief approve` again (agent roles are refused).
+- 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, shown and asked again, and a new `canon brief approve` (recorded with `--relayed-via` from that answer).

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

@@ -8,26 +8,57 @@ check reports `brief.section-missing`, `brief.section-duplicate`,
 
 ## Scope
 
-`.canon/changes/<slug>/brief.md`: section markers, order, and leftover
+`.canon/changes/<slug>/brief.md`: section headings, order, and leftover
 template text. A feature brief runs intent → outcome → flow → detail →
 acceptance → questions → out-of-scope; a chore brief runs intent → category →
-invariants → checks → out-of-scope (`<!-- canon:kind chore -->` under the
-title). Sections are found by their `<!-- canon:section <key> role=… -->`
-marker, never by heading text.
+invariants → checks → out-of-scope (`kind: chore` in the frontmatter). Sections
+are found by their English `##` heading, whatever the brief's language; a
+`##` line that is not one of the headings below is body text of the section
+before it. `language:` only picks the language of the prose rules and the
+guidance.
+
+| Section | Heading | Role | What goes in it |
+| --- | --- | --- | --- |
+| intent | `## Intent` | context | What problem this solves, for whom, and why now. One to three sentences. |
+| outcome | `## Desired outcome` | normative | What is observably true once this ships, from the user's side. |
+| flow | `## User flow` | normative | A numbered list; each item starts with its id and reads sees → does → becomes: `1. F1 The user sees … → does … → becomes …`. |
+| detail | `## Step detail` | normative | One `### F1 …` subheading per flow step, in the flow's order: rules, states and edge cases of that step. |
+| acceptance | `## Acceptance` | normative | Per step: what must be observable, and which failure path is covered. Do not write scenario ids here. |
+| questions | `## Questions and assumptions` | question | What is unresolved and what you assumed; anything that could change policy goes here. Write `None.` if nothing. |
+| out-of-scope | `## Out of scope` | context | What this change deliberately does not do. Write `None.` if nothing. |
+| category (chore) | `## Category` | context | Exactly one of `refactor`, `dependency`, `build`, `ci`, `infra`. |
+| invariants (chore) | `## Invariants` | normative | What must not change: behavior, public interfaces, data, outputs. A change that alters any of them is a feature, not a chore. |
+| checks (chore) | `## Checks` | normative | How you show the invariants held: the suite that is run again at the chore commit, and anything else you compare. |
+
+`canon change new` writes the brief with these headings and nothing under
+them: an empty section is a section not yet written, and `canon brief show`
+prints the guidance of each empty one (in `language:`). A wrong heading
+(`## Intnet`, `## intent`) is reported with the nearest heading.
 
 ## Inspect
 
 - `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).
+- Every section present once, in order, with its exact English heading; 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 (optionally with `match="<text>"`) is well formed with a real reason.
+- Waivers live in the frontmatter, visible on the page, and the approval covers them:
+  ```
+  ---
+  waive:
+    - rule: prose.length
+      section: brief
+      reason: "why the rule does not apply"
+      match: "optional text the finding contains"
+  ---
+  ```
+  Each entry has a known `rule`, a `section` key (or `brief`) and a non-empty `reason`; an unknown key is a blocker. Adding one after the approval is a change after the approval.
+- A brief that still has `<!-- canon:… -->` comments or Korean headings is in the old format: `canon migrate` (preview first) rewrites it, and the human runs `--commit` when it re-binds an approval.
 
 ## NEVER
 
 - Never fill a section with text you made up to silence a placeholder: write what the request and the repo support, and put the rest in Questions.
-- Never delete a section, retag a marker's role, or add a global waiver to pass. A waiver is one rule in one section with a reason the human can read.
+- Never delete a section, rename a heading to another role, or add a global waiver to pass. A waiver is one rule in one section with a reason the human can read.
 - Never turn a chore's missing invariants into "none" to pass: behavior-changing work is a feature change.
 
 ## Verify
@@ -38,7 +69,7 @@ marker, never by heading text.
 
 ## Next
 
-`clarify` if the Questions section still has open lines; `harden` if flow and detail disagree; otherwise report to the human, who approves with `canon brief approve` (theirs; agent roles are refused).
+`clarify` if the Questions section still has open lines; `harden` if flow and detail disagree; otherwise show the brief to the human and ask; record an explicit approval with `brief approve` with `--relayed-via <tool>` (`canon skills show role-planner`).
 
 ## Invariants (every brief pass)
 
@@ -46,4 +77,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 (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 the human's `canon brief approve` again (agent roles are refused).
+- 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, shown and asked again, and a new `canon brief approve` (recorded with `--relayed-via` from that answer).

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

@@ -84,7 +84,7 @@ enum, like `lane`.
 ## Subject pinning
 
 Every scenario belongs to a Subject (the durable product unit, see
-`canon-subject`). Write the Subject first, then pin with `--subject-id`;
+`canon-subject`). Write the Subject first, then pin with `--subject`;
 the scenario index carries the tag onto the index record and
 `spec_coverage.scope` filters on it. An unpinned scenario is invisible to
 a scoped gate.
@@ -94,9 +94,9 @@ a scoped gate.
 ```bash
 canon feature new checkout.cart --title "Cart"                       # once per surface
 canon scenario new checkout.cart.01 --title "Adding an item raises the count" \
-  --subject-id checkout-core --lane behavior --case happy               # once per behavior
+  --subject checkout-core --lane behavior --case happy               # once per behavior
 canon scenario new checkout.cart.04 --title "Adding an out-of-stock item is refused" \
-  --subject-id checkout-core --lane behavior --case failure             # and its failure path
+  --subject checkout-core --lane behavior --case failure             # and its failure path
 ```
 
 There is no format or sync step after these: the scaffold writes a
@@ -115,10 +115,10 @@ camelCase keys. `canon schema scenario new --json` shows the input schema
 and an example. There is no `--from`.
 
 ```text
-canon scenario new --input '[{"operands":["checkout.cart.01"],"title":"Adding an item raises the count","subjectId":"checkout-core","lane":"behavior","case":"happy"},{"operands":["checkout.cart.04"],"title":"Adding an out-of-stock item is refused","subjectId":"checkout-core","lane":"behavior","case":"failure"}]'
+canon scenario new --input '[{"operands":["checkout.cart.01"],"title":"Adding an item raises the count","subject":"checkout-core","lane":"behavior","case":"happy"},{"operands":["checkout.cart.04"],"title":"Adding an out-of-stock item is refused","subject":"checkout-core","lane":"behavior","case":"failure"}]'
 ```
 
-- `--actor-id <id>` (or `CANON_ACTOR` in the environment) puts YOUR id on the
+- `--actor <id>` (or `CANON_ACTOR` in the environment) puts YOUR id on the
   provenance line. Default is `canon-scaffold`.
 - **Keep the `# canon:` lines when you fill in the scenario.** Dropping one
   makes `canon inventory sync` abort on `missing-provenance`; restore it
@@ -160,7 +160,7 @@ wait for evidence, which `canon gate check` reports.
 - **A Feature title that is a theme.** "Fidelity of the original
   experience" names no surface. Name the screen.
 - **Hand-stamped provenance.** Eighty lines with one timestamp and the
-  same `agent_id`. Use `canon scenario new --actor-id`.
+  same `agent_id`. Use `canon scenario new --actor`.
 - **Coverage by splitting.** One behavior as two scenarios so two rows go
   green. One behavior, one id.
 - **Runner tags as classification.** `@design`, `@p2`, `@wip` are