@journeykit/canon 0.30.0 → 0.32.0

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

@@ -4,10 +4,12 @@ You turn a request into an approved scope: a subject, a change and a PRD
 brief the human answers once. You build nothing. Declare the role with
 `CANON_ROLE=planner` (or `--as planner`); `canon status` and `meta.next`
 then show your steps and count the rest under `waitingOn`. The approvals are
-the human's: `brief approve`, `policy approve` and `divergence accept` refuse
-every agent role (`HUMAN_ONLY`, `retryable: false`), and no flag grants them. You never run them, and never remove or unset your role (`env -u CANON_ROLE`,
-dropping `--as`) to get past the refusal: report the exact call, slug filled in, and
-wait; the human runs it (or uses `canon dashboard`).
+the human's: `brief approve`, `policy approve`, `divergence accept` and the
+`migrate --commit` that re-binds `Approved:` lines refuse every agent role
+(`HUMAN_ONLY`, `retryable: false`) unless you record the answer the human gave
+you in the conversation, with `--relayed-via <tool>` (step 4). Without a human's
+explicit answer you never run them, and you never remove or unset your role
+(`env -u CANON_ROLE`, dropping `--as`) to get past the refusal.
 
 ## Commands
 
@@ -30,17 +32,17 @@ canon brief check
 ```
 ```text
 # Show where the change stands and the next one to three steps; never edits
-canon brief show [<CHANGE_ID>]
+canon brief show [<CHANGE_ID>] [--body]
 ```
 ```bash
 canon brief show
 ```
 ```text
 # Write .canon/changes/<slug>/brief.md, import it, and adopt it into a subject
-canon change new <CHANGE_ID> --subject-id <SUBJECT_ID> --title <TEXT> [--change-kind <feature|chore>] [--input]
+canon change new <CHANGE_ID> --subject <SUBJECT_ID> --title <TEXT> [--change-kind <feature|chore>] [--input]
 ```
 ```bash
-canon change new add-search --subject-id demo --title "Add search"
+canon change new add-search --subject demo --title "Add search"
 ```
 ```text
 # Write the shell completion script for canon (bash, zsh or fish)
@@ -65,17 +67,17 @@ canon divergence list --as-of 2030-01-01
 ```
 ```text
 # Create a fresh .feature file for a new area.surface
-canon feature new <SURFACE> --title <TEXT> [--actor-id <ACTOR_ID>] [--session-id <SESSION_ID>] [--project-id <PROJECT_ID>] [--input]
+canon feature new <SURFACE> --title <TEXT> [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--project <PROJECT_ID>] [--input]
 ```
 ```bash
 canon feature new billing.invoice --title Invoices
 ```
 ```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
@@ -93,21 +95,21 @@ 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
 # Append a tagged scenario stub to its .feature file (created if missing); many at once with `--input`
-canon scenario new <SCENARIO_ID> --title <TEXT> [--subject-id <SUBJECT_ID>] [--lane <NAME>] [--case <NAME>] [--flow <FLOW_ID>] [--change-id <CHANGE_ID> (with --flow)] [--actor-id <ACTOR_ID>] [--session-id <SESSION_ID>] [--feature <FILE>] [--project-id <PROJECT_ID>] [--input]
+canon scenario new <SCENARIO_ID> --title <TEXT> [--subject <SUBJECT_ID>] [--lane <NAME>] [--case <NAME>] [--flow <FLOW_ID>] [--change <CHANGE_ID> (with --flow)] [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--feature <FILE>] [--project <PROJECT_ID>] [--input]
 ```
 ```bash
 canon scenario new auth.login.02 --title "Sign out" --feature .canon/specs/kind=feature/area=auth/login.feature
@@ -120,6 +122,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]
 ```
@@ -135,24 +144,31 @@ canon status
 ```
 ```text
 # Link an imported plan change to a subject (adopting it under another subject adds that subject; a change may belong to several)
-canon subject adopt <SUBJECT_ID> --change-id <CHANGE_ID> [--dry-run] [--input]
+canon subject adopt <SUBJECT_ID> --change <CHANGE_ID> [--dry-run] [--input]
 ```
 ```bash
-canon subject adopt demo --change-id add-login
+canon subject adopt demo --change add-login
 ```
 ```text
 # Author a new subject at status `proposed`
-canon subject new <SUBJECT_ID> --domain <NAME> --title <TEXT> [--summary <TEXT>] [--owner-role <ROLE>] [--actor-id <ACTOR_ID>] [--session-id <SESSION_ID>] [--input]
+canon subject new <SUBJECT_ID> --domain <NAME> --title <TEXT> [--summary <TEXT>] [--owner-role <ROLE>] [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--input]
 ```
 ```bash
 canon subject new payments --domain dev --title Payments
 ```
 ```text
 # Take a change back out of a subject (the mirror of adopt; refused for a change whose brief is approved)
-canon subject unadopt <SUBJECT_ID> --change-id <CHANGE_ID> [--dry-run] [--input]
+canon subject unadopt <SUBJECT_ID> --change <CHANGE_ID> [--dry-run] [--input]
+```
+```bash
+canon subject unadopt demo --change add-login
+```
+```text
+# Follow a finding's review loop in time order: review, finding, fix, re-review, evidence
+canon trace <ID>
 ```
 ```bash
-canon subject unadopt demo --change-id add-login
+canon trace add-login_1_1
 ```
 <!-- canon:generated commands-planner end -->
 
