@journeykit/canon 0.30.0 → 0.31.0

package/dist/skills/SKILL.src.md

@@ -34,8 +34,9 @@ a feature, a one-line request included. A human is needed once per scope:
   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
+  `canon brief approve <slug> <slug> --approver <their name> --note "<their words>"`
+  (one or more slugs, one answer for all, nothing written if any is refused)
+  refuses every agent role (`HUMAN_ONLY`). Report that exact call, every slug filled in, and
   wait; 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
@@ -43,16 +44,20 @@ a feature, a one-line request included. A human is needed once per scope:
   approval is not approved (`BRIEF_CHANGED_SINCE_APPROVAL`): it needs a new
   answer. The ship guard and `canon evidence add` refuse an unapproved or
   edited brief, but those are backstops: the stop itself is at step 1.
-- **Approval is scoped.** Evidence for a scenario needs the approval of the
-  changes its `@flow:<change>.<F-id>` tags name, so a new unapproved change
-  on a live subject waits on its own scenarios only; `change new` and
-  `subject adopt` warn when the subject is live. `canon subject unadopt <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,
@@ -110,7 +115,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 +142,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 +199,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,9 +209,11 @@ 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`
@@ -218,8 +244,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 +319,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`.

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

@@ -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
@@ -224,7 +224,7 @@ uses the section key `brief`.
 
 - 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.
 

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

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

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

@@ -129,11 +129,11 @@ A present section, even `require_evidence: false` or a malformed one
 
 - **Unimplemented** — no `EvidenceRecord` carries the scenario's
   `(project_id, scenario_id)`. Author one with
-  `canon evidence add --scenario-id <id> --project-id <root-id>`; the
+  `canon evidence add --scenario <id> --project <root-id>`; the
   root id is needed once more than one spec root is configured, because
   two roots may carry the same scenario id. `--summary` is allowed here too (scanned for fabrication
   markers like a task's); it is a row suffix only when the record also
-  names a `--task-id`. A record carrying both `--task-id` and `--scenario-id`
+  names a `--task`. A record carrying both `--task` and `--scenario`
   is one attestation answering both joins: it counts for the task cell
   and for the scenario cell (verdicts, the shipped gate, the review gate).
 - **Mismatched** — the folded divergence state is `open`,
@@ -161,7 +161,7 @@ A present section, even `require_evidence: false` or a malformed one
   (a review written before 0.15 has no pins and skips this check), and,
   when `distinct_actor` (default `true`), is by a reviewer and actor
   other than the scenario's evidence actor and from a session other than
-  any evidence session when both carry one (`--session-id`);
+  any evidence session when both carry one (`--session`);
   gaps are `unreviewed-promotion`, and the detail says whether the
   review is missing, a self-review, stale (naming whether the spec, the
   evidence or both changed), or not signed. With `block_on_findings`
@@ -218,7 +218,7 @@ report such files.
 ### Accepted divergence and re-verification
 
 ```bash
-canon divergence accept cart.add.01 --project-id root --reason "known gap" --tracking "issue#12" --expiry 2026-12-31 --actor-id reviewer-2 --role reviewer --session-id review-session-1
+canon divergence accept cart.add.01 --project root --reason "known gap" --tracking "issue#12" --expiry 2026-12-31 --actor reviewer-2 --role reviewer --session review-session-1
 ```
 
 Accepting a scenario whose latest evidence is `divergent` as a known gap
@@ -240,10 +240,10 @@ Re-verification is one rule with two triggers: a blocker whose latest
 disposition is `fixed`, and a chore change once approved, keep the subject
 from shipping until every one of its evidenced scenarios has evidence
 recorded after the close or the approval. A blocker that names its
-scenarios (`finding add --scenario-id`) asks only those, and the refusal
-names them with the per-scenario command (`canon evidence add --project-id
-<root-id> --scenario-id <id> --report <format>:<path>` plus `--class`, `--role` and `--ref`). Otherwise the
-refusal names the scenarios and the batch command: `canon evidence add --project-id <root-id>
+scenarios (`finding add --scenario`) asks only those, and the refusal
+names them with the per-scenario command (`canon evidence add --project
+<root-id> --scenario <id> --report <format>:<path>` plus `--class`, `--role` and `--ref`). Otherwise the
+refusal names the scenarios and the batch command: `canon evidence add --project <root-id>
 --all-scenarios --report <format>:<path> --class test-run --role
 implementer --ref "<test command>"`. Reviews pin what the evidence says
 (its verdict and the identity of its checks), not which record it is, so
