@journeykit/canon 0.30.0 → 0.32.0

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

@@ -4,15 +4,17 @@ You build inside an approved scope: scenarios, code, tests and evidence.
 Declare the role with `CANON_ROLE=implementer` (or `--as implementer`); `--role`
 on what you record then defaults to `implementer`.
 Build nothing before the brief is approved: `canon evidence add` refuses an
-unapproved brief's scenarios. If it is not approved, say so and wait; the
-planner and the human own that. The only waiver is `--override-reason
+unapproved brief's scenarios. If it is not approved, tell the orchestrator or planner, who show it to the human and ask;
+build nothing meanwhile. The only waiver is `--override-reason
 "<why>"`, for the case where you were told to attest while the brief waits for
 the human's answer: canon records it on the evidence, echoes it in
 `data.overrides[]` and lists it in `status` for the human. Never use it to
 skip the wait yourself. `brief approve`, `policy approve` and `divergence
-accept` are the human's; they refuse you (`HUMAN_ONLY`). 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`).
+accept` are the human's; they refuse you (`HUMAN_ONLY`) unless they record an
+answer the human gave in the conversation (`--relayed-via`, the planner's
+procedure: `canon skills show role-planner`). 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
 
@@ -63,17 +65,17 @@ canon context-pack verify sha256:00000000000000000000000000000000000000000000000
 ```
 ```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
@@ -84,45 +86,45 @@ 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 attributed EvidenceRecord for a task or scenario
-canon evidence add [--task-id <TASK_ID>] [--project-id <PROJECT_ID>] [--class <CLASS>] [--ref <TEXT>] [--verdict <faithful|not-applicable|divergent>] [--summary <TEXT>] [--command-result <TEXT>] [--scenario-id <SCENARIO_ID>] [--run-id <RUN_ID>] [--surface-ref <PATH_OR_EFFECT>]* [--actor-id <ACTOR_ID>] [--role <ROLE>] [--session-id <SESSION_ID>] [--approver <NAME>] [--approval-role <human>] [--signature-file <FILE>] [--approval-at <TIMESTAMP>] [--rev <REV>] [--artifact <PATH>]* [--report <FORMAT:PATH>]* [--report-case <NAME>]* [--all-scenarios] [--max-artifact-mib <N>] [--override-reason <TEXT>] [--promote | --no-promote] [--input]
+canon evidence add [--task <TASK_ID>] [--project <PROJECT_ID>] [--class <CLASS>] [--ref <TEXT>] [--verdict <faithful|not-applicable|divergent>] [--summary <TEXT>] [--command-result <TEXT>] [--scenario <SCENARIO_ID>] [--run <RUN_ID>] [--surface-ref <PATH_OR_EFFECT>]* [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--approver <NAME>] [--approval-role <human>] [--signature-file <FILE>] [--approval-at <TIMESTAMP>] [--rev <REV>] [--artifact <PATH>]* [--report <FORMAT:PATH>]* [--report-case <NAME>]* [--all-scenarios] [--max-artifact-mib <N>] [--override-reason <TEXT>] [--promote | --no-promote] [--input]
 ```
 ```bash
-canon evidence add --scenario-id auth.login.01 --class test-run --ref "npm test" --role implementer
+canon evidence add --scenario auth.login.01 --class test-run --ref "npm test" --role implementer
 ```
 ```text
 # Emit exact bytes for external `ssh-keygen -Y sign -n canon-approval-v1`
-canon evidence approval-payload --approver <NAME> --approval-at <TIMESTAMP> [--task-id <TASK_ID>] [--project-id <PROJECT_ID>] [--scenario-id <SCENARIO_ID>] [--run-id <RUN_ID>] [--rev <REV>] [--surface-ref <PATH_OR_EFFECT>]*
+canon evidence approval-payload --approver <NAME> --approval-at <TIMESTAMP> [--task <TASK_ID>] [--project <PROJECT_ID>] [--scenario <SCENARIO_ID>] [--run <RUN_ID>] [--rev <REV>] [--surface-ref <PATH_OR_EFFECT>]*
 ```
 ```bash
-canon evidence approval-payload --scenario-id auth.login.01 --project-id root --approver alice --approval-at 2030-01-01T00:00:00Z
+canon evidence approval-payload --scenario auth.login.01 --project root --approver alice --approval-at 2030-01-01T00:00:00Z
 ```
 ```text
 # Record an external evaluator's re-audit of one scenario (class `audit`; the verdict follows --audit-result; canon never runs the evaluator)
-canon evidence audit <SCENARIO_ID> --ref <TEXT> --evaluator-id <ID> --evaluator-version <TEXT> --evaluator-digest <DIGEST> --audit-result <confirmed|refuted|indeterminate> [--project-id <PROJECT_ID>] [--summary <TEXT>] [--command-result <TEXT>] [--run-id <RUN_ID>] [--actor-id <ACTOR_ID>] [--role <ROLE>] [--session-id <SESSION_ID>] [--rev <REV>] [--artifact <PATH>]* [--report <FORMAT:PATH>]* [--report-case <NAME>]* [--max-artifact-mib <N>] [--override-reason <TEXT>] [--promote | --no-promote] [--input]
+canon evidence audit <SCENARIO_ID> --ref <TEXT> --evaluator <ID> --evaluator-version <TEXT> --evaluator-digest <DIGEST> --audit-result <confirmed|refuted|indeterminate> [--project <PROJECT_ID>] [--summary <TEXT>] [--command-result <TEXT>] [--run <RUN_ID>] [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--rev <REV>] [--artifact <PATH>]* [--report <FORMAT:PATH>]* [--report-case <NAME>]* [--max-artifact-mib <N>] [--override-reason <TEXT>] [--promote | --no-promote] [--input]
 ```
 ```bash
-canon evidence audit auth.login.01 --ref audit-report.json --evaluator-id eval-1 --evaluator-version 2.1 --evaluator-digest 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef --audit-result confirmed --role implementer
+canon evidence audit auth.login.01 --ref audit-report.json --evaluator eval-1 --evaluator-version 2.1 --evaluator-digest 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef --audit-result confirmed --role implementer
 ```
 ```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
@@ -154,21 +156,21 @@ canon inventory sync
 ```
 ```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
@@ -181,6 +183,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]
 ```