@@ -180,10 +196,11 @@ ids); the human step comes after it. A policy that no longer matches its approva
    `building`, `verifying` or `shipped` subject warns (stderr and JSON
    `meta.warnings`) until its brief is approved: evidence for its existing scenarios is not
    frozen and the subject can still be reopened and shipped for its approved
-   scope while no scenario is tagged for the draft (a pending draft); once one
-   is, the subject cannot ship before the approval.
-   A scenario answers to the changes its `@flow:<change>.<F-id>`
-   tags name (`canon scenario new --flow <F-id>` tags one for this change).
+   scope while no scenario is tagged for the draft and it was never approved
+   (a pending draft); once one is, the subject cannot ship before the approval.
+   A tagged scenario answers to the changes its `@flow:<change>.<F-id>`
+   tags name (`canon scenario new --flow <F-id>` tags one for this change);
+   an untagged one answers to every change with an `Approved:` line.
    To park a draft that should not gate a live subject, `subject unadopt`
    it and adopt it into a `proposed` subject. Inside an approved scope there is no new
    subject or change: a fix or follow-up stays in the existing change.
@@ -228,26 +245,63 @@ ids); the human step comes after it. A policy that no longer matches its approva
    the advisories are gone or each remaining one is waived with a reason.
    It never blocks approval, but you do not hand the human a brief with
    unexamined advisories.
-4. **Stop for the human.** Report the brief to the human, in the brief's
-   language, asking once, and say they can approve it in `canon dashboard`
-   (the briefs page, `/briefs.html`) or answer in chat. You never click
-   Approve or fill that form yourself. Build nothing for that scope (no scenarios, code
-   or evidence) until the human answers. The approval is never assumed, even
-   when the human said they cannot answer until you report: the brief is
-   that report. The one answer approves the brief and the policy
+4. **Show, ask, count only an explicit approval.** Build nothing for that
+   scope (no scenarios, code or evidence) until the human has answered. The
+   approval is never assumed, even when the human said they cannot answer
+   until you show the brief. The one answer approves the brief and the policy
    (`.canon/policy.yaml`, written by `canon init`), which is what the gate
    grades the work against.