@@ -259,17 +259,17 @@ canon never generates or runs an audit. An external evaluator does, and
 canon records its result:
 
 ```bash
-canon evidence audit cart.add.01 --project-id root \
+canon evidence audit cart.add.01 --project root \
   --ref "judge run 42" --role reviewer \
-  --evaluator-id judge --evaluator-version 1.2 \
+  --evaluator judge --evaluator-version 1.2 \
   --evaluator-digest 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 \
   --audit-result refuted --report junit:audit/counterexample.xml
 ```
 
-- `evidence audit` requires the scenario operand, `--ref`, `--evaluator-id`,
+- `evidence audit` requires the scenario operand, `--ref`, `--evaluator`,
   `--evaluator-version`, `--evaluator-digest` (sha256, 64 lowercase hex)
-  and `--audit-result confirmed|refuted|indeterminate`, with `--project-id`
-  where several spec roots exist. It takes no `--task-id`, `--verdict`,
+  and `--audit-result confirmed|refuted|indeterminate`, with `--project`
+  where several spec roots exist. It takes no `--task`, `--verdict`,
   `--surface-ref` or `--approval-*`; the evaluator flags exist on no other
   command. All refusals exit `2`.
 - The record carries `audit: {evaluator_id, evaluator_version,
@@ -303,15 +303,15 @@ The approval is never assumed: the agent writes the brief, stops and
 reports it, and builds nothing for that scope until the human answers.
 `canon evidence add` is the backstop for that stop (0.16 M7). It
 refuses (exit `1`, nothing staged or stored) while a subject the record
-attests for has an enforced, unapproved brief: the newest adopted
-change's canon `.canon/changes/<change>/brief.md` has no `Approved:`
+attests for has an enforced, unapproved brief: a change the record
+answers to (below) has a canon `.canon/changes/<change>/brief.md` with no `Approved:`
 line, was edited after its approval (`BRIEF_CHANGED_SINCE_APPROVAL`), or
 there is no canon `brief.md` yet but the change comes from an
 external openspec plan with a `proposal.md` under the plan sources (the
 check `canon status` and the ship guard use; see
 `canon-subject`; which changes a scenario answers to is scoped by its `@flow:<change>.<F-id>` tags, described there). The subjects are the scenario's `@subject` owner for
-`--scenario-id`, and every subject adopting the task's change for
-`--task-id`:
+`--scenario`, and every subject adopting the task's change for
+`--task`:
 
 ```stderr
 canon evidence add: unreviewed-promotion demo-subject — evidence for world.demo.01: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line, so the human has not answered it; once they do, record their words with `canon brief approve c-demo --approver <the human> --note "<their words>"`
@@ -341,7 +341,7 @@ brief_override:
   reason: the human approved in chat; the line follows
   waived:
     - { class: unreviewed-promotion, subject: demo-subject }
