@journeykit/canon 0.29.0 → 0.31.0

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

@@ -51,17 +51,17 @@ canon context
 ```
 ```text
 # Add a divergence candidate, staged with no run_seq yet
-canon divergence add <SCENARIO_ID> --actor-id <ACTOR_ID> [--project-id <PROJECT_ID>] [--rev <REV>] [--state <open|still-divergent|resolved|deferred>] [--reason <TEXT>] [--expiry <TIMESTAMP>] [--round <N>] [--session-id <SESSION_ID>] [--detail <TEXT>] [--role <ROLE>] [--promote | --no-promote] [--input]
+canon divergence add <SCENARIO_ID> --actor <ACTOR_ID> [--project <PROJECT_ID>] [--rev <REV>] [--state <open|still-divergent|resolved|deferred>] [--reason <TEXT>] [--expiry <TIMESTAMP>] [--round <N>] [--session <SESSION_ID>] [--detail <TEXT>] [--role <ROLE>] [--promote | --no-promote] [--input]
 ```
 ```bash
-canon divergence add auth.login.01 --actor-id alice --role reviewer
+canon divergence add auth.login.01 --actor alice --role reviewer
 ```
 ```text
 # Directly record a deferred divergence (requires --reason/--expiry)
-canon divergence defer <SCENARIO_ID> --actor-id <ACTOR_ID> --reason <TEXT> --expiry <TIMESTAMP> [--project-id <PROJECT_ID>] [--rev <REV>] [--round <N>] [--session-id <SESSION_ID>] [--role <ROLE>] [--input]
+canon divergence defer <SCENARIO_ID> --actor <ACTOR_ID> --reason <TEXT> --expiry <TIMESTAMP> [--project <PROJECT_ID>] [--rev <REV>] [--round <N>] [--session <SESSION_ID>] [--role <ROLE>] [--input]
 ```
 ```bash
-canon divergence defer auth.login.01 --actor-id alice --reason "waiting on the vendor" --expiry 2030-01-01T00:00:00Z --role reviewer
+canon divergence defer auth.login.01 --actor alice --reason "waiting on the vendor" --expiry 2030-01-01T00:00:00Z --role reviewer
 ```
 ```text
 # List the current divergence burn-down state
@@ -72,31 +72,31 @@ canon divergence list --as-of 2030-01-01
 ```
 ```text
 # Directly record a resolved divergence
-canon divergence resolve <SCENARIO_ID> --actor-id <ACTOR_ID> [--project-id <PROJECT_ID>] [--rev <REV>] [--round <N>] [--session-id <SESSION_ID>] [--detail <TEXT>] [--role <ROLE>] [--input]
+canon divergence resolve <SCENARIO_ID> --actor <ACTOR_ID> [--project <PROJECT_ID>] [--rev <REV>] [--round <N>] [--session <SESSION_ID>] [--detail <TEXT>] [--role <ROLE>] [--input]
 ```
 ```bash
-canon divergence resolve auth.login.01 --actor-id alice --role reviewer
+canon divergence resolve auth.login.01 --actor alice --role reviewer
 ```
 ```text
 # Record one code-review finding
-canon finding add --change-id <CHANGE_ID> --round <N> --seq <N> --severity <blocker|should-fix|note> --actor-id <ACTOR_ID> --summary <TEXT> [--disposition <open|fixed|rejected|deferred>] [--rev <REV>] [--resolution-rev <REV>] [--introduced-rev <REV>] [--file-ref <TEXT>] [--scenario-id <SCENARIO_ID>]* [--role <ROLE>] [--session-id <SESSION_ID>] [--promote | --no-promote] [--input]
+canon finding add --change <CHANGE_ID> --round <N> --seq <N> --severity <blocker|should-fix|note> --actor <ACTOR_ID> --summary <TEXT> [--disposition <open|fixed|rejected|deferred>] [--rev <REV>] [--resolution-rev <REV>] [--introduced-rev <REV>] [--introduced-unknown] [--review <REVIEW_ID>] [--file-ref <TEXT>] [--scenario <SCENARIO_ID>]* [--role <ROLE>] [--session <SESSION_ID>] [--promote | --no-promote] [--input]
 ```
 ```bash
