@journeykit/canon 0.31.0 → 0.32.0

package/dist/skills/SKILL.src.md

@@ -26,18 +26,34 @@ a feature, a one-line request included. A human is needed once per scope:
 
 - **The approval** (step 1). For a new subject or a scope change, the
   human must approve the brief. Write the brief,
-  run `canon brief check` until it reports no blockers, then stop and
-  report the brief to the human: build nothing for that scope (no
+  run `canon brief check` until it reports no blockers, then show it, ask and
+  record the answer: build nothing for that scope (no
   scenarios, code or evidence) before the human answers. The approval is
   the one thing you never assume, even when the human said they cannot
-  answer until you report: the brief is that report. The one answer
+  answer until you show it. The one answer
   approves the brief and the policy, `.canon/policy.yaml`, which is what
   the gate grades the work against. The human may also approve it on the `canon dashboard` briefs page; you never use that form.
-  The human records the answer, never you:
-  `canon brief approve <slug> <slug> --approver <their name> --note "<their words>"`
-  (one or more slugs, one answer for all, nothing written if any is refused)
-  refuses every agent role (`HUMAN_ONLY`). Report that exact call, every slug filled in, and
-  wait; never remove or unset your role (`env -u CANON_ROLE`, dropping `--as`) to run it yourself.
+  1. **Show** with `canon brief show <slug> --body`: the brief file's bytes and,
+     last, `digest: sha256:<hex>`. Send it to the human's own view without
+     retyping it (omp: redirect it to `out://`, which is off for subagents and
+     non-TUI sessions and caps at 64 KiB; there, and in a harness with no such
+     channel, leave the tool output visible). A subagent has no question tool:
+     the orchestrator shows, asks and records.
+  2. **Ask** with the harness question tool (`ask` in omp, `AskUserQuestion` in
+     Claude Code, otherwise in the chat): approve or request changes, several
+     briefs in one question.
+  3. **Count only an explicit approval.** A question or a condition is a
+     revision request (change the brief, check, show and ask again); no answer
+     records nothing.
+  4. **Record it** with the relay option:
+     `canon brief approve <slug> <slug> --approver <their name> --note "<their words>" --relayed-via <ask|AskUserQuestion|chat> --actor <your actor id> --digest <slug>=<digest shown>`
+     (one or more slugs, each with its own `--digest`, one answer for all, nothing written if any is refused).
+     The `Approved:` line then carries `(relayed by <role> <actor> via <tool>)`.
+     A digest that no longer matches the brief is `RELAY_DIGEST_MISMATCH`: show
+     it again. Without `--relayed-via` an agent role gets `HUMAN_ONLY`, and so
+     does a repo whose `canon.yaml` says `approval: { relay: deny }`: then the
+     human runs the call themselves. Never remove or unset your role
+     (`env -u CANON_ROLE`, dropping `--as`) to run it yourself.
   Never edit the policy to make the gate pass: a policy that differs from
   the approved one fails closed (`POLICY_CHANGED_SINCE_APPROVAL`, not
   waivable); stop and ask the human. A brief edited after its
@@ -74,7 +90,7 @@ a feature, a one-line request included. A human is needed once per scope:
   so in your report. That covers the brief's questions and work inside an
   approved scope, never the approval itself.
 
-1. **Brief.** The planner writes the PRD brief (`.canon/changes/<slug>/brief.md`), checks it with `canon brief check`, and stops for the human. `canon skills show role-planner`
+1. **Brief.** The planner writes the PRD brief (`.canon/changes/<slug>/brief.md`), checks it with `canon brief check`, shows it to the human, asks, and records their explicit approval. `canon skills show role-planner`
 2. **Subject.** `canon subject new`, then `canon change new` (`--change-kind chore` for work that alters no behavior); the change writes the brief skeleton. `canon skills show role-planner`
 3. **Scenarios.** `canon scenario new --flow <F-id> --case <case>` per behavior of a flow step, failure paths (`--case failure`) included; many at once with `--input` (below). `canon skills show role-implementer`
 4. **Units.** Split the work; one unit is one flow step's slice with a named verify command, and each unit has its own actor id and session id, passed on everything it records. A unit never attests another unit's work.
@@ -217,16 +233,19 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
   (`canon subject move <id> --to verifying`, `canon change new <slug>`), and
   `--kind` values carry no `_record` suffix (`--kind evidence`).
 - `canon status` sends the planner to write the brief while `brief check`
-  has blockers; the human stop appears only when the brief is clean and
+  has blockers; the approval step appears only when the brief is clean and
   unapproved.
 - Page long lists with `--limit <n>` and `--cursor <nextCursor>` (`--all`
   for everything), and project fields with `--fields a,b` (`status`, `export`,
   `query`, `finding list`, `divergence list`, `context`).
 - `--override-reason <text>` is the only way to proceed past a waivable
   refusal; it is recorded, echoed in `data.overrides[]` and listed by `status`
-  for the human. There is no `--force`. `brief approve`, `policy approve` and
-  `divergence accept` are human-only and refuse every agent role: report the
-  exact call, ids filled in, and wait; never unset your role to run one.
+  for the human. There is no `--force`. `brief approve`, `policy approve`,
+  `divergence accept` and the `migrate --commit` that re-binds `Approved:`
+  lines record a human's decision and refuse every agent role (`HUMAN_ONLY`)
+  unless they record the explicit answer the human gave you, with
+  `--relayed-via <tool>` (show, ask, record, as for the brief; `canon skills
+  show role-planner`); never unset your role to run one.
 
 ### Many records at once: `--input`
 
@@ -343,7 +362,7 @@ current step needs.
 | Name | What it is for |
 | --- | --- |
 | `canon` | This core guide: the loop, driving the CLI, routing. |
-| `role-planner` | Planner steps 1–2: subject, change, PRD brief, the human stop. |
+| `role-planner` | Planner steps 1–2: subject, change, PRD brief, the approval. |
 | `role-implementer` | Implementer steps 3–6: scenarios, units, code, evidence. |
 | `role-reviewer` | Reviewer step 7: findings and signed reviews in a separate session. |
 | `role-orchestrator` | Orchestrator step 8: dispatch, transitions, resuming, upgrading. |

package/dist/skills/reference/brief-align.md

@@ -33,7 +33,7 @@ A chore adds no scenarios and has no flow: this pass does not apply to it.
 
 ## Next
 
-Implement, evidence and review (loop steps 5 to 7). If the brief had to change, the human answers again with `canon brief approve` (theirs; agent roles are refused).
+Implement, evidence and review (loop steps 5 to 7). If the brief had to change, the human answers again: show the brief, ask, and record an explicit approval with `--relayed-via` (`canon skills show role-planner`).
 
 ## Invariants (every brief pass)
 
@@ -41,4 +41,4 @@ Implement, evidence and review (loop steps 5 to 7). If the brief had to change,
 - Explaining writes nothing. Asked what a finding means or what a pass would do, answer in chat and leave the brief untouched.
 - No pass requires another as a prerequisite. Run the one the findings or the human point at, in any order.
 - A pass closes only the findings it rechecked: rerun `canon brief check` after the edit and report a finding as closed only when it is gone from that run. Never claim a rule you did not rerun.
-- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and the human's `canon brief approve` again (agent roles are refused).
+- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer, shown and asked again, and a new `canon brief approve` (recorded with `--relayed-via` from that answer).

package/dist/skills/reference/brief-clarify.md

@@ -33,7 +33,7 @@ Every open line is a question with a proposed default or a stated assumption. `c
 
 ## Next
 
-`harden` if the flow changed; otherwise report to the human, who answers the questions and approves (`canon brief approve` is theirs; agent roles are refused).
+`harden` if the flow changed; otherwise put the questions and the brief to the human and ask; record an explicit approval with `brief approve` with `--relayed-via <tool>` (`canon skills show role-planner`).
 
 ## Invariants (every brief pass)
 
@@ -41,4 +41,4 @@ Every open line is a question with a proposed default or a stated assumption. `c
 - Explaining writes nothing. Asked what a finding means or what a pass would do, answer in chat and leave the brief untouched.
 - No pass requires another as a prerequisite. Run the one the findings or the human point at, in any order.
 - A pass closes only the findings it rechecked: rerun `canon brief check` after the edit and report a finding as closed only when it is gone from that run. Never claim a rule you did not rerun.
-- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and the human's `canon brief approve` again (agent roles are refused).
+- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer, shown and asked again, and a new `canon brief approve` (recorded with `--relayed-via` from that answer).

package/dist/skills/reference/brief-harden.md

@@ -34,7 +34,7 @@ brief has none of them: harden its Invariants and Checks instead.
 
 ## Next
 
-`align` (`canon skills show brief-align`) once scenarios exist; `polish` (`canon skills show brief-polish`) for prose; otherwise report to the human.
+`align` (`canon skills show brief-align`) once scenarios exist; `polish` (`canon skills show brief-polish`) for prose; otherwise show the brief to the human and ask (`canon skills show role-planner`).
 
 ## Invariants (every brief pass)
 
@@ -42,4 +42,4 @@ brief has none of them: harden its Invariants and Checks instead.
 - Explaining writes nothing. Asked what a finding means or what a pass would do, answer in chat and leave the brief untouched.
 - No pass requires another as a prerequisite. Run the one the findings or the human point at, in any order.
 - A pass closes only the findings it rechecked: rerun `canon brief check` after the edit and report a finding as closed only when it is gone from that run. Never claim a rule you did not rerun.
-- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and the human's `canon brief approve` again (agent roles are refused).
+- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer, shown and asked again, and a new `canon brief approve` (recorded with `--relayed-via` from that answer).

package/dist/skills/reference/brief-polish.md

@@ -2,7 +2,7 @@
 
 Make the brief something a human reads once and understands. Run it whenever
 `canon brief check` reports `prose.*` advisories; `canon status` and
-`meta.next` name it before the human stop. It never blocks approval, and it
+`meta.next` name it before the approval step. It never blocks approval, and it
 is not finished by silencing rules: it is finished when the brief reads
 plainly and each advisory is gone or waived with a reason.
 
@@ -218,7 +218,7 @@ uses the section key `brief`.
 1. Fix the mode problems above, then the findings, section by section.
 2. Run `canon brief check <slug> --json`: the findings are in `data.findings[]`.
 3. Repeat until no advisory remains, or each remaining one is waived with a reason.
-4. Stop and report to the human, in the brief's language. Do not loop further: a clean run says nothing about whether the brief is good, only that these counts are within budget.
+4. Stop polishing and show the brief to the human (`canon brief show <slug> --body`), in the brief's language, and ask. Do not loop further: a clean run says nothing about whether the brief is good, only that these counts are within budget.
 
 ## NEVER
 
@@ -236,7 +236,7 @@ uses the section key `brief`.
 
 ## Next
 
-Report to the human, who approves with `canon brief approve` (theirs; agent roles are refused).
+Show the brief to the human and ask (`canon brief show <slug> --body`, then the harness question tool); record an explicit approval with `brief approve` with `--relayed-via <tool>` (`canon skills show role-planner`).
 
 ## Invariants (every brief pass)
 
@@ -244,4 +244,4 @@ Report to the human, who approves with `canon brief approve` (theirs; agent role
 - Explaining writes nothing. Asked what a finding means or what a pass would do, answer in chat and leave the brief untouched.
 - No pass requires another as a prerequisite. Run the one the findings or the human point at, in any order.
 - A pass closes only the findings it rechecked: rerun `canon brief check` after the edit and report a finding as closed only when it is gone from that run. Never claim a rule you did not rerun.
-- Write in the brief's language (detected from the text, or `language:` in `canon.yaml` when set). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and the human's `canon brief approve` again (agent roles are refused).
+- Write in the brief's language (detected from the text, or `language:` in `canon.yaml` when set). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer, shown and asked again, and a new `canon brief approve` (recorded with `--relayed-via` from that answer).

package/dist/skills/reference/brief-shape.md

@@ -69,7 +69,7 @@ prints the guidance of each empty one (in `language:`). A wrong heading
 
 ## Next
 
-`clarify` if the Questions section still has open lines; `harden` if flow and detail disagree; otherwise report to the human, who approves with `canon brief approve` (theirs; agent roles are refused).
+`clarify` if the Questions section still has open lines; `harden` if flow and detail disagree; otherwise show the brief to the human and ask; record an explicit approval with `brief approve` with `--relayed-via <tool>` (`canon skills show role-planner`).
 
 ## Invariants (every brief pass)
 
@@ -77,4 +77,4 @@ prints the guidance of each empty one (in `language:`). A wrong heading
 - Explaining writes nothing. Asked what a finding means or what a pass would do, answer in chat and leave the brief untouched.
 - No pass requires another as a prerequisite. Run the one the findings or the human point at, in any order.
 - A pass closes only the findings it rechecked: rerun `canon brief check` after the edit and report a finding as closed only when it is gone from that run. Never claim a rule you did not rerun.
-- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer and the human's `canon brief approve` again (agent roles are refused).
+- Write in the brief's language (detected from the text; `language:` in `canon.yaml` overrides it). Edits touch `.canon/changes/<slug>/brief.md` only. A brief edited after approval is not approved: it needs a new human answer, shown and asked again, and a new `canon brief approve` (recorded with `--relayed-via` from that answer).

package/dist/skills/reference/canon-gate.md

@@ -299,9 +299,9 @@ never rides along into a confirming audit. `--drop-attachment` and
 
 ### Nothing is attested before the brief is approved (`--override-reason`)
 
-The approval is never assumed: the agent writes the brief, stops and
-reports it, and builds nothing for that scope until the human answers.
-`canon evidence add` is the backstop for that stop (0.16 M7). It
+The approval is never assumed: the agent writes the brief, shows it to the
+human and asks, and builds nothing for that scope until the human answers.
+`canon evidence add` is the backstop for that rule (0.16 M7). It
 refuses (exit `1`, nothing staged or stored) while a subject the record
 attests for has an enforced, unapproved brief: a change the record
 answers to (below) has a canon `.canon/changes/<change>/brief.md` with no `Approved:`
@@ -315,7 +315,7 @@ check `canon status` and the ship guard use; see
 
 ```stderr
 canon evidence add: unreviewed-promotion demo-subject — evidence for world.demo.01: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line, so the human has not answered it; once they do, record their words with `canon brief approve c-demo --approver <the human> --note "<their words>"`
-canon evidence add: refused — stop, report the brief to the human and wait for their answer: nothing is built or attested for a subject before its brief is approved. Record their answer with `canon brief approve --approver <the human> --note "<their words>"` only from that answer; to attest anyway, pass --override-reason <text>, which is recorded on the evidence record
+canon evidence add: refused — stop and get the human's answer to the brief: nothing is built or attested for a subject before its brief is approved. Show it (`canon brief show --body`), ask with the harness question tool, and on their explicit approval record it with `canon brief approve --approver <their name> --note "<their words>" --relayed-via <the question tool> --actor <your actor id> --digest <change>=<the digest shown>` (or they approve on `canon dashboard`); never unset your role to run it; to attest anyway, pass --override-reason <text>, which is recorded on the evidence record
 ```
 
 For a change from an external plan with no canon brief yet, the first

package/dist/skills/reference/canon-policy.md

@@ -75,10 +75,13 @@ canon policy approve --approver <who> [--note <text>] [--repo <dir>]
 A human approves the policy after reviewing `.canon/policy.yaml`, in the
 same answer that approves a subject's brief (0.16; see the skill's working
 loop). `canon brief approve` records both in one call. `canon policy
-approve` is a human-only leaf: with a role declared (`--as` or `CANON_ROLE`)
-it is refused with `HUMAN_ONLY` (exit 2, not retryable), and no flag grants
-it to an agent. The human runs it themselves, for a policy-only change or
-after the brief answer, supplying `--approver` and `--note`. It
+approve` is a human's decision: with a role declared (`--as` or `CANON_ROLE`)
+it is refused with `HUMAN_ONLY` (exit 2, not retryable) unless it records the
+answer the human gave in the conversation: show them `.canon/policy.yaml`, ask,
+and on an explicit approval run it (the steps are in `canon skills show role-planner`) with `--relayed-via <tool>`, `--actor`,
+`--approver` and `--note` (their name and words); the file then carries `relay`
+(role, actor, tool). The human may run it themselves, for a policy-only change
+or after the brief answer, supplying `--approver` and `--note`. It
 writes `.canon/policy.approval.json` directly (nothing to promote):
 
 ```json

package/dist/skills/reference/canon-report-dashboard.md

@@ -163,10 +163,13 @@ refused brief): nothing is written and the page says to read it again. A request
 naming one brief the old way (`changeId`, `sha256`) is still accepted. The server is localhost only and
 refuses requests from other origins (`DASHBOARD_ORIGIN_REFUSED`).
 
