@journeykit/canon 0.29.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","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
@@ -252,7 +278,7 @@ and `canon context` warn when the repo holds 0.27-era state and put
 2. `canon migrate --commit --plan-digest <digest>` with that digest applies it.
    It moves the layout, rewrites canon's own hooks and scripts, compacts the
    ledger, replaces an old full skill with the stub, and backs up every file it
-   rewrites under `.canon/migrate-backup/`. It refuses uncommitted changes
+   rewrites under `.canon/migrate-backup/` (local and git-ignored; `--revert` needs it). It refuses uncommitted changes
    under a path it moves.
 3. `canon skills install` refreshes the stub and the scripts; `canon skills check`
    confirms them.
@@ -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`
@@ -205,14 +205,20 @@ Two refusals rather than a silent pass, both surfacing as
   `divergence`, or `subject` sent anywhere but `local`) refuses, because
   the gate reads one tier and would otherwise pass by seeing nothing.
 
-Malformed rows in those three kinds do NOT surface as
+Unparseable rows in those three kinds do NOT surface as
 `malformed-evidence`; they are kept off the evidence violation set on
-purpose, so enabling nothing changes no existing verdict.
+purpose, so enabling nothing changes no existing verdict. A row whose file
+name is not the one its body computes (a layout violation) is the
+exception once `spec_coverage` judges the corpus: the gate names it as
+`malformed-evidence`, because every read skips it and the corpus being
+judged would otherwise be missing it silently. Without the section the
+gate stays as it was; `canon query --kind <kind>` and `canon status`
+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
@@ -234,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
@@ -253,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,
@@ -297,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>"`
@@ -335,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
@@ -370,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
@@ -431,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
@@ -490,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>`
@@ -515,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[]`.
 
@@ -546,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
@@ -678,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]`
@@ -700,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.
 
@@ -773,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,
@@ -182,7 +186,7 @@ In `canon report`'s own render order. Each panel names the view that
 computes it; nothing here is derived a second time.
 
 - **Trust matrix** (`mart_trust_matrix`) — Change/task coverage × green × who.
-  `covered` means at least one `evidence_record` exists for this `task_id`,
+  `covered` means at least one `evidence` record exists for this `task_id`,
   NOT that policy's REQUIRED evidence is present — that is `canon gate
   check`'s question, and this view deliberately does not answer it. `green`
   is the plain `verdict = 'faithful'` proxy over the latest attestation, not
@@ -258,7 +262,7 @@ computes it; nothing here is derived a second time.
 - **Review rounds** (`mart_review_rounds`) — one row per `(change_id, round)`
   over `Finding` records (`canon finding add`, then `canon finding close` to
   move a finding's disposition), folded to the latest version
-  of each `{change_id}__{round}__{seq}` finding first, so a finding raised
+  of each `(change_id, round, seq)` finding first, so a finding raised
   `open` and later closed is counted once and in one disposition bucket.
   A round that found
   nothing wrote no `Finding` and so has no row: the table