-canon finding add --change-id add-login --round 1 --seq 2 --severity should-fix --actor-id alice --summary "Token is logged"
+canon finding add --change add-login --round 1 --seq 2 --severity should-fix --introduced-unknown --actor alice --summary "Token is logged"
 ```
 ```text
 # Move an already-committed finding's disposition
-canon finding close <CHANGE_ID> --round <N> --seq <N> --disposition <open|fixed|rejected|deferred> [--resolution-rev <REV>] [--reason <TEXT>] [--actor-id <ACTOR_ID>] [--role <ROLE>] [--session-id <SESSION_ID>] [--promote | --no-promote] [--input]
+canon finding close <CHANGE_ID> --round <N> --seq <N> --disposition <open|fixed|rejected|deferred> [--resolution-rev <REV>] [--reason <TEXT>] [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--promote | --no-promote] [--input]
 ```
 ```bash
 canon finding close add-login --round 1 --seq 1 --disposition rejected --reason "works as designed"
 ```
 ```text
 # List a change's committed findings at their latest version
-canon finding list --change-id <CHANGE_ID> [--open] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
+canon finding list --change <CHANGE_ID> [--open] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
 ```
 ```bash
-canon finding list --change-id add-login
+canon finding list --change add-login
 ```
 ```text
 # Validate a spec/artifact corpus against canon's format
@@ -114,31 +114,31 @@ canon gate check
 ```
 ```text
 # Read stored records across every storage tier
-canon query --kind <change|task|scenario|session|run|event|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding> [--since <TIMESTAMP>] [--plugin-id <PLUGIN_ID> | --history] [--change-id <CHANGE_ID>] [--status <STATUS>] [--domain <NAME>] [--include-sensitive] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
+canon query --kind <change|task|scenario|session|run|event|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding> [--since <TIMESTAMP>] [--plugin <PLUGIN_ID> | --history] [--change <CHANGE_ID>] [--status <STATUS>] [--domain <NAME>] [--include-sensitive] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
 ```
 ```bash
 canon query --kind evidence
 ```
 ```text
 # Fetch role-scoped strategy guidance
-canon retrieve --for-role <ROLE> [--regime <KEY>] [--domain <NAME>] [--subject-id <SUBJECT_ID>] [--limit <N>]
+canon retrieve --for-role <ROLE> [--regime <KEY>] [--domain <NAME>] [--subject <SUBJECT_ID>] [--limit <N>]
 ```
 ```bash
 canon retrieve --for-role reviewer --domain dev --limit 20
 ```
 ```text
 # Write one attributed Review record for a chore change directly to the ledger (exactly one provenance ref required)
-canon review change <CHANGE_ID> --actor-id <ACTOR_ID> (--upstream-ref <TEXT> | --original-spec-ref <TEXT>) [--project-id <PROJECT_ID>] [--rev <REV>] [--role <ROLE>] [--session-id <SESSION_ID>] [--review-outcome <signed|indeterminate|unavailable>] [--reviewer-provider <NAME>] [--reviewer-model <NAME>] [--reviewer-harness <NAME>] [--artifact <PATH>]* [--max-artifact-mib <N>] [--input]
+canon review change <CHANGE_ID> --actor <ACTOR_ID> (--upstream-ref <TEXT> | --original-spec-ref <TEXT>) [--project <PROJECT_ID>] [--rev <REV>] [--role <ROLE>] [--session <SESSION_ID>] [--review-outcome <signed|indeterminate|unavailable>] [--reviewer-provider <NAME>] [--reviewer-model <NAME>] [--reviewer-harness <NAME>] [--artifact <PATH>]* [--max-artifact-mib <N>] [--input]
 ```
 ```bash
-canon review change add-login --actor-id alice --role reviewer --original-spec-ref docs/prd.md
+canon review change add-login --actor alice --role reviewer --original-spec-ref docs/prd.md
 ```
 ```text
 # Write one attributed Review record per scenario directly to the ledger, nothing to promote (exactly one provenance ref required)