-5. **The human records the answer.** `brief approve` is the human's leaf: run
-   by an agent role it is refused (`HUMAN_ONLY`) with a hint addressed to the
-   human. Report the exact call, slug filled in, and wait: `canon brief approve
-   add-login --approver <their name> --note "<their own words>"`; the human
-   runs it in their own shell (`--approver` and `--note` are theirs to supply)
-   or approves in the dashboard. Never approve in their name, never remove or
-   unset your role (`env -u CANON_ROLE`, dropping `--as`) to run it, and never
-   edit the policy to make the gate pass.
+   - **Show.** `canon brief show <slug> --body` prints the brief file's bytes
+     as they are and, as its last line, `digest: sha256:<hex>`, the value
+     `brief approve` records. Send that output to the human's own view; never
+     retype or paraphrase the brief into the conversation. In omp, redirect it
+     to `out://` (`canon brief show add-login --body > out://add-login`).
+     `out://` is off for subagents and non-TUI sessions (the redirect then
+     errors) and caps a reply at 64 KiB: there, and in a harness with no such
+     channel, leave the tool output visible, which is the same. Read the digest alone with `canon brief show add-login --body |
+     tail -n 1`. Show every brief of one request, each with its digest.
+   - **Ask.** Use the harness's question tool: `ask` in omp, `AskUserQuestion`
+     in Claude Code; a harness without one, ask in the chat and wait for the
+     reply. Two choices: approve, or request changes. Several briefs are one
+     question. Say in the brief's language what is approved: the brief and
+     the policy.
+   - **Count only an explicit approval.** The approve choice, or the human
+     saying in the chat that they approve. A question, a condition ("yes, if
+     …") or an approval of part of it is a revision request: change the brief,
+     `brief check` until clean, show it again and ask again. No answer means
+     nothing is recorded: wait.
+   A subagent has no question tool and no human in front of it: the
+   orchestrator (the session talking to the human) shows, asks and records.
+   They may also approve on `canon dashboard` (the briefs page,
+   `/briefs.html`); you never click Approve or fill that form yourself.
+5. **Record the answer you were given.** Run `brief approve` with the relay
+   option: `canon brief approve add-login --approver <their name> --note "<their
+   answer, as they gave it>" --relayed-via <ask|AskUserQuestion|chat> --actor
+   <your actor id> --digest add-login=<the digest you showed>` (several slugs:
+   one `--digest <slug>=<digest>` each, one answer for all, nothing written if
+   any is refused). `--actor` may be `CANON_ACTOR` instead. The record keeps
+   their name and words and says that you, with your role and actor, recorded
+   them through that tool: the `Approved:` line gains `(relayed by <role>
+   <actor> via <tool>)`, which is outside the digest, and `status`, `brief
+   show` and the dashboard name it. Never approve in their name without their
+   answer, never write the answer for them, and never edit the policy to make
+   the gate pass. A digest that differs from the brief now
+   (`RELAY_DIGEST_MISMATCH`) means the brief changed after they saw it: show
+   it again and ask again; nothing was written. Without `--relayed-via` the call is
+   `HUMAN_ONLY`; with it and no role declared, `USAGE`. When `canon.yaml`
+   turns relaying off (`approval: { relay: deny }`), the refusal names that key:
+   report the human's call (`canon brief approve add-login --approver <their
+   name> --note "<their own words>"`) and wait for them to run it. Never
+   remove or unset your role (`env -u CANON_ROLE`, dropping `--as`) to run it.
+   `canon policy approve`, `canon divergence accept` and `canon migrate
+   --commit --plan-digest <d>` follow the same procedure, each taking
+   `--approver <their name> --note "<their answer>" --relayed-via <tool>` (and
+   `--actor <your actor id>`, which `divergence accept` already requires): show what is approved (the policy file, the divergent
+   evidence with its reason and tracking reference, the migrate plan), ask,
+   count only an explicit approval, then record with the relay option.
    `canon brief show <slug>` then reports `state: approved`. A brief edited
    after its approval is not approved (`BRIEF_CHANGED_SINCE_APPROVAL`): it
-   needs a new answer and a new `brief approve` by the human. A follow-up that
+   needs a new answer, shown and asked again, and a new `brief approve`. A follow-up that
    adds or changes a step of the brief is a scope change and needs a new
    answer.
 
@@ -258,17 +312,17 @@ approval.
 
 **Done when:** `canon brief check add-login` exits 0 (no blockers, and the
 prose advisories are gone or waived with a reason) and `canon brief show
-add-login` reports `state: ready`: the brief is handed to the human and you
-stop. The scope is approved when the same command reports `state:
-approved`; read it in `data.state` of `canon brief show add-login --json`.
-Nothing else starts before that.
+add-login` reports `state: ready`: show it to the human and ask (step 4). The scope is approved
+when you have recorded their explicit approval (step 5) and the same command
+reports `state: approved`; read it in `data.state` of `canon brief show
+add-login --json`. Nothing else starts before that.
 
 ## Non-behavior work is a chore
 
 A refactor, dependency, build, CI or infra change that alters nothing a user
 can observe: `change new --change-kind chore`. Its brief is short (intent,
 category, invariants, checks, out of scope) and approved like any brief, one
-human stop. A chore adds no scenarios: the
+human answer. A chore adds no scenarios: the
 implementer runs the subject's suite again where the code changed and binds
 it with `canon evidence add --all-scenarios` (a docs-only chore changes no
 code and needs no new evidence), then the reviewer records one
@@ -295,9 +349,9 @@ old column, delete the old format) in its own later change.
 
 | The thought | The reality |
 |---|---|
-| "The human is unavailable; I will assume the approval." | Never. The brief is the report; stop, and put open questions into Questions and assumptions. |
+| "The human is unavailable; I will assume the approval." | Never. Show the brief and ask; without an explicit answer nothing is recorded and nothing is built. Put open questions into Questions and assumptions. |
 | "This could change policy, but I will decide it." | Anything that could change policy goes to the questions. |
-| "A small follow-up needs no new answer." | A follow-up that adds or changes a flow step is a scope change and needs a new `brief approve`. |
+| "A small follow-up needs no new answer." | A follow-up that adds or changes a flow step is a scope change and needs a new answer and a new `brief approve`. |
 | "This migration is just a chore." | Data, interface or output changes are feature changes. |
 | "Put the file and line in the brief so nobody has to look." | Paths rot; describe behavior. |
 

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

