@journeykit/canon 0.27.0 → 0.28.0

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

@@ -1,46 +1,210 @@
 # Role: reviewer
 
 You are the independent second look. Declare the role with
-`CANON_ROLE=reviewer` (or `--as reviewer`); `--role` on `review add` then
-defaults to `reviewer`.
+`CANON_ROLE=reviewer` (or `--as reviewer`); `--role` on `review scenario`,
+`review change` and `finding add` then defaults to `reviewer`. The human's
+acts refuse you (`HUMAN_ONLY`): `brief approve`, `policy approve` and
+`divergence accept`. Name what the human has to decide in your report; never
+look for a flag that grants it. You never run them, and never remove or unset your role (`env -u CANON_ROLE`,
+dropping `--as`) to get past the refusal: report the exact call, slug filled in, and
+wait; the human runs it (or uses `canon dashboard`).
 
 ## Commands
 
-Every line is complete; fill the `<placeholders>`. `<root-id>` is the `id` of
-a `specs.roots[]` entry in `canon.yaml` (`root` by default).
+Every leaf of this role is below with its full syntax line (every option the leaf
+has) and an example generated from the CLI's own spec, which runs as written against
+the example story (subject `demo`, change `add-login`, scenario `auth.login.01`): swap
+in your ids. Use only the options on a line; never guess one. Ask `canon schema
+<command> --json` only for a leaf this block does not list, or after a `USAGE` refusal.
 