-canon review scenario <SCENARIO_ID>+ --actor-id <ACTOR_ID> (--upstream-ref <TEXT> | --original-spec-ref <TEXT>) [--project-id <PROJECT_ID>] [--rev <REV>] [--role <ROLE>] [--session-id <SESSION_ID>] [--review-outcome <signed|indeterminate|unavailable>] [--reviewer-provider <NAME>] [--reviewer-model <NAME>] [--reviewer-harness <NAME>] [--artifact <PATH>]* [--max-artifact-mib <N>] [--input]
+canon review scenario <SCENARIO_ID>+ --actor <ACTOR_ID> (--upstream-ref <TEXT> | --original-spec-ref <TEXT>) [--project <PROJECT_ID>] [--rev <REV>] [--role <ROLE>] [--session <SESSION_ID>] [--review-outcome <signed|indeterminate|unavailable>] [--reviewer-provider <NAME>] [--reviewer-model <NAME>] [--reviewer-harness <NAME>] [--artifact <PATH>]* [--max-artifact-mib <N>] [--input]
 ```
 ```bash
-canon review scenario auth.login.01 --actor-id alice --role reviewer --original-spec-ref docs/prd.md
+canon review scenario auth.login.01 --actor alice --role reviewer --original-spec-ref docs/prd.md
 ```
 ```text
 # Describe canon's own commands
@@ -148,6 +148,13 @@ canon schema [<PATH>]* [--errors | --error <CODE>]
 canon schema evidence add
 ```
 ```text
+# Search records, brief sections and scenario text, with each hit's neighbors in the record graph
+canon search <TEXT> [--kind <change|task|scenario|session|run|event|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding|brief>]* [--expand <N>] [--limit <N>]
+```
+```bash
+canon search timeout --kind finding
+```
+```text
 # Print a guide built into this binary (markdown on stdout); the installed SKILL.md is a stub that points here
 canon skills show <NAME> [--full]
 ```
@@ -161,6 +168,13 @@ canon status [--fields <FIELDS>]
 ```bash
 canon status
 ```
+```text
+# Follow a finding's review loop in time order: review, finding, fix, re-review, evidence
+canon trace <ID>
+```
+```bash
+canon trace add-login_1_1
+```
 <!-- canon:generated commands-reviewer end -->
 
 `review scenario` needs exactly one of `--upstream-ref <ref>` or
@@ -174,20 +188,20 @@ found goes in `finding add --summary`.
 The forms you reach for most (the story's ids; swap in yours):
 
 ```bash
-canon review scenario auth.login.01 auth.login.02 --actor-id reviewer-1 --session-id session-7 --original-spec-ref docs/prd.md
-canon review scenario auth.login.01 --actor-id reviewer-1 --session-id session-7 --review-outcome indeterminate --original-spec-ref docs/prd.md
-canon review change add-login --actor-id reviewer-1 --session-id session-7 --original-spec-ref docs/prd.md
-canon finding add --change-id add-login --round 1 --seq 2 --severity blocker --actor-id reviewer-1 --session-id session-7 --summary "No rate limit" --scenario-id auth.login.01 --scenario-id auth.login.02 --introduced-rev HEAD~3
+canon review scenario auth.login.01 auth.login.02 --actor reviewer-1 --session session-7 --original-spec-ref docs/prd.md
+canon review scenario auth.login.01 --actor reviewer-1 --session session-7 --review-outcome indeterminate --original-spec-ref docs/prd.md
+canon review change add-login --actor reviewer-1 --session session-7 --original-spec-ref docs/prd.md
+canon finding add --change add-login --round 1 --seq 2 --severity blocker --actor reviewer-1 --session session-7 --summary "No rate limit" --scenario auth.login.01 --scenario auth.login.02 --introduced-rev HEAD~3
 canon finding close add-login --round 1 --seq 2 --disposition fixed --resolution-rev HEAD
 canon finding close add-login --round 1 --seq 3 --disposition rejected --reason "works as designed"
-canon finding list --change-id add-login --open
+canon finding list --change add-login --open
 ```
 
 Several findings at once are one `--input` array (the keys are option names
 in camelCase):
 
 ```text