@@ -201,6 +210,13 @@ canon task done <TASK_ID> [--input]
 ```bash
 canon task done add-login#1
 ```
+```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-implementer end -->
 
 After the first `status`, follow `meta.next` of each write; do not call
@@ -214,9 +230,9 @@ The forms you reach for most (the story's ids; swap in yours):
 
 ```bash
 canon evidence add --all-scenarios --report junit:a.xml --report junit:b.xml --role implementer
-canon evidence add --scenario-id auth.login.01 --report junit:red.xml
-canon evidence add --scenario-id auth.login.01 --verdict divergent --class test-run --ref "upstream limit, tracked in issue 118" --artifact limit.log
-canon finding add --change-id add-login --round 1 --seq 1 --severity should-fix --introduced-unknown --actor-id unit-1 --summary "Token is logged"
+canon evidence add --scenario auth.login.01 --report junit:red.xml
+canon evidence add --scenario auth.login.01 --verdict divergent --class test-run --ref "upstream limit, tracked in issue 118" --artifact limit.log
+canon finding add --change add-login --round 1 --seq 1 --severity should-fix --introduced-unknown --actor unit-1 --summary "Token is logged"
 ```
 
 Batches are one `--input` document (the keys are option names in camelCase,
@@ -224,7 +240,7 @@ Batches are one `--input` document (the keys are option names in camelCase,
 
 ```text
 canon scenario new --input '[{"operands":["auth.login.01"],"title":"Logs in","case":"happy","flow":"F1"},{"operands":["auth.login.02"],"title":"Rejects a wrong password","case":"failure","flow":"F1"}]'
-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 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"}]'
 ```
 
 ## Steps
@@ -247,7 +263,7 @@ canon evidence add --input '[{"scenarioId":"auth.login.01","class":"test-run","r
    under a `specs.roots[]` root (default `.canon/specs`); `canon skills show
    canon-authoring` has the scaffold. When you fill in a scenario, keep its
    `# canon: {...}` provenance lines: dropping one aborts `inventory sync`
-   on `missing-provenance`. `--project-id` is needed only when the repo
+   on `missing-provenance`. `--project` is needed only when the repo
    configures more than one spec root.
 2. **Units.** One unit is one flow step's complete path (sees, does,
    becomes) that can be verified on its own, sized to one session. Name the
@@ -262,7 +278,7 @@ canon evidence add --input '[{"scenarioId":"auth.login.01","class":"test-run","r
    with `finding add` the moment you find it, before review.
    **A fix fails first.** For a bug fix, write or extend the scenario's test
    and run it red on the unfixed code, then bind that failing run before you