-  actor: { agent_id: lead }   # from --actor-id
+  actor: { agent_id: lead }   # from --actor
 ```
 
 Under `--json` the same waiver is `data.overrides[]` (`code` of the waived
@@ -376,8 +376,9 @@ review waivers: 1 advisory(ies) — not failing the gate:
 The waiver lasts only until the subject's next status write.
 
 `canon subject move <id> --to shipped` also refuses where a brief exists and
-is not approved (the subject's scope, its newest adopted change walking back past pending drafts
-no scenario is tagged `@flow:<change>.*` for, has a canon
+is not approved (a change the subject answers for, that is one a scenario of
+the subject is tagged `@flow:<change>.*` for, one with an `Approved:` line,
+or a chore, has a canon
 `brief.md` with no `Approved:` line or one the brief's text no longer
 matches, or an external `proposal.md` and no canon `brief.md` yet;
 see `canon-subject`), as an `unreviewed-promotion` naming
@@ -437,14 +438,14 @@ what backed the claim:
 
 ```bash
 # any file: a Playwright trace, screenshots, an agent QA log — by sha256
-canon evidence add --scenario-id cart.add.04 --project-id root \
+canon evidence add --scenario cart.add.04 --project root \
   --class agent-qa --ref "stagehand run 7" --role implementer \
   --artifact test-results/cart-trace.zip
 # a JUnit XML or Cucumber JSON report: also records the matched case + outcome
-canon evidence add --scenario-id cart.add.04 --project-id root --class test-run --ref "cargo nextest run" --role implementer --report junit:target/nextest/default/junit.xml
-canon evidence add --scenario-id cart.add.04 --project-id root --class test-run --ref "cucumber-js" --role implementer --report cucumber:reports/cucumber.json
+canon evidence add --scenario cart.add.04 --project root --class test-run --ref "cargo nextest run" --role implementer --report junit:target/nextest/default/junit.xml
+canon evidence add --scenario cart.add.04 --project root --class test-run --ref "cucumber-js" --role implementer --report cucumber:reports/cucumber.json
 # a Swift Testing event stream (swift test --experimental-event-stream-output <path>)
-canon evidence add --scenario-id cart.add.04 --project-id root --class test-run --ref "swift test" --role implementer --report swift-testing:.build/events.jsonl
+canon evidence add --scenario cart.add.04 --project root --class test-run --ref "swift test" --role implementer --report swift-testing:.build/events.jsonl
 ```
 
 A case is bound when the scenario id is its OWN: the first
@@ -496,12 +497,12 @@ not close it.
 One test run proves many scenarios. Bind it once:
 
 ```bash
-canon evidence add --project-id root --all-scenarios \
+canon evidence add --project root --all-scenarios \
   --report junit:target/nextest/default/junit.xml \
   --class test-run --ref "cargo nextest run" --role implementer
 ```
 
-Each indexed scenario of `--project-id` that owns a case (the rule above)
+Each indexed scenario of `--project` that owns a case (the rule above)
 gets its own record, with only its own cases. Its verdict comes from
 them: `faithful` when every case passed, `divergent` when one failed,
 `not-applicable` when one was skipped and none failed. `--verdict <v>`
@@ -521,18 +522,18 @@ It is all or nothing: a claimed `faithful` verdict over a failed case,
 a fabrication marker in `--summary`, an unapproved brief for any
 scenario's subject refuses the whole batch, and nothing is written. Each
 record binds only what the batch names (nothing is carried forward).
-`--scenario-id`, `--task-id`,
+`--scenario`, `--task`,
 `--report-case`, `canon evidence audit` and the approval flags name one subject
 and are refused with `--all-scenarios`.
 
-A task's evidence with `--report` and no `--scenario-id` binds EVERY case
+A task's evidence with `--report` and no `--scenario` binds EVERY case
 in the report, so a `faithful` verdict needs all of them to pass.
 
 Many records at once without a report: `--input` takes inline JSON, a file
 or `-`; an array (or NDJSON) is a batch, validated element by element before
 the first write (a refusal writes nothing, exit 2). Keys are the option
 names in camelCase plus `operands`: one object per scenario, with
-`scenarioId`, `class`, `ref` and `role`. `canon schema evidence add --json`
+`scenario`, `class`, `ref` and `role`. `canon schema evidence add --json`
 shows the input schema and an example. Each element reports `written`,
 `unchanged` or `failed` in `data.items[]`.
 
@@ -552,7 +553,7 @@ current pinned review saw, `canon evidence add` prints one line per
 review it makes stale (its verdict or checks differ from what the review saw), with the command that re-pins it:
 
 ```stderr