-canon finding add --input '[{"changeId":"add-login","round":1,"seq":3,"severity":"note","actorId":"reviewer-1","summary":"Token is logged"},{"changeId":"add-login","round":1,"seq":4,"severity":"should-fix","actorId":"reviewer-1","summary":"Error text leaks the user name"}]'
+canon finding add --input '[{"change":"add-login","round":1,"seq":3,"severity":"note","actor":"reviewer-1","summary":"Token is logged"},{"change":"add-login","round":1,"seq":4,"severity":"should-fix","introducedUnknown":true,"actor":"reviewer-1","summary":"Error text leaks the user name"}]'
 ```
 
 A review pins what you saw: the scenario's digest plus the verdict
@@ -210,8 +224,8 @@ or `status` again.
 ## Separate session
 
 You run as a separate process with your own session id, never the session
-that wrote the code and evidence under another `--actor-id` or
-`--session-id` label. Pass your real session id as `--session-id` on
+that wrote the code and evidence under another `--actor` or
+`--session` label. Pass your real session id as `--session` on
 everything you record. A harness with no subagent tool starts you (a new
 `codex exec` run in this repo, say). Review happens on every change.
 
@@ -257,6 +271,10 @@ should make it fail and run it if it is cheap; if the test stays green, record
 the finding. For a fix, read `canon query --kind evidence --history --json`
 for that scenario's records: expect an earlier non-faithful version, or a
 named closest reproduction in `--ref`; record a finding when neither exists.
+`canon trace <finding key>` lists the loop around a finding in time order (the
+review that raised it, the fix, the re-review, the evidence at those commits);
+`canon search "<text>"` finds earlier findings and the scenarios about the same
+thing.
 Put one blast-radius fact in the finding or review `--summary`: what else the
 change touches that the checks do not exercise. Read the waivers too:
 `status` lists every `--override-reason` an implementer or the orchestrator
@@ -274,7 +292,7 @@ confirm the evidence really is divergent and the limit is outside this
 change, then report to the human the scenario ids, the reason, the
 tracking reference and an expiry when the limit should be gone by a date.
 Give the exact call, ids filled in: the human runs `canon divergence accept
-<ids> --actor-id <name> --reason "<why>" --tracking <ref>` themselves in their
+<ids> --actor <name> --reason "<why>" --tracking <ref>` themselves in their
 own shell, from a session that did not attest the evidence
 (`DIVERGENCE_ACCEPT_REFUSED` otherwise); you never run it or unset your role to. Never suggest it to skip
 a fix the implementer can make in this change. The acceptance pins that
@@ -302,9 +320,9 @@ covered for the ship guard and stays listed as `accepted-divergence` in
 - Sign off in one batch with `review scenario <ids>`, all or nothing. It writes
   directly; nothing to promote. canon stores and re-checks attached bytes
   and never compares images.
-- Pass `--scenario-id` for each scenario a finding is about. A blocker you
+- Pass `--scenario` for each scenario a finding is about. A blocker you
   close `fixed` then stays blocking until the implementer records evidence
-  again for those scenarios alone (`evidence add --scenario-id <id>`); the
+  again for those scenarios alone (`evidence add --scenario <id>`); the
   close inherits the list. A blocker naming no scenario asks for the whole
   suite again (`evidence add --all-scenarios`), which on a big suite is
   a long e2e run for a one-scenario fix, so name them. Your pinned review
@@ -313,7 +331,7 @@ covered for the ship guard and stays listed as `accepted-divergence` in
   evidence changes a verdict or the checks and so stales your review, look
   again before you sign it again.
   A chore has no scenarios: review it with one change-level review, `canon
-  review change <slug> --actor-id <me> --session-id <session>
+  review change <slug> --actor <me> --session <session>
   --upstream-ref <ref>` (or `--original-spec-ref <path>`). It signs the
   chore's invariants and checks against the diff and pins its brief, so
   editing the brief stales it. The chore also needs new evidence on every