-   change the code (`evidence add --scenario-id <id> --report <fmt>:<path>`).
+   change the code (`evidence add --scenario <id> --report <fmt>:<path>`).
    A bound report decides the verdict: a failed case records `divergent`, a
    skipped case and none failed records `not-applicable`, otherwise
    `faithful`; an explicit `--verdict faithful` over a failed or skipped case
@@ -276,8 +292,8 @@ canon evidence add --input '[{"scenarioId":"auth.login.01","class":"test-run","r
    One test run that proves several scenarios is bound once with
    `--all-scenarios`: one record per indexed scenario owning a case, each
    with the verdict its own cases show; any refusal writes none. It needs
-   `--project-id` only when the repo has several spec roots. For one scenario
-   use `--scenario-id <id>` with `--report` or `--artifact`; for many
+   `--project` only when the repo has several spec roots. For one scenario
+   use `--scenario <id>` with `--report` or `--artifact`; for many
    records with different values, one `evidence add --input` with an array
    (validated before any write; a write that fails stops the batch, the
    earlier elements stay written and a rerun reports them `unchanged`).
@@ -299,12 +315,12 @@ canon evidence add --input '[{"scenarioId":"auth.login.01","class":"test-run","r
    with `--artifact <scenario-id>=<path>`; a bare `--artifact` in a batch is
    refused. An external evaluator's audit is
    `canon evidence audit`; canon never generates one. Evidence for a task of an
-   imported plan (`--task-id <id>`) must bind the artifact or report that proves
+   imported plan (`--task <id>`) must bind the artifact or report that proves
    the task; a canon command is never that proof. When the behavior cannot
    match the scenario because of something outside this change, record the
    evidence `divergent` and say why in `--ref`; never record `faithful` to
    pass. The human accepts the tracked gap (`canon divergence accept`
-   refuses agent roles); fixing the behavior and recording again is the
+   refuses agent roles unless it records their explicit answer); fixing the behavior and recording again is the
    other way out.
 5. **Promote.** Under `write: { promote: auto }` (what `canon init` writes)
    the record is final when `evidence add` returns. Only with
@@ -328,7 +344,7 @@ canon evidence add --input '[{"scenarioId":"auth.login.01","class":"test-run","r
    is `docs/**` and `*.md`). A docs-only chore needs its change-level review
    alone. When code did change, the shipping refusal, `status` and
    `meta.next` lead with one command over every report, with the real paths
-   (`--project-id <id>` is added only with several spec roots):
+   (`--project <id>` is added only with several spec roots):
    `canon evidence add --all-scenarios --report junit:a.xml --report junit:b.xml --role implementer`.
    Run the suite and bind it with that one command, not one scenario at a
    time. Reviews stay current while the verdicts and checks are unchanged; a
@@ -347,10 +363,10 @@ not another evidence step.
 |---|---|
 | "The suite is slow; record `faithful` to pass." | `faithful` over a failed case is refused; a limit outside this change is recorded `divergent` with the reason in `--ref`. |
 | "I fixed it, the test would pass." | Run the test red first and bind it, then green. Evidence is a claim; the history is what the reviewer reads. |
-| "The brief is as good as approved." | `evidence add` refuses an unapproved brief's scenarios. Say so and wait. |
+| "The brief is as good as approved." | `evidence add` refuses an unapproved brief's scenarios. Tell the orchestrator or planner, who show it to the human and ask; build nothing meanwhile. |
 | "I will attest the other unit's work under my id." | Each unit records under its own actor id and session id. |
 | "I was told this twice already." | A correction repeated across runs belongs in a scenario, the policy or a gate; tell the orchestrator. |
-| "I will accept the divergence myself." | `divergence accept` refuses agent roles (`HUMAN_ONLY`); report the scenario, the reason and the tracking reference to the human. |
+| "I will accept the divergence myself." | The human accepts a gap: report the scenario, the reason and the tracking reference so they are asked, and never record an answer they did not give. |
 
 ## Retry safety
 

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

@@ -4,9 +4,10 @@ You run the loop across agents and move the subject. You write no brief,
 code or review yourself. Declare the role with `CANON_ROLE=orchestrator` (or
 `--as orchestrator`); your `canon status` also lists the human's steps. The
 human's acts (`brief approve`, `policy approve`, `divergence accept`) refuse