+<!-- canon:generated commands-reviewer begin -->
+Every leaf takes `--as <ROLE>` and `--json`; `--repo <DIR>` too, except `completion`, `schema`, `skills show`. `--input <JSON|FILE|->` runs a leaf from one JSON document (an array is a batch) and is only on the lines ending `[--input]`. Its document keys are the option names in camelCase, singular even when the option repeats (the value is then an array), and `operands` holds the operands. `--fields <FIELDS>` is a comma list; camelCase and snake_case both match.
+In a syntax line `<X>` is a value, `[x]` optional, `a | b` a choice, `(a | b)` exactly one is required, `[--x <V>]*` may repeat, `<X>+` is one or more, `[--a --b <V>]` go together. An option that is not on the line does not exist: it is refused (`USAGE`).
+
+```text
+# Read the brief against the rules
+canon brief check [<CHANGE_ID>]
+```
+```bash
+canon brief check
+```
+```text
+# Show where the change stands and the next one to three steps; never edits
+canon brief show [<CHANGE_ID>]
+```
+```bash
+canon brief show
+```
+```text
+# Write the shell completion script for canon (bash, zsh or fish)
+canon completion <SHELL>
+```
+```bash
+canon completion zsh
+```
+```text
+# Show what you can author here: record kinds, fields, enums, policies
+canon context [--fields <FIELDS>]
+```
+```bash
+canon context
+```
+```text
+# Add a divergence candidate, staged with no run_seq yet
+canon divergence add <SCENARIO_ID> --actor-id <ACTOR_ID> [--project-id <PROJECT_ID>] [--rev <REV>] [--state <open|still-divergent|resolved|deferred>] [--reason <TEXT>] [--expiry <TIMESTAMP>] [--round <N>] [--session-id <SESSION_ID>] [--detail <TEXT>] [--role <ROLE>] [--promote | --no-promote] [--input]
+```
+```bash
+canon divergence add auth.login.01 --actor-id 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]
+```
+```bash
+canon divergence defer auth.login.01 --actor-id alice --reason "waiting on the vendor" --expiry 2030-01-01T00:00:00Z --role reviewer
+```
+```text
+# List the current divergence burn-down state
+canon divergence list [--as-of <TIMESTAMP>] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
+```
+```bash
+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]
+```
+```bash
+canon divergence resolve auth.login.01 --actor-id alice --role reviewer
+```
+```text
+# Record one code-review finding
+canon finding add --change-id <CHANGE_ID> --round <N> --seq <N> --severity <blocker|should-fix|note> --actor-id <ACTOR_ID> --summary <TEXT> [--disposition <open|fixed|rejected|deferred>] [--rev <REV>] [--resolution-rev <REV>] [--introduced-rev <REV>] [--file-ref <TEXT>] [--scenario-id <SCENARIO_ID>]* [--role <ROLE>] [--session-id <SESSION_ID>] [--promote | --no-promote] [--input]
+```
+```bash
+canon finding add --change-id add-login --round 1 --seq 2 --severity should-fix --actor-id alice --summary "Token is logged"
+```
+```text
+# Move an already-committed finding's disposition
+canon finding close <CHANGE_ID> --round <N> --seq <N> --disposition <open|fixed|rejected|deferred> [--resolution-rev <REV>] [--reason <TEXT>] [--actor-id <ACTOR_ID>] [--role <ROLE>] [--session-id <SESSION_ID>] [--promote | --no-promote] [--input]
+```
+```bash
+canon finding close add-login --round 1 --seq 1 --disposition rejected --reason "works as designed"
+```
+```text
+# List a change's committed findings at their latest version
+canon finding list --change-id <CHANGE_ID> [--open] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
+```
+```bash
+canon finding list --change-id add-login
+```
+```text
+# Validate a spec/artifact corpus against canon's format
+canon format [<DIR>]
+```
 ```bash
-canon brief check --change-id <slug> --as reviewer --json
-canon gate check --as reviewer --json                 # once, before review add
-canon finding add --change-id <slug> --round <n> --seq <n> --severity <blocker|should-fix|note> --reviewer <me> --actor-id <me> --session-id <session> --summary "<defect>" --scenario-id <id> --scenario-id <id> --as reviewer --json   # one --scenario-id per scenario the defect is about
-canon finding list --change-id <slug> --open --as reviewer --json
-canon finding close --change-id <slug> --round <n> --seq <n> --disposition fixed --resolution-sha <sha> --as reviewer --json
-canon finding close --change-id <slug> --round <n> --seq <n> --disposition rejected|deferred --reason "<why, one line>" --as reviewer --json   # --reason is required here (FINDING_REASON_REQUIRED); optional for fixed
-canon review add --project-id <root-id> --scenario-id <id> --scenario-id <id> --reviewer <me> --actor-id <me> --role reviewer --session-id <session> --pin <sha> --upstream-ref <ref> --as reviewer --json
-canon review add --project-id <root-id> --scenario-ids-from - --reviewer <me> --actor-id <me> --role reviewer --session-id <session> --pin <sha> --upstream-ref <ref> --as reviewer --json   # ids on stdin, one per line
-canon review add --project-id <root-id> --change-id <chore-slug> --reviewer <me> --actor-id <me> --role reviewer --session-id <session> --pin <sha> --upstream-ref <ref> --as reviewer --json   # a chore: one change-level review of its invariants and checks against the diff
-canon divergence accept --project-id <root-id> --scenario-id <id> --reason "<why the gap stays>" --tracking <issue-url-or-ref> [--expiry YYYY-MM-DD] --reviewer <me> --actor-id <me> --session-id <session> --as reviewer --json
-canon artifacts verify --full --as reviewer --json    # the files the evidence and reviews bind are in the artifact store; refuses when an object store is unreachable
-canon query --kind evidence --history --as reviewer --json   # every version, not only the current record
-canon query --kind evidence --history --scenario-id <id> --as reviewer --json   # one scenario's red-then-green pair
+canon format .canon/specs
 ```