-For an agent the human stop is unchanged: when clean briefs are waiting,
-tell the human they can approve them in `canon dashboard` (briefs page) or
-answer in chat. An agent never clicks Approve or fills the form, and runs
-`canon brief approve` only from the human's own words.
+For an agent: when clean briefs are waiting, show them (`canon brief show
+<slug> --body`), ask with the harness question tool, and tell the human they
+can approve them in `canon dashboard` (briefs page) instead. An agent never
+clicks Approve or fills the form; it runs `canon brief approve` only from the
+human's explicit answer, with `--relayed-via`. The page lists the approvals an
+agent recorded for the human under "Approved through an agent" (`relayed` in
+`GET /api/briefs`), with the role, actor and tool of each.
 
 The dashboard renders SEVEN panels — trust matrix, session costs, role
 memory, flywheel funnel, review burn-down, review rounds, review totals.

package/dist/skills/reference/canon-subject.md

@@ -207,8 +207,8 @@ the transition, not the check.
 
 This refusal is a backstop, and so is the evidence one: shipping is not
 the first thing an unapproved brief stops. The agent writes the brief,
-runs `canon brief check` until it has no blockers, then stops and reports
-it, and nothing is built or attested for the subject until the human
+runs `canon brief check` until it has no blockers, then shows it to the
+human and asks, and nothing is built or attested for the subject until the human
 answers. `canon evidence add` refuses (exit 1, nothing staged) a
 scenario whose `@subject` owner, or a task whose change
 an adopting subject, has an enforced, unapproved brief, through the same