-every agent role, you included (`HUMAN_ONLY`). 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`).
+every agent role, you included (`HUMAN_ONLY`), unless you record the answer the
+human gave you in the conversation with `--relayed-via <tool>` (below). 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
 
@@ -114,7 +115,7 @@ canon demo review
 ```
 ```text
 # Mint a Run manifest with retrieved guidance and context/policy lineage
-canon dispatch begin --regime <KEY> [--role <ROLE>] [--actor-id <ACTOR_ID>] [--session-id <SESSION_ID>] [--provider <NAME>] [--model <NAME>] [--skill-id <ID>] [--skill-digest <DIGEST>] [--manifest <FILE>] [--prompt-bundle <NAME@VERSION>] [--task-id <TASK_ID>] [--parent-run-id <RUN_ID>] [--input]
+canon dispatch begin --regime <KEY> [--role <ROLE>] [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--provider <NAME>] [--model <NAME>] [--skill <ID>] [--skill-digest <DIGEST>] [--manifest <FILE>] [--prompt-bundle <NAME@VERSION>] [--task <TASK_ID>] [--parent-run <RUN_ID>] [--input]
 ```
 ```bash
 canon dispatch begin --regime implementer/my-repo/api/abcdef012345 --role implementer
@@ -142,10 +143,10 @@ canon divergence list --as-of 2030-01-01
 ```
 ```text
 # Emit exact bytes for external `ssh-keygen -Y sign -n canon-approval-v1`
-canon evidence approval-payload --approver <NAME> --approval-at <TIMESTAMP> [--task-id <TASK_ID>] [--project-id <PROJECT_ID>] [--scenario-id <SCENARIO_ID>] [--run-id <RUN_ID>] [--rev <REV>] [--surface-ref <PATH_OR_EFFECT>]*
+canon evidence approval-payload --approver <NAME> --approval-at <TIMESTAMP> [--task <TASK_ID>] [--project <PROJECT_ID>] [--scenario <SCENARIO_ID>] [--run <RUN_ID>] [--rev <REV>] [--surface-ref <PATH_OR_EFFECT>]*
 ```
 ```bash
-canon evidence approval-payload --scenario-id auth.login.01 --project-id root --approver alice --approval-at 2030-01-01T00:00:00Z
+canon evidence approval-payload --scenario auth.login.01 --project root --approver alice --approval-at 2030-01-01T00:00:00Z
 ```
 ```text
 # Export a redacted retention manifest without deleting records
@@ -156,10 +157,10 @@ canon export --kind evidence --output evidence.json
 ```
 ```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
@@ -191,7 +192,7 @@ canon ingest plans
 ```
 ```text
 # Import review/divergence/task/handoff records and derive verdicts
-canon ingest records [--watch] [--interval-secs <N>] [--dry-run] [--run-id <RUN_ID>] [--input]
+canon ingest records [--watch] [--interval-secs <N>] [--dry-run] [--run <RUN_ID>] [--input]
 ```
 ```bash
 canon ingest records
@@ -227,7 +228,7 @@ canon ledger compact
 ```
 ```text
 # Bring a repo from an earlier canon up to date
-canon migrate [--commit --plan-digest <DIGEST>] [--revert] [--backup <DIR> (with --revert)] [--input]
+canon migrate [--commit --plan-digest <DIGEST>] [--revert | --relayed-via <NAME>] [--backup <DIR> (with --revert)] [--actor <ACTOR_ID> (with --relayed-via)] [--approver <NAME> (with --relayed-via)] [--note <TEXT> (with --relayed-via)] [--input]
 # a bare run previews and prints planDigest; `--commit --plan-digest <DIGEST>` with that digest acts
 ```
 ```bash
@@ -271,7 +272,7 @@ canon purge --kind session --before 2020-01-01T00:00:00Z
 ```
 ```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
@@ -306,7 +307,7 @@ canon report snapshot snapshot-out
 ```
 ```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
@@ -319,6 +320,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
 # Run canon's built-in fixture self-tests
 canon selftest [--suite <trust-spine-gate|tiered-storage|typed-authoring-vocabulary|policy-expressions|format-authority|session-ingest|canon-context|artifact-ingest|spec-ledger-selftest|plugin-overlays|plan-import>]
 ```
@@ -376,28 +384,28 @@ canon strategy promote 01ARZ3NDEKTSV4RRFFQ69G5FAV
 ```
 ```text
 # Disable an active strategy with durable rollback provenance
-canon strategy rollback <STRATEGY_ID> --reason <TEXT> --actor-id <ACTOR_ID> --signature-file <FILE> --approval-at <TIMESTAMP> [--contradicting-trajectory-id <ID>] [--input]
+canon strategy rollback <STRATEGY_ID> --reason <TEXT> --actor <ACTOR_ID> --signature-file <FILE> --approval-at <TIMESTAMP> [--contradicting-trajectory <ID>] [--input]
 ```
 ```bash