@@ -322,7 +340,7 @@ covered for the ship guard and stays listed as `accepted-divergence` in
 
 **Done when:** `canon gate check` lists no `unreviewed-promotion` violation
 and no open blocker for the change (read `data.violations[]` in `canon gate
-check --json`; `canon finding list --change-id add-login --open` shows the
+check --json`; `canon finding list --change add-login --open` shows the
 open findings), or each remaining one is a finding you recorded and the
 implementer owns. Your last write's `meta.next` names the next step.
 

package/man/canon-adapter-authorize.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-adapter-authorize 1  "authorize 0.29.0" 
+.TH canon-adapter-authorize 1  "authorize 0.31.0" 
 .SH NAME
 canon\-adapter\-authorize \- Authorize declared capabilities against repository policy (preflight only)
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-adapter-validate.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-adapter-validate 1  "validate 0.29.0" 
+.TH canon-adapter-validate 1  "validate 0.31.0" 
 .SH NAME
 canon\-adapter\-validate \- Read and validate one provider\-neutral response envelope
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-adapter.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-adapter 1  "adapter 0.29.0" 
+.TH canon-adapter 1  "adapter 0.31.0" 
 .SH NAME
 canon\-adapter \- Validate a provider\-neutral adapter response without executing a provider
 .SH SYNOPSIS
@@ -43,4 +43,4 @@ Examples:
   canon adapter validate \-\-response response.json
   canon adapter validate \-\-response response.json \-\-repo . \-\-json
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-artifacts-move.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-artifacts-move 1  "move 0.29.0" 
+.TH canon-artifacts-move 1  "move 0.31.0" 
 .SH NAME
 canon\-artifacts\-move \- Move the local artifact blobs to an object\-store tier, verify them, and remove the local copies
 .SH SYNOPSIS
@@ -60,4 +60,4 @@ The bare run previews: it lists every upload and removal and prints a planDigest
 
 Idempotent and resumable: a run stopped anywhere leaves a repo the gate still passes, and the next run finishes; a second run finds nothing to do. A blob whose bytes do not match its name is never moved. Moving back to local is refused; `\-\-tier local` on a local repo is a no\-op.
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-artifacts-store.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-artifacts-store 1  "store 0.29.0" 
+.TH canon-artifacts-store 1  "store 0.31.0" 
 .SH NAME
 canon\-artifacts\-store \- Store the bound files of existing evidence records and current reviews in the artifact store (.canon/artifacts/sha256/)
 .SH SYNOPSIS
@@ -51,4 +51,4 @@ For records written before canon stored bound bytes (0.11\-0.13), and for any ev
 
 Exit 0 when the pass ran (the gate decides whether an unstored file matters), 2 when the ledger cannot be read or a write fails.
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-artifacts-verify.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-artifacts-verify 1  "verify 0.29.0" 
+.TH canon-artifacts-verify 1  "verify 0.31.0" 
 .SH NAME
 canon\-artifacts\-verify \- Check that the artifact store holds every file the latest evidence and current reviews bind (\-\-full re\-hashes the stored bytes)
 .SH SYNOPSIS
@@ -45,4 +45,4 @@ Asks the store canon.yaml\*(Aqs `artifacts:` block selects (default: local, .can
 
 Exit 0 when every file is stored, 1 when one is missing or altered (data.problems names each), 2 when the store cannot be used or reached: an unreachable store is a refusal, never a pass.
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-artifacts.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-artifacts 1  "artifacts 0.29.0" 
+.TH canon-artifacts 1  "artifacts 0.31.0" 
 .SH NAME
 canon\-artifacts \- Check or move the evidence artifact store (local, or an object\-store tier)
 .SH SYNOPSIS
@@ -42,4 +42,4 @@ Store the bound files of existing evidence records and current reviews in the ar
 canon\-artifacts\-move(1)
 Move the local artifact blobs to an object\-store tier, verify them, and remove the local copies
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-brief-approve.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-brief-approve 1  "approve 0.29.0" 
+.TH canon-brief-approve 1  "approve 0.31.0" 
 .SH NAME
 canon\-brief\-approve \- Record the human\*(Aqs approval of the brief, bound to its text; refused while `brief check` has blockers
 .SH SYNOPSIS
@@ -48,15 +48,18 @@ Print help
 Print version
 .TP
 [\fICHANGE_ID\fR]
-The change to read (default: the repo\*(Aqs only live change)
+The changes to approve, one answer for all, none written unless every one is approvable (default: the repo\*(Aqs only live change)
 .SH EXTRA
 Examples:
   canon brief approve add\-login \-\-approver Ana \-\-note \*(AqGo. Ship the failure flow too.\*(Aq
+  canon brief approve add\-login add\-search fix\-sync \-\-approver Ana \-\-note \*(AqAll three, go.\*(Aq
 
-Writes `Approved: <who> <when> — "<words>" (brief sha256:<digest>)` into the
+Several ids take one name, one answer and one timestamp. Every id is checked
+first; one refused id refuses the call (BRIEF_APPROVE_REFUSED) and nothing is
+written. Writes `Approved: <who> <when> — "<words>" (brief sha256:<digest>)` into the
 brief (the digest covers the brief without its `Approved:` lines) and records
 `canon policy approve` in the same call. Edit the brief afterwards and it reads as
 not approved (BRIEF_CHANGED_SINCE_APPROVAL) until a human answers again and this
 runs again. Run it only from the human\*(Aqs answer, with their words as \-\-note.
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-brief-check.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-brief-check 1  "check 0.29.0" 
+.TH canon-brief-check 1  "check 0.31.0" 
 .SH NAME
 canon\-brief\-check \- Read the brief against the rules: blocker and advisory findings (exit 0 clean, 1 blockers, 2 refused)
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print version
 [\fICHANGE_ID\fR]
 The change to read (default: the repo\*(Aqs only live change)
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-brief-show.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-brief-show 1  "show 0.29.0" 
+.TH canon-brief-show 1  "show 0.31.0" 
 .SH NAME
 canon\-brief\-show \- Show where the change stands and the next one to three steps; never edits
 .SH SYNOPSIS
@@ -47,4 +47,4 @@ Examples:
 
 The operand names the change; without it the repo\*(Aqs only live change is read.
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-brief.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-brief 1  "brief 0.29.0" 
+.TH canon-brief 1  "brief 0.31.0" 
 .SH NAME
 canon\-brief \- Check a change\*(Aqs brief (PRD format) and see the next steps; never edits
 .SH SYNOPSIS
@@ -48,16 +48,17 @@ Examples:
   canon brief check add\-login \-\-json
 
 The brief is the PRD `canon change new` writes: sections are found by their
-`<!\-\- canon:section <key> role=… \-\->` marker, never by heading text. Blockers
+English `##` heading (Intent, Desired outcome, …), never by a comment. Blockers
 (structure) are a missing or out\-of\-order section, a duplicate flow id, step
 detail that does not match the flow ids, leftover placeholders, and, once the
 subject is building, a flow step with no scenario or no failure scenario.
 Advisories (prose) apply to normative sections, Intent and Questions, in the
 language each is written in (`language:` in canon.yaml overrides); only en and
 ko have rule lists.
-Waive one rule in one section with
-  <!\-\- canon:waive <rule\-id> <section\-key> "<reason>" \-\->
-A brief without markers (written before 0.19) checks as `brief.legacy`, an
-advisory. Without \-\-change\-id, the repo\*(Aqs only live change is checked.
+Waive one rule in one section with an entry of the frontmatter `waive` list
+(`rule`, `section`, `reason`, optional `match`). A brief in the 0.30 format
+gets one blocker, `brief.old\-format`: `canon migrate` rewrites it. A brief
+with fewer than two known headings (written before 0.19) checks as `brief.legacy`, an
+advisory. Without \-\-change, the repo\*(Aqs only live change is checked.
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-change-new.1

@@ -1,10 +1,10 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-change-new 1  "new 0.29.0" 
+.TH canon-change-new 1  "new 0.31.0" 
 .SH NAME
 canon\-change\-new \- Write .canon/changes/<slug>/brief.md, import it, and adopt it into a subject
 .SH SYNOPSIS
-\fBcanon change new\fR [\fB\-\-as\fR] <\fB\-\-subject\-id\fR> [\fB\-\-change\-kind\fR] <\fB\-\-title\fR> [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fICHANGE_ID\fR> 
+\fBcanon change new\fR [\fB\-\-as\fR] <\fB\-\-subject\fR> [\fB\-\-change\-kind\fR] <\fB\-\-title\fR> [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fICHANGE_ID\fR> 
 .SH DESCRIPTION
 Write .canon/changes/<slug>/brief.md, import it, and adopt it into a subject
 .SH OPTIONS
@@ -26,7 +26,7 @@ reviewer
 orchestrator
 .RE
 .TP
-\fB\-\-subject\-id\fR \fI<SUBJECT_ID>\fR
+\fB\-\-subject\fR \fI<SUBJECT_ID>\fR
 The existing subject to adopt the change under
 .TP
 \fB\-\-change\-kind\fR \fI<CHANGE_KIND>\fR [default: feature]
@@ -63,4 +63,4 @@ Print version
 <\fICHANGE_ID\fR>
 The change\*(Aqs slug (its change_id)
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-change.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-change 1  "change 0.29.0" 
+.TH canon-change 1  "change 0.31.0" 
 .SH NAME
 canon\-change \- Write a plan change (.canon/changes/<slug>/brief.md) and adopt it into a subject
 .SH SYNOPSIS
@@ -37,6 +37,6 @@ canon\-change\-new(1)
 Write .canon/changes/<slug>/brief.md, import it, and adopt it into a subject
 .SH EXTRA
 Examples:
-  canon change new add\-login \-\-subject\-id auth \-\-title \*(AqAdd login\*(Aq
+  canon change new add\-login \-\-subject auth \-\-title \*(AqAdd login\*(Aq
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-completion.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-completion 1  "completion 0.29.0" 
+.TH canon-completion 1  "completion 0.31.0" 
 .SH NAME
 canon\-completion \- Write the shell completion script for canon (bash, zsh or fish)
 .SH SYNOPSIS
@@ -57,4 +57,4 @@ Examples:
 
 The script is generated from the command tree, so it completes exactly what the parser accepts. It needs no repo and no network.
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-context-pack-add.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-context-pack-add 1  "add 0.29.0" 
+.TH canon-context-pack-add 1  "add 0.31.0" 
 .SH NAME
 canon\-context\-pack\-add \- Create an immutable context pack from a repository\-local JSON manifest
 .SH SYNOPSIS
@@ -44,4 +44,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-context-pack-show.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-context-pack-show 1  "show 0.29.0" 
+.TH canon-context-pack-show 1  "show 0.31.0" 
 .SH NAME
 canon\-context\-pack\-show \- Show a context pack after verifying its manifest and content objects
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print version
 <\fIPACK_ID\fR>
 Context pack id (sha256:<64 hex digits>)
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-context-pack-verify.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-context-pack-verify 1  "verify 0.29.0" 
+.TH canon-context-pack-verify 1  "verify 0.31.0" 
 .SH NAME
 canon\-context\-pack\-verify \- Verify a context pack\*(Aqs manifest and immutable content objects
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print version
 <\fIPACK_ID\fR>
 Context pack id (sha256:<64 hex digits>)
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-context-pack.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-context-pack 1  "context-pack 0.29.0" 
+.TH canon-context-pack 1  "context-pack 0.31.0" 
 .SH NAME
 canon\-context\-pack \- Create, inspect, and verify reproducible context packs
 .SH SYNOPSIS
@@ -47,4 +47,4 @@ Examples:
   canon context\-pack show sha256:<pack\-digest> \-\-repo . \-\-json
   canon context\-pack verify sha256:<pack\-digest>
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-context.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-context 1  "context 0.29.0" 
+.TH canon-context 1  "context 0.31.0" 
 .SH NAME
 canon\-context \- Show what you can author here: record kinds, fields, enums, policies
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-dashboard.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-dashboard 1  "dashboard 0.29.0" 
+.TH canon-dashboard 1  "dashboard 0.31.0" 
 .SH NAME
 canon\-dashboard \- Serve the local status dashboard
 .SH SYNOPSIS
@@ -47,4 +47,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-demo-init.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-demo-init 1  "init 0.29.0" 
+.TH canon-demo-init 1  "init 0.31.0" 
 .SH NAME
 canon\-demo\-init \- Scaffold the demo repo (gate starts RED)
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-demo-review.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-demo-review 1  "review 0.29.0" 
+.TH canon-demo-review 1  "review 0.31.0" 
 .SH NAME
 canon\-demo\-review \- Record the missing reviewer evidence (gate turns GREEN)
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-demo.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-demo 1  "demo 0.29.0" 
+.TH canon-demo 1  "demo 0.31.0" 
 .SH NAME
 canon\-demo \- Try the evidence loop end\-to\-end in a throwaway demo repo
 .SH SYNOPSIS
@@ -44,4 +44,4 @@ Examples:
   canon gate check   # RED
   canon demo review && canon gate check   # GREEN
 .SH VERSION
-v0.29.0
+v0.31.0