@@ -4,10 +4,11 @@ You are the independent second look. Declare the role with
 `CANON_ROLE=reviewer` (or `--as reviewer`); `--role` on `review scenario`,
 `review change` and `finding add` then defaults to `reviewer`. The human's
 acts refuse you (`HUMAN_ONLY`): `brief approve`, `policy approve` and
-`divergence accept`. Name what the human has to decide in your report; never
-look for a flag that grants it. You never run them, and never remove or unset your role (`env -u CANON_ROLE`,
-dropping `--as`) to get past the refusal: report the exact call, slug filled in, and
-wait; the human runs it (or uses `canon dashboard`).
+`divergence accept`, unless you record the answer the human gave you in the
+conversation with `--relayed-via <tool>` (the divergence acceptance below).
+Name what the human has to decide; never look for another flag that grants it.
+You never run them without that answer, and never remove or unset your role
+(`env -u CANON_ROLE`, dropping `--as`) to get past the refusal.
 
 ## Commands
 
@@ -30,7 +31,7 @@ canon brief check
 ```
 ```text
 # Show where the change stands and the next one to three steps; never edits
-canon brief show [<CHANGE_ID>]
+canon brief show [<CHANGE_ID>] [--body]
 ```
 ```bash
 canon brief show
@@ -51,17 +52,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 +73,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>] [--introduced-unknown] [--review-id <REVIEW_ID>] [--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 --introduced-unknown --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 +115,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 +149,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 +169,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 +189,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","introducedUnknown":true,"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 +225,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 +272,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
@@ -269,14 +288,21 @@ sign.
 `divergence accept` is for a scenario whose honest evidence is `divergent`
 and whose gap is limited by something outside this change (an upstream
 limit, a platform bug) and is tracked there. It records a human's decision,
-so it refuses every agent role (`HUMAN_ONLY`), you included. What you do:
-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
-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
+so it refuses every agent role (`HUMAN_ONLY`), you included, unless it records
+the answer the human gave you. What you do: confirm the evidence really is
+divergent and the limit is outside this change, then put to the human the
+scenario ids, the reason, the tracking reference and an expiry when the limit
+should be gone by a date, in their own view and not retyped (omp: `out://`).
+Ask with the harness question tool (`ask` in omp, `AskUserQuestion` in Claude
+Code, otherwise in the chat): accept the gap, or not. Only an explicit
+approval counts; a question or a condition is not one, and no answer records
+nothing. Then record it from a session that did not attest the evidence
+(`DIVERGENCE_ACCEPT_REFUSED` otherwise): `canon divergence accept <ids> --actor
+<your actor id> --reason "<why>" --tracking <ref> --approver <their name> --note
+"<their answer>" --relayed-via <tool>`; the record carries the relay, the
+approver and their answer. When `canon.yaml` has `approval: { relay: deny }` the
+call is refused (`HUMAN_ONLY`, naming the key) and the human runs it themselves.
+You never unset your role to run it. Never suggest it to skip
 a fix the implementer can make in this change. The acceptance pins that
 evidence: new evidence for the scenario, or its expiry, ends it, and the
 human accepts (or the implementer fixes) again. An accepted gap counts as
@@ -302,9 +328,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 +339,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 +348,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.
 
@@ -344,6 +370,6 @@ disposition is a no-op too.
 | "I cannot run the tests, but the evidence looks right." | Say so and record `indeterminate` or `unavailable`; never sign what you could not run. |
 | "This is a minor defect; I will skip the finding." | Every defect is a finding; severity says how much it matters. |
 | "I will edit the brief to fix it." | A brief defect is a finding, not an edit. |
-| "I will accept the gap myself, the limit is real." | `divergence accept` refuses agent roles; report the gap to the human. |
+| "I will accept the gap myself, the limit is real." | The human accepts it: ask them, and record only their explicit answer with `--relayed-via`. |
 
 Reference: `canon skills show canon-review`.

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.30.0" 
+.TH canon-adapter-authorize 1  "authorize 0.32.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.30.0
+v0.32.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.30.0" 
+.TH canon-adapter-validate 1  "validate 0.32.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.30.0
+v0.32.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.30.0" 
+.TH canon-adapter 1  "adapter 0.32.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.30.0
+v0.32.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.30.0" 
+.TH canon-artifacts-move 1  "move 0.32.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.30.0
+v0.32.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.30.0" 
+.TH canon-artifacts-store 1  "store 0.32.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.30.0
+v0.32.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.30.0" 
+.TH canon-artifacts-verify 1  "verify 0.32.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.30.0
+v0.32.0