-canon strategy rollback 01ARZ3NDEKTSV4RRFFQ69G5FAV --reason "regressed in production" --actor-id alice --signature-file approval.sig --approval-at 2030-01-01T00:00:00Z
+canon strategy rollback 01ARZ3NDEKTSV4RRFFQ69G5FAV --reason "regressed in production" --actor alice --signature-file approval.sig --approval-at 2030-01-01T00:00:00Z
 ```
 ```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
 # Move a subject to another lifecycle state (shipping is evidence-gated; with spec_coverage.require_review, entering its scope is review-gated; shipped → verifying reopens with --reason)
-canon subject move <SUBJECT_ID> --to <proposed|specced|building|verifying|shipped|retired> [--override-reason <TEXT>] [--reason <TEXT>] [--actor-id <ACTOR_ID>] [--session-id <SESSION_ID>] [--input]
+canon subject move <SUBJECT_ID> --to <proposed|specced|building|verifying|shipped|retired> [--override-reason <TEXT>] [--reason <TEXT>] [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--input]
 ```
 ```bash
 canon subject move demo --to specced
 ```
 ```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
@@ -411,10 +419,10 @@ canon subject show demo
 ```
 ```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-id add-login
+canon subject unadopt demo --change add-login
 ```
 ```text
 # Apply canon.yaml aging rules, moving old records to their destination tier
@@ -424,6 +432,13 @@ canon tier age [--commit --plan-digest <DIGEST>] [--input]
 ```bash
 canon tier age
 ```
+```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-orchestrator end -->
 
 ## Read the state
@@ -454,7 +469,7 @@ on every canon call (or run `export CANON_ROLE=<role>` first in its own
 shell).
 
 Order: planner, then (after the human's answer) implementer, then reviewer.
-Give each a unit: its own `--actor-id` and a session id.
+Give each a unit: its own `--actor` and a session id.
 
 ### Spawn contract
 
@@ -463,7 +478,7 @@ one flow step or review it serves); the scope it owns (the scenarios or
 paths it may write); what it must not touch (the brief, the policy, other
 units' scenarios, anything outside its scope); the command that proves it is
 done (the unit's verify command, or `canon gate check` for the reviewer); and
-its own `--actor-id` and `--session-id`. Two agents never write the same
+its own `--actor` and `--session`. Two agents never write the same
 paths: give parallel implementers disjoint scopes, and where the harness can
 isolate a child in its own worktree, use it. The child reports what it
 verified apart from what it only claims.
@@ -477,40 +492,55 @@ text.
 | Harness | In-harness subagents | Isolation | Ask the human | Hooks | Skipped |
 |---|---|---|---|---|---|
 | claude (`.claude`) | yes, a subagent tool; a child shares your environment, so pass the role in the task | a subagent can run in its own git worktree | yes, a question tool | yes, in the harness settings; `scripts/canon-retrieve-pre-dispatch.sh` is a sidecar, not installed | none |
-| codex (`.agents`) | `verify`: none when #39 was filed; start the reviewer as a new `codex exec` run | none from canon: use a separate worktree you create | no in `codex exec`; stop and report | `verify` | in-harness spawn, unless a newer version provides it |
+| codex (`.agents`) | `verify`: none when #39 was filed; start the reviewer as a new `codex exec` run | none from canon: use a separate worktree you create | no in `codex exec`; ask in the chat | `verify` | in-harness spawn, unless a newer version provides it |
 | omp (`.omp`) | yes, the task tool | `verify` | yes, an ask tool | yes | none |
 | pi (`.pi`) | `verify`: assume none; start a new `pi` process | none from canon | `verify` | `verify` | in-harness spawn, isolation |
 
 Where a harness has no subagent tool, the reviewer is still a separate
 process with its own session id: start it from the shell with its own
-`CANON_ROLE=reviewer`. A harness that cannot ask the human means you stop
-and report in your final message; you never assume the answer.
+`CANON_ROLE=reviewer`. A harness that cannot ask the human means you ask
+in the chat and record only the reply; you never assume the answer.
 
 The reviewer is a separate process with its own session id, never your
 session or the implementer's under another label. Start it as a new process
 (a new `codex exec` run, or the harness's subagent), pass nothing of the
 implementer's context, and have it record its real session id as
-`--session-id` (#39). A reviewer that cannot run the tests says so and does
+`--session` (#39). A reviewer that cannot run the tests says so and does
 not sign off.
 
-## Relay the human stop
+## Relay the human's answer
 
 When `status` or `meta.next` shows a step with `actor: human` (the brief's
-approval), stop everything for that scope, report the brief to the human in
-its language, and wait. Tell the human they can approve the clean briefs in
-`canon dashboard` (the briefs page) or run, in their own shell, the exact call
-with the slug filled in: `canon brief approve <slug> --approver <their name>
---note "<their own words>"`. You never click Approve, fill the form or run
-`brief approve` yourself: it refuses you (`HUMAN_ONLY`), and removing or
-unsetting your declared role (`env -u CANON_ROLE`, dropping `--as`) to get past
-that is the same act under another label. Report the call and wait. Do not start the
+approval), stop everything for that scope and put the brief in front of the
+human in its language: `canon brief show <slug> --body` prints the brief and,
+last, its digest. Send the output to the human's own view, never retyped (omp:
+redirect it to `out://`, off for subagents and non-TUI sessions and capped at
+64 KiB; there, and where there is no such channel, leave the tool output
+visible). You are the session that talks to the human: a subagent has no
+question tool, so you show, ask and record for it. Ask with the harness question tool (`ask` in omp, `AskUserQuestion`
+in Claude Code, otherwise in the chat), approve or request changes, all the
+clean briefs in one question. Only an explicit approval counts; a question or a
+condition is a revision request for the planner, and no answer means you wait.
+They may also approve in `canon dashboard` (the briefs page); you never click
+Approve or fill the form. On their approval record it: `canon brief approve
+<slug> <slug> --approver <their name> --note "<their own words>" --relayed-via
+<ask|AskUserQuestion|chat> --actor <your actor id> --digest <slug>=<the digest
+shown>` (several slugs take one answer, each with its own `--digest`; nothing is written
+if one is refused). The record says you recorded it, with your role, actor and
+tool. `RELAY_DIGEST_MISMATCH` means the brief changed after they saw it: show it
+again. When `canon.yaml` has `approval: { relay: deny }` the call is refused
+(`HUMAN_ONLY`, naming the key): report the human's own call and wait for them to
+run it. Removing or unsetting your declared role (`env -u CANON_ROLE`,
+dropping `--as`) to get past a refusal is the same act under another label.
+`canon skills show role-planner` has the full procedure. Do not start the
 implementer before `canon brief show <slug>` reports `state: approved`.
 Never approve it yourself and never edit the policy to pass the gate. A
 policy that no longer matches the approval fails closed
 (`POLICY_CHANGED_SINCE_APPROVAL`, or `POLICY_APPROVAL_UNREADABLE`): the ship
 guard and the reopen refuse, and `--override-reason` does not waive it. Run