+```text
+# Run the coverage/ledger/staleness/trust checks (0 clean, 1 red, 2 usage)
+canon gate check [--release]
+```
+```bash
+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>]
+```
+```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>]
+```
+```bash
+canon retrieve --for-role reviewer --domain dev --limit 20
+```
+```text
+# Write one attributed Review record for a chore change directly to the ledger (exactly one provenance ref required)
+canon review change <CHANGE_ID> --actor-id <ACTOR_ID> (--upstream-ref <TEXT> | --original-spec-ref <TEXT>) [--project-id <PROJECT_ID>] [--rev <REV>] [--role <ROLE>] [--session-id <SESSION_ID>] [--review-outcome <signed|indeterminate|unavailable>] [--reviewer-provider <NAME>] [--reviewer-model <NAME>] [--reviewer-harness <NAME>] [--artifact <PATH>]* [--max-artifact-mib <N>] [--input]
+```
+```bash
+canon review change add-login --actor-id alice --role reviewer --original-spec-ref docs/prd.md
+```
+```text
+# Write one attributed Review record per scenario directly to the ledger, nothing to promote (exactly one provenance ref required)
+canon review scenario <SCENARIO_ID>+ --actor-id <ACTOR_ID> (--upstream-ref <TEXT> | --original-spec-ref <TEXT>) [--project-id <PROJECT_ID>] [--rev <REV>] [--role <ROLE>] [--session-id <SESSION_ID>] [--review-outcome <signed|indeterminate|unavailable>] [--reviewer-provider <NAME>] [--reviewer-model <NAME>] [--reviewer-harness <NAME>] [--artifact <PATH>]* [--max-artifact-mib <N>] [--input]
+```
+```bash
+canon review scenario auth.login.01 --actor-id alice --role reviewer --original-spec-ref docs/prd.md
+```
+```text
+# Describe canon's own commands
+canon schema [<PATH>]* [--errors | --error <CODE>]
+```
+```bash
+canon schema evidence add
+```
+```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]
+```
+```bash
+canon skills show canon --full
+```
+```text
+# Show where this repo stands: subjects by status, their gaps, and the next commands
+canon status [--fields <FIELDS>]
+```
+```bash
+canon status
+```
+<!-- canon:generated commands-reviewer end -->
 
-`review add` needs `--upstream-ref <ref>` or `--original-spec-ref <path>`;
-add `--artifact <path>` (repeatable) for user-visible behavior. A short
-`<sha>` is fine. With `write.promote: manual`, follow `finding add` and
-`finding close` with `canon gate promote --as reviewer --json`.
+`review scenario` needs exactly one of `--upstream-ref <ref>` or
+`--original-spec-ref <path>`; add `--artifact <path>` (repeatable) for
+user-visible behavior. `--rev` is the commit you reviewed (default `HEAD`;
+any git revision, a short sha included). With `write.promote: manual`,
+follow `finding add` and `finding close` with `canon gate promote --as
+reviewer --json`. `review scenario` has no `--summary` or note option: what you
+found goes in `finding add --summary`.
 