@@ -547,7 +547,7 @@ warn, and a command that writes and judges it is refused
   human answers again and `approve` runs again. Run it only from the
   human's answer, with their words as `--note`.
 
-The optional refinement passes that fix findings before the human stop are
+The optional refinement passes that fix findings before the approval step are
 listed in `role-planner.md` in this directory.
 
 A **chore** (`canon change new --change-kind chore`) changes how the subject is
@@ -688,7 +688,7 @@ uses, so status and the gate cannot disagree about a gap:
   newest change's canon
   `brief.md` has no `Approved:` line, or it has no canon `brief.md` yet
   and comes from an external openspec `proposal.md`) and clean gets
-  `human: stop and report the brief in <brief>; build and attest nothing for <id> until the human answers (one answer approves brief and policy)`,
+  `human: show the brief in <brief> to the human and ask; build and attest nothing for <id> until the human answers (one answer approves brief and policy)`,
   where `<brief>` is the canon `brief.md`, or the external `proposal.md`
   when no canon brief exists yet. Its reason reads ``<id>: <why
   unanswered> (an older change's approval does not cover a new scope),
@@ -752,7 +752,7 @@ first, with `meta.nextOmitted` counting what was cut and `meta.waitingOn`
 
 ```json
 "next": [
-  { "command": "stop and report the brief in openspec/changes/c-promo/proposal.md; build and attest nothing for promo until the human answers; then record their words with `canon brief approve c-promo --approver <the human> --note \"<their words>\"`", "argv": [], "why": "promo: the brief is not approved", "actor": "human", "role": null },
+  { "command": "show the brief in openspec/changes/c-promo/proposal.md; build and attest nothing for promo until the human answers; then record their words with `canon brief approve c-promo --approver <the human> --note \"<their words>\"`", "argv": [], "why": "promo: the brief is not approved", "actor": "human", "role": null },
   { "command": "canon finding close c-cart --round 1 --seq 1 --disposition fixed --actor <unit> --session <session>", "argv": [], "why": "cart: 1 open blocker finding(s); fix it, commit, then close it", "actor": "agent", "role": "implementer" },
   { "command": "canon status", "argv": ["canon", "status"], "why": "1 scenario(s) carry no @subject tag (first: cart.promo.01); add `@subject:<id>` above each in its .feature file, then check again", "actor": "agent", "role": "planner" }
 ]

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
 
@@ -318,7 +320,7 @@ canon evidence add --input '[{"scenario":"auth.login.01","class":"test-run","ref
    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
@@ -361,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
 
@@ -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
@@ -491,14 +492,14 @@ 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
@@ -507,25 +508,39 @@ implementer's context, and have it record its real session id as
 `--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 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
+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
@@ -563,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. |

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,7 +32,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
@@ -243,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.
 
@@ -273,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
@@ -310,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. |