-`canon policy show`, then stop and ask the human to re-approve
-(the call `canon policy approve --approver <their name>` is theirs to run, never yours) or restore the
+`canon policy show`, then show the policy to the human, ask them to re-approve
+and record their explicit answer (`canon policy approve --approver <their name>
+--note "<their words>" --relayed-via <tool> --actor <your actor id>`), or restore the
 approved policy from git; never edit the policy yourself. Inside an
 approved scope never stop for a human: fixes, follow-ups and re-reviews go
 straight to the implementer and reviewer in the same change. A known gap the
@@ -548,7 +578,7 @@ its preview, never from an old digest.
 |---|---|
 | "Edit the policy so the gate passes." | A changed policy fails closed (`POLICY_CHANGED_SINCE_APPROVAL`); ask the human to re-approve or restore it from git. |
 | "The reviewer can be me under another label." | The reviewer is a separate process with its own real session id (#39). |
-| "Approve the brief; the human said they are busy." | `brief approve` refuses agent roles. Report the brief and wait. |
+| "Approve the brief; the human said they are busy." | An answer they did not give is not recorded. Show the brief, ask, and record only an explicit approval with `--relayed-via`. |
 | "Override the refusal to ship." | Fix the gap the refusal names; `--override-reason` waives only the `require_review` gaps and the brief gap, is recorded on the subject, and is for the human's call, not a shortcut. |
 | "Run the commit now, the preview looked fine earlier." | A bare run previews; `--commit --plan-digest` acts only on the plan you just previewed (`PLAN_CHANGED` otherwise). Preview again, then act. |
 | "I have corrected this agent before." | A correction repeated across runs belongs in a scenario, the policy or a gate, not more prose. Tell the human. |