@journeykit/canon 0.29.0 → 0.31.0

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

@@ -63,17 +63,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 +84,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 +154,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 +181,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 +208,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 +228,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 --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 +238,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 +261,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 +276,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 +290,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,7 +313,7 @@ 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
@@ -328,7 +342,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

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

@@ -114,7 +114,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 +142,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 +156,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 +191,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 +227,7 @@ canon ledger compact
 ```
 ```text
 # Bring a repo from an earlier canon up to date
-canon migrate [--commit --plan-digest <DIGEST>] [--input]
+canon migrate [--commit --plan-digest <DIGEST>] [--revert] [--backup <DIR> (with --revert)] [--input]
 # a bare run previews and prints planDigest; `--commit --plan-digest <DIGEST>` with that digest acts
 ```
 ```bash
@@ -271,7 +271,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 +306,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 +319,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 +383,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 +418,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 +431,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 +468,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 +477,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.
@@ -490,7 +504,7 @@ 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
@@ -499,8 +513,9 @@ 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
+with every slug filled in: `canon brief approve <slug> <slug> --approver <their name>
+--note "<their own words>"` (several slugs take one answer; nothing is written if
+one is refused). 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
@@ -635,14 +650,15 @@ canon skills install
    (which do not count until then; the gate, `status` and `subject move`
    print one advisory naming it) and replaces an old full skill with the
    stub. It backs up every file it rewrites under
-   `.canon/migrate-backup/<timestamp>/`, is safe to run again (a second run
+   `.canon/migrate-backup/<timestamp>/` (local, git-ignored; `--revert` restores from it), is safe to run again (a second run
    finds nothing to move) and refuses uncommitted changes under a path it
    moves: commit first. In CI run it with full history (`fetch-depth: 0`).
 3. `canon skills install` refreshes the stub and the scripts for the selected
    harnesses; `canon skills check` reports a skill written by another canon
    version (exit 1, `SKILLS_DRIFT`), `canon skills doctor` explains it.
 
-Commit what it changes.
+Commit what it changes, except the backup: `.canon/migrate-backup/` is local and
+git-ignored, and `canon migrate --revert` needs it (keep it until you are sure).
 
 **Done when:** `canon migrate` reports nothing left to move, `canon skills
 check` exits 0, and `canon status` and `canon gate check` no longer warn

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

@@ -37,10 +37,10 @@ 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 +65,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 +93,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 +120,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 +142,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 +194,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.