-A scenario review pins what you saw: the scenario's digest plus the verdict
+The forms you reach for most (the story's ids; swap in yours):
+
+```bash
+canon review scenario auth.login.01 auth.login.02 --actor-id reviewer-1 --session-id session-7 --original-spec-ref docs/prd.md
+canon review scenario auth.login.01 --actor-id reviewer-1 --session-id session-7 --review-outcome indeterminate --original-spec-ref docs/prd.md
+canon review change add-login --actor-id reviewer-1 --session-id session-7 --original-spec-ref docs/prd.md
+canon finding add --change-id add-login --round 1 --seq 2 --severity blocker --actor-id reviewer-1 --session-id session-7 --summary "No rate limit" --scenario-id auth.login.01 --scenario-id auth.login.02 --introduced-rev HEAD~3
+canon finding close add-login --round 1 --seq 2 --disposition fixed --resolution-rev HEAD
+canon finding close add-login --round 1 --seq 3 --disposition rejected --reason "works as designed"
+canon finding list --change-id add-login --open
+```
+
+Several findings at once are one `--input` array (the keys are option names
+in camelCase):
+
+```text
+canon finding add --input '[{"changeId":"add-login","round":1,"seq":3,"severity":"note","actorId":"reviewer-1","summary":"Token is logged"},{"changeId":"add-login","round":1,"seq":4,"severity":"should-fix","actorId":"reviewer-1","summary":"Error text leaks the user name"}]'
+```
+
+A review pins what you saw: the scenario's digest plus the verdict
 and checks (report format and matched case names, or artifact digests) of its
 latest evidence per role, not which record held them. It stays current when
 the implementer records the same verdict from the same checks again, and
 goes stale when the verdict or the checks differ or the scenario changes.
-Reviews written before 0.23 do not count until `canon migrate` re-pins them
-(an advisory names it); that is the orchestrator's step, not yours.
+A review of code that is not committed yet is allowed: the record carries
+`codeTree` and `worktreeDirty: true`, and the commit made from that working
+tree has the same `codeTree`, so the review survives the commit; only its
+pins (above) make it stale, never the commit or the code tree. Reviews
+written before 0.23 do not count until `canon migrate` re-pins them (an
+advisory names it); that is the orchestrator's step, not yours.
 
-Run `gate check` once, before `review add`: its `unreviewed-promotion`
+Run `gate check` once, before `review scenario`: its `unreviewed-promotion`
 violations are the subjects and scenarios that need your review. Do not loop
-it. After `review add`, read its `meta.next` instead of calling `gate check`
+it. After `review scenario`, read its `meta.next` instead of calling `gate check`
 or `status` again.
 
 ## Separate session
@@ -53,7 +217,7 @@ everything you record. A harness with no subagent tool starts you (a new
 
 ## Read the PRD
 
-1. `brief check`: the brief must have no blockers.
+1. `brief check`: the brief must have no blockers (exit 1 means it has some).
 2. Read the brief itself, `.canon/changes/<slug>/brief.md`: intent, the flow
    `F1`, `F2`, …, acceptance and failure path per step, out of scope. You do
    not refine the brief; a brief defect is a finding, not an edit.
@@ -65,10 +229,12 @@ everything you record. A harness with no subagent tool starts you (a new
 ## Run the checks yourself
 
 Run the build, the tests and the app the evidence claims to cover, on the
-commit you pin. Compare the results with the evidence records. Never sign
+code you review: the commit `--rev` names, or the working tree when it is
+not committed yet. Compare the results with the evidence records. Never sign
 what you could not run: a reviewer that cannot run the tests says so and
-does not sign off; record that instead (`--outcome indeterminate`, or
-`unavailable` when you could not run).
+does not sign off; record that instead (`--review-outcome indeterminate`,
+or `unavailable` when you could not run). Only `signed` counts; the others
+stay on the record as a review gap.
 
 ## Check the checks
 
@@ -88,54 +254,86 @@ steps, in two separate passes, and say which pass a finding came from:
 
 When a check looks weak, you may name the one-line change to the code that
 should make it fail and run it if it is cheap; if the test stays green, record
-the finding. For a fix, read `canon query --kind evidence --history
---scenario-id <id>`: expect an earlier non-faithful version, or a named
-closest reproduction in `--ref`; record a finding when neither exists. Put
-one blast-radius fact in the finding or review `--summary`: what else the
-change touches that the checks do not exercise. Do all of this before you
+the finding. For a fix, read `canon query --kind evidence --history --json`
+for that scenario's records: expect an earlier non-faithful version, or a
+named closest reproduction in `--ref`; record a finding when neither exists.
+Put one blast-radius fact in the finding or review `--summary`: what else the
+change touches that the checks do not exercise. Read the waivers too:
+`status` lists every `--override-reason` an implementer or the orchestrator
+used (it is echoed in `data.overrides[]` of the write that took it). A
+waiver whose reason does not hold is a finding. Do all of this before you
 sign.
 
-## Accept a known gap
+## A known gap is the human's to accept
 
 `divergence accept` is for a scenario whose honest evidence is `divergent`
 and whose gap is limited by something outside this change (an upstream
-limit, a platform bug) and is tracked there: give the reason and the
-`--tracking` reference, and an `--expiry` when the limit should be gone by
-a date. Never use it to skip a fix you can make in this change. It is your
-step, from a session that did not attest the evidence
-(`DIVERGENCE_ACCEPT_REFUSED` otherwise). The acceptance pins that evidence:
-new evidence for the scenario, or its expiry, ends it, and you accept (or
-the implementer fixes) again. An accepted gap counts as covered for the
-ship guard and stays listed as `accepted-divergence` in `status` and
-`gate check`.
+limit, a platform bug) and is tracked there. It records a human's decision,
+so it refuses every agent role (`HUMAN_ONLY`), you included. What you do:
+confirm the evidence really is divergent and the limit is outside this
+change, then report to the human the scenario ids, the reason, the
+tracking reference and an expiry when the limit should be gone by a date.
+Give the exact call, ids filled in: the human runs `canon divergence accept
+<ids> --actor-id <name> --reason "<why>" --tracking <ref>` themselves in their
+own shell, from a session that did not attest the evidence
+(`DIVERGENCE_ACCEPT_REFUSED` otherwise); you never run it or unset your role to. Never suggest it to skip
+a fix the implementer can make in this change. The acceptance pins that
+evidence: new evidence for the scenario, or its expiry, ends it, and the
+human accepts (or the implementer fixes) again. An accepted gap counts as
+covered for the ship guard and stays listed as `accepted-divergence` in
+`status` and `gate check`.
 
 ## Record
 
 - Every defect is a finding; `finding list` shows round, seq, severity and
   disposition, so the next seq and the open blockers are one command away.
-  Close a finding once it is dealt with. When you close it `rejected` or
-  `deferred`, give the reason in one line with `--reason "<why>"`: the close
-  is refused without it (`FINDING_REASON_REQUIRED`), and `finding list` shows
-  it as `[reason: …]` so the next reader sees why it was not fixed.
-- Sign off in one batch with `review add`, all or nothing. It writes
+  `--rev` of a finding is the commit the round reviewed; `--introduced-rev`
+  is the commit that introduced the defect and has no default: source it
+  (`git log -S`, `git blame`) or leave it out, never guess it. Many findings
+  at once are one `finding add --input` with an array, validated before any
+  write.
+- Close a finding once it is dealt with: `finding close <slug> --round <n>
+  --seq <n> --disposition fixed` records `--resolution-rev` (default
+  `HEAD`). When you close it `rejected` or `deferred`, give the reason in
+  one line with `--reason "<why>"`: the close is refused without it
+  (`FINDING_REASON_REQUIRED`), and `finding list` shows it as
+  `[reason: …]` so the next reader sees why it was not fixed. Closing a
+  finding that already has that disposition is `unchanged`.
+- Sign off in one batch with `review scenario <ids>`, all or nothing. It writes
   directly; nothing to promote. canon stores and re-checks attached bytes
   and never compares images.
 - Pass `--scenario-id` for each scenario a finding is about. A blocker you
   close `fixed` then stays blocking until the implementer records evidence
-  again for those scenarios alone (`evidence add --scenario-id <id> …`); the
+  again for those scenarios alone (`evidence add --scenario-id <id>`); the
   close inherits the list. A blocker naming no scenario asks for the whole
   suite again (`evidence add --all-scenarios`), which on a big suite is
   a long e2e run for a one-scenario fix, so name them. Your pinned review
   stays current when the new evidence says the same, otherwise look again.
 - Fixes you ask for return as a re-review of the same change. When new
   evidence changes a verdict or the checks and so stales your review, look
-  again before you re-pin.
+  again before you sign it again.
   A chore has no scenarios: review it with one change-level review, `canon
-  review add --project-id <root-id> --change-id <slug> --reviewer <me> --role
-  reviewer --pin <sha> --upstream-ref <ref> …`. It signs the chore's
-  invariants and checks against the diff and pins its brief, so editing the
-  brief stales it. The chore also needs evidence recorded after its approval
-  (the implementer's `--all-scenarios` run) before it ships.
+  review change <slug> --actor-id <me> --session-id <session>
+  --upstream-ref <ref>` (or `--original-spec-ref <path>`). It signs the
+  chore's invariants and checks against the diff and pins its brief, so
+  editing the brief stales it. The chore also needs new evidence on every
+  scenario whose code changed since its latest evidence (the implementer's
+  batch) before it ships; a docs-only chore needs your review alone.
+
+**Done when:** `canon gate check` lists no `unreviewed-promotion` violation
+and no open blocker for the change (read `data.violations[]` in `canon gate
+check --json`; `canon finding list --change-id add-login --open` shows the
+open findings), or each remaining one is a finding you recorded and the
+implementer owns. Your last write's `meta.next` names the next step.
+
+## Retry safety
+
+`review scenario`, `review change` and `finding add` are content-keyed: an
+identical repeat is reported `unchanged` (`meta.unchanged: true`, or the
+element's `status` in a batch), so after a timeout run the same command
+again. A different finding under an occupied round and seq is refused
+(`FINDING_SEQ_OCCUPIED`): take the next seq. `finding close` with the same
+disposition is a no-op too.
 
 ## Excuses that fail
 
@@ -146,5 +344,6 @@ ship guard and stays listed as `accepted-divergence` in `status` and
 | "I cannot run the tests, but the evidence looks right." | Say so and record `indeterminate` or `unavailable`; never sign what you could not run. |
 | "This is a minor defect; I will skip the finding." | Every defect is a finding; severity says how much it matters. |
 | "I will edit the brief to fix it." | A brief defect is a finding, not an edit. |
+| "I will accept the gap myself, the limit is real." | `divergence accept` refuses agent roles; report the gap to the human. |
 
-Reference: `reference/canon-review.md`.
+Reference: `canon skills show canon-review`.

package/dist/skills/scripts/canon-retrieve-pre-dispatch.sh

@@ -73,7 +73,7 @@ TOOL_NAME="$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || t
 # fixed point of `regime_key`'s own segment canonicalizer, so the
 # derived `--role` still equals the assembled regime_key's leading
 # segment. The repo/area segments are NOT slugified here — they are
-# canonicalized by `canon regime-key` below (the write-path serializer).
+# canonicalized by `canon regime show` below (the write-path serializer).
 slugify() {
   printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9' '-' | sed -E 's/-+/-/g; s/^-//; s/-$//'
 }
@@ -97,20 +97,25 @@ if [ -z "$REGIME" ]; then
   fi
   [ -n "$HASH" ] || exit 0
   # Assemble the regime_key through canon's OWN serializer (`canon
-  # regime-key` -> `canon_model::ids::regime_key`), the identical
+  # regime show` -> `canon_model::ids::regime_key`), the identical
   # normalizer the S4/S6/S14 WRITE path uses — never a second shell
   # derivation. A prior local `slugify` of the repo segment mapped a
   # written `my_repo` to a queried `my-repo`, so `retrieve_guidance`
   # fail-softed to empty and silently missed the namespace. `--role`
   # is the already-kebab ROLE (a fixed point of that canonicalizer, so
   # it still equals the assembled key's leading segment). Malformed
-  # segments make `canon regime-key` exit nonzero -> `|| true` -> empty
+  # segments make `canon regime show` exit nonzero -> `|| true` -> empty
   # REGIME -> the silent no-op just below.
-  REGIME="$(canon regime-key --role "$ROLE" --repo "$REPO_RAW" --area "$AREA_RAW" --hash "$HASH" 2>/dev/null || true)"
+  REGIME="$(canon regime show --role-segment "$ROLE" --repo-name "$REPO_RAW" --area "$AREA_RAW" --hash "$HASH" 2>/dev/null || true)"
   [ -n "$REGIME" ] || exit 0
 fi
 
-GUIDANCE_JSON="$(canon retrieve --role "$ROLE" --regime "$REGIME" --json 2>/dev/null || true)"
+GUIDANCE_JSON="$(canon retrieve --for-role "$ROLE" --regime "$REGIME" --json 2>/dev/null || true)"
+[ -n "$GUIDANCE_JSON" ] || exit 0
+
+# canon >= 0.28 envelopes the result ({ok, data: [...], meta}); 0.27 printed the bare array.
+# `(.data? // .)` reads either, so this hook works before and after the upgrade.
+GUIDANCE_JSON="$(printf '%s' "$GUIDANCE_JSON" | jq -c '(.data? // .)' 2>/dev/null || true)"
 [ -n "$GUIDANCE_JSON" ] || exit 0
 
 COUNT="$(printf '%s' "$GUIDANCE_JSON" | jq 'length' 2>/dev/null || echo 0)"

package/man/canon-adapter-authorize.1

@@ -0,0 +1,44 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-adapter-authorize 1  "authorize 0.28.0" 
+.SH NAME
+canon\-adapter\-authorize \- Authorize declared capabilities against repository policy (preflight only)
+.SH SYNOPSIS
+\fBcanon adapter authorize\fR [\fB\-\-as\fR] <\fB\-\-response\fR> [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Authorize declared capabilities against repository policy (preflight only)
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` defaults to it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-\-response\fR \fI<FILE>\fR
+JSON response file to validate and authorize
+.TP
+\fB\-\-repo\fR \fI<DIR>\fR
+The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
+.TP
+\fB\-\-json\fR
+Output authorization result as JSON
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH VERSION
+v0.28.0

package/man/canon-adapter-validate.1

@@ -0,0 +1,44 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-adapter-validate 1  "validate 0.28.0" 
+.SH NAME
+canon\-adapter\-validate \- Read and validate one provider\-neutral response envelope
+.SH SYNOPSIS
+\fBcanon adapter validate\fR [\fB\-\-as\fR] <\fB\-\-response\fR> [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Read and validate one provider\-neutral response envelope
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` defaults to it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-\-response\fR \fI<FILE>\fR
+JSON response file to validate
+.TP
+\fB\-\-repo\fR \fI<DIR>\fR
+The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
+.TP
+\fB\-\-json\fR
+Output the normalized core summary as JSON
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH VERSION
+v0.28.0

package/man/canon-adapter.1

@@ -0,0 +1,46 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-adapter 1  "adapter 0.28.0" 
+.SH NAME
+canon\-adapter \- Validate a provider\-neutral adapter response without executing a provider
+.SH SYNOPSIS
+\fBcanon adapter\fR [\fB\-\-as\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Validate a provider\-neutral adapter response without executing a provider
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` defaults to it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH SUBCOMMANDS
+.TP
+canon\-adapter\-validate(1)
+Read and validate one provider\-neutral response envelope
+.TP
+canon\-adapter\-authorize(1)
+Authorize declared capabilities against repository policy (preflight only)
+.SH EXTRA
+Examples:
+  canon adapter validate \-\-response response.json
+  canon adapter validate \-\-response response.json \-\-repo . \-\-json
+.SH VERSION
+v0.28.0

package/man/canon-artifacts-move.1

@@ -0,0 +1,63 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-artifacts-move 1  "move 0.28.0" 
+.SH NAME
+canon\-artifacts\-move \- Move the local artifact blobs to an object\-store tier, verify them, and remove the local copies
+.SH SYNOPSIS
+\fBcanon artifacts move\fR [\fB\-\-as\fR] <\fB\-\-tier\fR> [\fB\-\-commit\fR] [\fB\-\-plan\-digest\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Move the local artifact blobs to an object\-store tier, verify them, and remove the local copies
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` defaults to it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-\-tier\fR \fI<TIER>\fR
+The tier to move to: the name of an `s3` tier in canon.yaml (for example `cold`)
+.TP
+\fB\-\-commit\fR
+Act on the previewed plan; needs \-\-plan\-digest
+.TP
+\fB\-\-plan\-digest\fR \fI<DIGEST>\fR
+The `planDigest` the preview printed; the run acts only if the plan recomputed now has this digest
+.TP
+\fB\-\-repo\fR \fI<DIR>\fR
+The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
+.TP
+\fB\-\-json\fR
+Output JSON instead of the human\-readable form
+.TP
+\fB\-\-input\fR \fI<JSON|FILE|\->\fR
+The arguments as JSON: an object (one run) or an array / NDJSON file or `\-` (a batch); keys are the option names in camelCase, `operands` an array
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH EXTRA
+Examples:
+  canon artifacts move \-\-tier cold
+  canon artifacts move \-\-tier cold \-\-commit \-\-plan\-digest <DIGEST>
+
+The bare run previews: it lists every upload and removal and prints a planDigest, and writes nothing. \-\-commit \-\-plan\-digest acts on exactly that plan (PLAN_CHANGED, exit 2, when it changed since).
+
+\-\-tier names an `s3` tier of canon.yaml\*(Aqs `tiers:` (for example `cold`; its credentials are the tier\*(Aqs own). Every blob in .canon/artifacts/sha256 is hashed, uploaded under <prefix>sha256/<digest> (prefix artifacts/), and read back; only when all of them verified does canon.yaml gain `artifact_store: { backend: <tier>, prefix: artifacts/ }`, after which the local copies are removed and `.canon/artifacts/` is added to .gitignore. Commit the removal with the ledger.
+
+Idempotent and resumable: a run stopped anywhere leaves a repo the gate still passes, and the next run finishes; a second run finds nothing to do. A blob whose bytes do not match its name is never moved. Moving back to local is refused; `\-\-tier local` on a local repo is a no\-op.
+.SH VERSION
+v0.28.0