-canon evidence add: review by `reviewer-2` of cart.add.01 is now stale (this record's verdict or checks differ from what it saw); re-pin it: canon review scenario cart.add.01 --project-id root --actor-id reviewer-2 --role reviewer --original-spec-ref specs/kind=feature/area=cart/add.feature
+canon evidence add: review by `reviewer-2` of cart.add.01 is now stale (this record's verdict or checks differ from what it saw); re-pin it: canon review scenario cart.add.01 --project root --actor reviewer-2 --role reviewer --original-spec-ref specs/kind=feature/area=cart/add.feature
 ```
 
 The decision is the gate's own (the same stale-review rule `canon gate
@@ -684,7 +685,7 @@ task at all is a loud failure naming every source consulted. A repo with
 no `.canon/changes/` and `sources: []` is refused: "this repo configures
 no plan sources (no `.canon/changes` and no `plans.sources` entries in
 canon.yaml) … write the change with `canon change new`, or list your
-external plans under `plans.sources`" (`canon dispatch begin --task-id` says the
+external plans under `plans.sources`" (`canon dispatch begin --task` says the
 same).
 It requires
 a matching non-`Divergent` evidence record, and flips `- [ ]` → `- [x]`
@@ -706,7 +707,7 @@ A flip on evidence that cannot prove the task still succeeds, but warns
 on stderr: when none of the task's evidence records binds a file and one
 of them cites a canon command as its `--ref` (`canon gate check`,
 `canon status`), the warning says to bind the artifact or report that
-proves the task (`canon evidence add --task-id <id> --artifact <path>` or
+proves the task (`canon evidence add --task <id> --artifact <path>` or
 `--report <format>:<path>`). A canon command reports on canon's own
 records, so it is never the proof of a task.
 
@@ -779,6 +780,14 @@ canon gate install-hooks --repo .
 canon gate install-hooks --repo . --event PreToolUse --matcher Edit --command "canon gate check" --timeout 30
 ```
 
+It installs no git hook: copy the script into git's `pre-commit` hook
+(`.git/hooks/pre-commit`) or call it from a hook runner. The output names the two
+agent hook files and the script, also under `--dry-run`. In `--json`,
+`installed` is true when an agent hook file changed and
+`preCommitScriptWritten` when the script was written. A `--repo` that is not an
+existing directory exits 2 with `HOOKS_INSTALL_FAILED` (also under `--dry-run`)
+and creates nothing.
+
 Prefer this over hand-editing `settings.json`/`hooks.json`.
 
 ## `canon selftest --suite trust-spine-gate`

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

@@ -183,9 +183,9 @@ record.
 An operator-requested rollback is a distinct authenticated action:
 
 ```text
-canon strategy rollback <strategy_id> --reason "<reason>" --actor-id alice \
+canon strategy rollback <strategy_id> --reason "<reason>" --actor alice \
   --signature-file rollback.sig --approval-at 2026-10-02T12:00:00Z \
-  [--contradicting-trajectory-id <trajectory_id>] --repo .
+  [--contradicting-trajectory <trajectory_id>] --repo .
 ```
 
 `--signature-file` is an armored SSH detached signature over the

package/dist/skills/reference/canon-plan-import.md

@@ -13,8 +13,8 @@ one, and neither can `canon gate`.
 one `<slug>/` directory per change holding `brief.md` (and a `tasks.md`
 only when someone adds one: an optional work note), written by
 `canon change new` (see `canon-subject`). Every plan reader —
-`canon ingest plans`, `canon task done`, `canon evidence add --task-id`,
-`canon dispatch begin --task-id`, `canon status` and the brief check — reads it
+`canon ingest plans`, `canon task done`, `canon evidence add --task`,
+`canon dispatch begin --task`, `canon status` and the brief check — reads it
 first whenever the directory exists, with no `plans:` entry. Being first,
 it owns a change id an external source also carries (the external copy
 is the later duplicate, skipped and counted under `duplicate_change_id`).

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

@@ -70,12 +70,12 @@ error; the next step (3) reads the overlay back.
 ## 3. Project a read
 
 ```bash
-canon query --kind scenario --plugin-id porting          # human table, projected fields appended
-canon query --kind scenario --plugin-id porting --json   # merged record bodies
-canon query --kind scenario                           # no --plugin-id: byte-identical to the core view
+canon query --kind scenario --plugin porting          # human table, projected fields appended
+canon query --kind scenario --plugin porting --json   # merged record bodies
+canon query --kind scenario                           # no --plugin: byte-identical to the core view
 ```
 
-`--plugin-id <id>` folds the plugin's overlay records (latest-by-
+`--plugin <id>` folds the plugin's overlay records (latest-by-
 `(join_key, at)`) onto each queried core record. Fail-soft everywhere:
 
 - No overlay record for a core key → that record projects UNMODIFIED (no
@@ -85,7 +85,7 @@ canon query --kind scenario                           # no --plugin-id: byte-ide
   SKIPPED + diagnosed; siblings still project.
 - An absent plugin/manifest → the unmodified core view + a diagnostic,
   never a process error.
-- Omitting `--plugin-id` is byte-identical to `canon query`'s output without
+- Omitting `--plugin` is byte-identical to `canon query`'s output without
   plugins — it's a purely additive layer.
 
 **Done when:** the projected table or JSON shows the plugin's fields on the
@@ -108,7 +108,7 @@ scenarios you synced.
    (zero new files) and a genuine coverage edit supersedes the prior
    overlay via latest-`at`-wins.
 3. `canon plugin sync porting` writes/dedupes those candidates.
-4. `canon query --kind scenario --plugin-id porting [--json]` projects
+4. `canon query --kind scenario --plugin porting [--json]` projects
    `covered`/`surface_ref` back onto each scenario.
 
 `canon gate check`'s verdicts are byte-identical with and without a

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

@@ -151,12 +151,16 @@ canon dashboard --snapshot /tmp/canon-snap --port 8080
 `/briefs.html` lists every live change whose brief awaits the human (no
 `Approved:` line, or edited since) with its intent, outcome, flow steps,
 acceptance, questions and assumptions, and its `canon brief check`
-blockers and advisories. The human types their name and their answer and
-clicks Approve: that records exactly what `canon brief approve
-<id> --approver <name> --note <text>` records, the `Approved:` line bound to the
-brief digest and the policy approval. It is refused when the brief changed
-after the page loaded (`BRIEF_CHANGED_SINCE_PAGE_LOAD`: reload) or while it
-has blockers (`BRIEF_APPROVE_REFUSED`). The server is localhost only and
+blockers and advisories. Each brief that has no blocker has a selection box
+and the page shows how many are selected. The human types their name and their
+answer once and clicks Approve: one request carries every selected brief with
+the sha256 of the file the page read, and records exactly what `canon brief
+approve <id>+ --approver <name> --note <text>` records, the `Approved:` line
+bound to the brief digest and the policy approval, for each. A brief that
+changed after the page loaded (`BRIEF_CHANGED_SINCE_PAGE_LOAD`) or that has
+blockers refuses the whole request (409 `BRIEF_APPROVE_REFUSED`, naming each
+refused brief): nothing is written and the page says to read it again. A request
+naming one brief the old way (`changeId`, `sha256`) is still accepted. The server is localhost only and
 refuses requests from other origins (`DASHBOARD_ORIGIN_REFUSED`).
 
 For an agent the human stop is unchanged: when clean briefs are waiting,