@journeykit/canon 0.7.0 → 0.9.0

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

@@ -0,0 +1,119 @@
+# canon-policy
+
+Canon uses ONE expression language — CEL — for every conditional knob a
+spec needs: policy-routing predicates, tier-aging thresholds, verdict-
+mapping guards, retrieval filters, and a template's `applies_when:`
+section. Wherever a `policy.yaml` predicate or an `applies_when:` string
+appears, it is a CEL expression evaluated against the target record.
+
+## The closed CEL profile
+
+Every expression is evaluated against exactly one variable, `record` (the
+target kind's own fields — always `record.<field>`, never the raw
+envelope), plus one registered function:
+
+- `record.<field>` — any field the target kind declares. Nested objects
+  (e.g. `record.actor.agent_id`) resolve to a bounded depth; deeply-open
+  fields (an unconstrained `detail` blob) are readable but not field-
+  checked at write time.
+- `age_days(ts) -> int` — whole days between a timestamp field and a
+  caller-supplied "now" (never the wall clock read inside the function, so
+  the same expression against the same facts and the same `now` always
+  evaluates identically).
+- `has(record.<field>)` — CEL's built-in field-presence macro. Validates
+  like a normal field read.
+- CEL's operator grammar (`==`, `!=`, `&&`, `||`, `>`, `<`, `in`, the
+  ternary `? :`) and macros (`map`, `filter`, `all`, `exists`,
+  `exists_one`) are always available.
+
+Nothing else is. There is NO `size()`, `matches()`, `contains()`,
+`string()`, or any other CEL standard-library method — the profile is a
+closed allowlist of exactly the one function above. A
+`record.title.contains('x')`-shaped expression is rejected at WRITE time
+with an `UnknownFunction` diagnostic, not deferred to a runtime failure.
+Express the same check with `record.<field> == <literal>` / `in` / `has`
+instead.
+
+## Discovering what's bindable for a kind
+
+Run `canon context --json` and read its `cel` section: for each record
+kind it lists the bindable `record.<field>` names + types and the
+callable function allowlist a `policy.yaml` predicate may reference. This
+is the source of truth for "what can a CEL predicate for this kind
+reference?" — it's derived from the same schema `canon format` validates
+against, so there is no second, hand-maintained list to drift. See the
+`canon-context` skill.
+
+## Writing and validating an expression
+
+An expression is compiled BEFORE storage: both parsing AND a full walk
+(checking every `record.<field>` chain and every function call) run up
+front. There is no "accepted but fails on first evaluation" path — a
+type-invalid expression is rejected at author time with every diagnostic,
+not just the first.
+
+Evaluation is bounded by a wall-clock deadline (default 200ms): a
+pathological expression is reported as budget-exceeded rather than
+blocking. `now` is always caller-supplied — one `canon gate` run scoring
+many records uses the same `now` across the batch for mutually consistent
+results.
+
+## Reading a write-time "expected …" diagnostic
+
+Every rejection names what was expected, never a bare "invalid
+expression":
+
+- **Undeclared field** — `` `record.severty` is not a declared field of
+  `task` (expected one of: actor, at, evidence_note, kind, schema,
+  status, task_id, title) `` — check the name against `canon context`'s
+  field list; a typo is the usual cause.
+- **Undeclared variable** — `` `foo` is not a declared variable (expected
+  one of: record) `` — only `record` (plus a `map`/`filter` loop
+  variable) is ever in scope.
+- **Unknown function** — `` `contains` is not an allowlisted function
+  (expected one of: age_days) `` — a typo, or a CEL standard-library
+  method the closed profile doesn't register.
+- **Arity mismatch** — `` `age_days` expects 1 argument(s), got 0 ``.
+- **Type mismatch** — `` `age_days` expects argument 0 of type
+  `timestamp`, got `string` `` — the field passed isn't the type the
+  function's signature declares.
+
+## What never gets a CEL hook
+
+Some knobs deliberately stay code, not configurable CEL: reward-scoring
+functions, ingest/verdict-mapping transforms, and the content of an
+evidence record itself. If a task looks like "let this record configure
+its own evaluation logic," it is out of scope — raise it as a design
+question rather than adding an expression field. Conditional logic about
+what a record *means* lives in `policy.yaml`/`applies_when:`, evaluated
+against the record's fields, never inside the record.
+
+## Effect-aware risk tiers
+
+The optional `risk_tiers` section is not CEL. Absent means no risk-approval
+check. A present section must be a mapping of tier names to:
+
+```yaml
+risk_tiers:
+  high:
+    rank: 3
+    paths: ["src/auth/**"]
+    effects: ["secret-access"]
+    min_human_approvals: 1
+```
+
+Malformed sections or entries are retained as a policy diagnostic and make
+`canon gate check` fail closed with `uncovered-cell risk_tiers — risk_tiers
+policy-invalid: ...`; they are never treated as an empty map. The gate
+selects the highest-ranked tier against the current, faithful
+`EvidenceRecord` generation. A current `evidence_sha` and an explicit
+`surface_ref`/`effect:<kebab-slug>` binding are required for a tier that
+requires approval. Surface refs are validated syntax and attestation input,
+not proof that the caller's path is authoritative; configured rules cannot
+be bypassed by declaring a safe ref.
+
+Approval text is also only an attestation unless identity is verified.
+`canon evidence add` marks an approval verified only when `--approval-by`
+equals non-empty `CANON_ACTOR` and `--approval-role human` is supplied.
+The persisted verification bit is what later gates count; arbitrary caller
+strings, empty identities, and agent roles do not count.

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

@@ -0,0 +1,345 @@
+# canon-report-dashboard
+
+canon's single status surface: `canon report` renders TEN panels to
+markdown, `canon report --snapshot` exports the same ten marts to
+Parquet, and `canon dashboard` serves a small zero-network web app that
+renders SEVEN of them from such a snapshot. Neither surface computes an
+aggregate itself — both read canon's precomputed
+`crates/canon-store/sql/views.sql` marts, and each run reads the corpus
+ONCE (`crates/canon-report/src/query.rs`'s `PIN_CORPUS_SQL`), so no two
+panels within one report, or two files within one snapshot, can
+disagree. Across surfaces the input is what differs: a dashboard renders
+the snapshot it was given, so it matches a report only insofar as the
+two were generated from the same corpus.
+
+They can still disagree about what a number MEANS, and that is the
+failure this skill is written against: a friendly label or a paraphrase
+asserting something its query never computed. Every claim below is kept
+verbatim with the prose `canon report` actually renders
+(`canon_report::render`'s `pub const *_PANEL` literals and its inline
+one-liners), and `packages/dashboard/test/panel-copy.test.ts` pins this
+file to those literals. Copy a claim; do not paraphrase it.
+
+## Generated, never hand-edited
+
+`.canon/REPORT.md` carries a leading `<!-- GENERATED by \`canon report\` …
+DO NOT EDIT. -->` comment. If it looks stale or wrong, the fix is
+**always** re-running `canon report` (or fixing the underlying
+ledger/policy it renders) — never hand-editing the file. The report
+header embeds only input-derived digests (corpus hash, policy hash,
+ledger-head hash) and **no timestamp, no `source_git_sha`**, so a
+committed report is reproducible from named inputs and `canon report
+--check` can byte-diff it deterministically. `source_git_sha` belongs
+only in `--snapshot`'s `manifest.json` (below), which is never
+drift-checked.
+
+## `canon report [--repo <dir>]`
+
+Renders the current ten-panel report to `<repo>/.canon/REPORT.md`.
+`--repo` resolves through the nearest-`canon.yaml`-ancestor walk every
+subcommand uses — omit it (or pass `.`) to run from any subdirectory.
+
+```bash
+canon report                 # writes .canon/REPORT.md
+canon report --repo /path/to/repo
+```
+
+Between the digest header and the first panel, the report may also
+render a `## Kinds not read directly` section. It is config-derived
+(`canon.yaml`'s static `routing`/`tiers` tables), not a live backend
+probe, and an empty set renders NO section at all — so a repo routing
+nothing to a not-directly-readable backend renders exactly as before
+the section existed.
+
+## `canon report --check` — the CI drift gate
+
+Regenerates the report in memory and byte-compares it against the
+committed `.canon/REPORT.md`:
+
+- `MISSING` (exit 1) — no report has ever been written; run `canon report` first.
+- no drift (exit 0) — the committed file is byte-identical to what the
+  current inputs would render now.
+- `DRIFT` (exit 1) — the committed file disagrees with current inputs
+  (hand-edited, or the corpus/policy/ledger moved and nobody re-ran
+  `canon report`).
+
+```bash
+canon report --check   # wire into CI exactly like canon format --check / canon gate check
+```
+
+Wire it as a CI step or pre-push hook the same way `canon gate
+install-hooks` wires `canon gate check`; run `canon report --check`
+directly wherever CI already runs those.
+
+Exports all ten views to `<dir>/<table>.parquet` plus a
+`<dir>/manifest.json`. One explicit `COPY` per view — the exported
+columns are each view's own `SELECT` list, wider than the curated column
+subset the markdown tables render. `file` is always
+`<table>.parquet`, and the table order is the report's own panel order,
+with `mart_scope_status`, `mart_subjects`, `mart_review_rounds`,
+`mart_review_totals` and `mart_run_observability` APPENDED last so an
+existing consumer's order never moves:
+
+```json
+{
+  "generated_at": "...",
+  "source_git_sha": "...",
+  "source_digest": "...",
+  "tables": [
+    { "table": "mart_trust_matrix", "file": "mart_trust_matrix.parquet" },
+    { "table": "mart_session_costs", "file": "mart_session_costs.parquet" },
+    { "table": "mart_role_memory", "file": "mart_role_memory.parquet" },
+    { "table": "mart_flywheel_funnel", "file": "mart_flywheel_funnel.parquet" },
+    { "table": "mart_review_burndown", "file": "mart_review_burndown.parquet" },
+    { "table": "mart_scope_status", "file": "mart_scope_status.parquet" },
+    { "table": "mart_subjects", "file": "mart_subjects.parquet" },
+    { "table": "mart_review_rounds", "file": "mart_review_rounds.parquet" },
+    { "table": "mart_review_totals", "file": "mart_review_totals.parquet" },
+    { "table": "mart_run_observability", "file": "mart_run_observability.parquet" }
+  ]
+}
+```
+
+This is where `source_git_sha`/`generated_at` live (never in the
+drift-checked markdown header) — a snapshot is output-inclusive
+provenance. `source_digest` is one 12-hex fingerprint over the same
+corpus/policy/ledger digests the report header renders, so a snapshot's
+provenance is comparable to a report's without re-deriving anything.
+
+```bash
+canon report --snapshot /tmp/canon-snap
+```
+
+## `canon dashboard [--repo <dir>] [--snapshot <dir>] [--port <n>]`
+
+Serves the dashboard web app locally, pointed at a real snapshot:
+
+```bash
+# build the app once
+bun install && bun run --cwd packages/dashboard build
+
+canon dashboard                       # regenerates a fresh snapshot every run, serves it
+canon dashboard --snapshot /tmp/canon-snap --port 8080
+```
+
+- `--snapshot` omitted: `canon dashboard` calls `canon report --snapshot`
+  itself every run, into the conventional `.canon/dashboard-snapshot`
+  scratch directory — always fresh.
+- `--snapshot <dir>` given: served AS-IS when `<dir>` already has a
+  `manifest.json` (a separately generated snapshot, or a downloaded CI
+  artifact) — never silently regenerated over it. If it has no
+  `manifest.json`, one is generated there once.
+- Prints the URL to open, then serves until Ctrl-C. If the app is not
+  built, `canon dashboard` fails with the exact build command to run.
+
+The dashboard renders SEVEN panels — trust matrix, session costs, role
+memory, flywheel funnel, review burn-down, review rounds, review totals.
+**Scope status
+and subjects are exported to the snapshot but have no dashboard panel**;
+for those two, read `.canon/REPORT.md` or query the Parquet directly.
+Do not read a missing dashboard panel as an empty mart.
+
+The dashboard's freshness banner shows the snapshot's
+`generated_at`/`source_git_sha`/`source_digest` with a "scoped to this
+snapshot, not necessarily the live checkout" note — treat "matches
+`canon report`" as "matches the inputs that produced THIS snapshot".
+
+## Reading the ten panels
+
+In `canon report`'s own render order. Each panel names the view that
+computes it; nothing here is derived a second time.
+
+- **Trust matrix** (`mart_trust_matrix`) — Change/task coverage × green × who.
+  `covered` means at least one `evidence_record` exists for this `task_id`,
+  NOT that policy's REQUIRED evidence is present — that is `canon gate
+  check`'s question, and this view deliberately does not answer it. `green`
+  is the plain `verdict = 'faithful'` proxy over the latest attestation, not
+  `canon-gate`'s multi-rung trust-ladder classifier, which the view refuses
+  to re-implement in SQL. `evidence_count` counts ATTESTATIONS, superseded
+  versions included, because a re-attestation can only arrive as a new
+  version; `green` and `who` are read off one whole winner row, so they can
+  never come from two different attestations.
+
+- **Session costs** (`mart_session_costs`) — token/cost per
+  `(session, client, role, workspace_label)`. Every `run`/`session`/
+  `token_usage` record is folded to its latest version first, so
+  a re-ingested corrected cost REPLACES the superseded figure instead of being summed with it.
+  `workspace_label` is NOT a repo identity: it is the last non-empty path
+  segment of the `token_usage` event's workspace key and nothing more, so it
+  SPLITS one repo whose worktrees sit in differently-named directories and
+  MERGES two different repos sharing a directory name. Two stronger fields
+  exist and this mart reads neither — the event's own `workspace_key`, and
+  `Session.project_key`, which `canon-cli` stamps to the main worktree's key.
+
+- **Role memory** (`mart_role_memory`) — per-`(role, regime_key)` strategy
+  counts. `hit_rate` is NOT a retrieval hit rate: it is the fraction of that
+  namespace's distilled strategies carrying no `demotion` flag, i.e.
+  exactly `active_count / strategy_count`.
+  `avg_source_trajectories` is the mean number of source trajectories a
+  strategy was distilled from — an explicitly-named stand-in, because
+  canon records no per-strategy reward or effect metric.
+  There is no effect column, and this panel measures no effect.
+
+- **Flywheel funnel** (`mart_flywheel_funnel`) — verdicts → distilled →
+  retrieved → applied, per role, where
+  the last three stages count STRATEGIES, so the funnel narrows by construction.
+  `applied` is the retrieved set narrowed to strategies whose recipient run
+  has something recorded about how it ended, split into
+  `applied_attributed` (a resolved trajectory of the same role stamped with
+  that run id) and `applied_proxy` (only the run's own terminal status).
+  Both rules are CO-OCCURRENCE inside one run, never causation:
+  canon stores no edge from a strategy to a verdict,
+  so neither column can separate guidance that was followed from guidance
+  that was ignored. A large drop between two stages is the actionable
+  signal; `retrieved 0` means no run's recorded guidance names a strategy
+  that exists now.
+
+- **Review burn-down** (`mart_review_burndown`) — a per-day trend over raw
+  `Divergence.status` events, with the `evidence_*` columns breaking the same
+  window down by `EvidenceRecord.verdict`. `divergence_open_running_total` is
+  a running `opened - resolved` event count, NOT the number open now —
+  the two differ whenever one `resolved` record closes several findings on a
+  scenario. For current state per scenario, run `canon divergence status`.
+
+- **Scope status** (`mart_scope_status`) —
+  Every specified scenario × evidence-verified × plan-carried × spec-covered (`mart_scope_status`). Driven by the spec corpus, so a scenario no plan task declares still appears — with a NULL `task_id`, which is the worklist entry.
+  Grain is one row per authored `(project_id, scenario_id)`; the driving
+  side carries the project, so two spec roots authoring one scenario id
+  are two rows by construction. `evidence_covered`/`green` count either
+  side — the task the scenario is declared by, or scenario-keyed evidence
+  authored directly against it (`scenario_verdict`). `spec_covered IS
+  NULL` means NO coverage overlay row exists for that scenario — a
+  different state from an overlay row that exists and says
+  `spec_covered = false`. Read-only reporting; never a `canon gate` input.
+
+- **Subjects** (`mart_subjects`) —
+  Per-domain subject rollup: status × scenario coverage.
+  One row per `subject` record, folded to its latest version, so a subject
+  that walked proposed → shipped is still one row. `scenario_count` is how
+  many scenarios the subject owns — those whose latest synced `Scenario`
+  generation carries `@subject:<id>` (run `canon inventory sync` after
+  tagging); `covered_scenarios` is how many of those carry a latest
+  NON-divergent evidence verdict (`faithful` or `not_applicable`), the same
+  join and last-wins fold the `verifying -> shipped` gate uses. Read-only
+  reporting; never a `canon gate` input. See `canon-subject`.
+
+- **Review rounds** (`mart_review_rounds`) — one row per `(change_id, round)`
+  over `Finding` records (`canon finding add`, then `canon finding close` to
+  move a finding's disposition), folded to the latest version
+  of each `{change_id}__{round}__{seq}` finding first, so a finding raised
+  `open` and later closed is counted once and in one disposition bucket.
+  A round that found
+  nothing wrote no `Finding` and so has no row: the table
+  counts the rounds that FOUND something, never the rounds RUN
+  (s42's round 12 returned MERGEABLE with zero findings and is absent),
+  and canon has no record kind that marks a round as run.
+  `fix_of_fix` counts
+  findings whose SOURCED `introduced_by` equals the `resolution_sha` of a
+  finding earlier in the SAME change, ordered strictly by `(round, seq)`.
+  That is
+  a commit-id equality join over two recorded fields and nothing more:
+  it reads no git history, computes no blame,
+  and establishes no causal claim.
+  `introduced_by_unsourced` is the UNKNOWN bucket —
+  a finding with no sourced `introduced_by` is counted there and NEVER as
+  not-a-fix-of-fix.
+  What the count MEANS is one sentence, and every surface that reports it
+  states this sentence and no paraphrase of it:
+  `fix_of_fix` bounds NOTHING — not from below, not from above: it
+  UNDER-counts, because an unsourced finding is never counted and a fix in
+  one change that breaks something first found while reviewing a DIFFERENT
+  change is not counted at all; it OVER-counts, because a `resolution_sha`
+  commit may carry work BEYOND the fix and every finding recording that
+  commit is counted regardless; and for any individual match the data
+  cannot say whether the fix or the other work in that commit introduced
+  the defect.
+  Both directions are live in canon's own rows —
+  `f438c610` closed s42's round 8 AND shipped s42's whole feature, so
+  round 9's six matches cannot be attributed either way.
+  `reviewed_sha` is the greatest value any of
+  the round's findings recorded and reads `—` when none did; a round that
+  reviewed an uncommitted working tree is the usual reason, but the view
+  cannot distinguish that from findings that left the field unset.
+
+- **Review totals** (`mart_review_totals`) — one row per `change_id`,
+  and every column a `sum()`, `count(*)` or `max()` over the
+  `mart_review_rounds` rows above. This is the panel a release note is
+  copied from: the per-round table left "N findings across R rounds" as
+  hand arithmetic, and hand arithmetic over a generated table is what
+  put four wrong figures into this release line's published notes, so
+  this panel exists so a release note is a COPY rather than a
+  computation. The view's only `FROM` is `mart_review_rounds`, and
+  every panel in one report — or one `--snapshot` export — is computed
+  in a single DuckDB process over one materialized read of the corpus,
+  so the total and the rows it totals are one computation over one
+  input and cannot disagree: a record written to the ledger mid-run
+  reaches BOTH tables or neither, never one and not the other — though the
+  digest header beside these panels is a SEPARATE read outside that pin,
+  taken before it in a report and after it in a `--snapshot`, so header
+  and panels can still describe the corpus a moment apart. (Both halves
+  matter. The SQL
+  argument alone held while `canon report` ran one `duckdb` process per
+  mart against a live ledger, and a finding written between two of them
+  reached one panel and not the other — s43 round 6's blocker.
+  `crates/canon-report/src/query.rs`'s `PIN_CORPUS_SQL` is the other
+  half.)
+  `rounds_recorded` is `count(*)` over those rows, and that view holds a
+  row only for a round that RECORDED a finding, so
+  this column counts the rounds that FOUND something, never the rounds RUN;
+  canon has no record kind for a review round, so the rounds-RUN number
+  is not derivable from this corpus at all. `highest_round` is
+  `max(round)`, and it witnesses nothing about rounds: above
+  `rounds_recorded` it says only that some round number below it has no
+  row, and canon cannot say why — `round` is author-supplied and
+  nothing requires a change's rounds to be numbered from 1 or without
+  gaps, so a change whose only finding is labelled round 7 shows the
+  same gap six silent rounds would. Neither the gap nor its absence
+  evidences a round that RAN. Neither column is the rounds-RUN count —
+  `highest_round` is a round NUMBER, not a count, and `round` is
+  author-supplied. The splits sum the per-round `FILTER` counts, so
+  `severity_* = findings`, `disposition_* = findings` and
+  `introduced_by_sourced + introduced_by_unsourced = findings` all hold
+  at this grain too. `fix_of_fix` is `sum(fix_of_fix)` over a column
+  nothing records, and it means exactly what it means one panel up:
+  `fix_of_fix` bounds NOTHING — not from below, not from above: it
+  UNDER-counts, because an unsourced finding is never counted and a fix in
+  one change that breaks something first found while reviewing a DIFFERENT
+  change is not counted at all; it OVER-counts, because a `resolution_sha`
+  commit may carry work BEYOND the fix and every finding recording that
+  commit is counted regardless; and for any individual match the data
+  cannot say whether the fix or the other work in that commit introduced
+  the defect.
+  There is no defect rate, no quality score and no comparison between changes here:
+  a row is one change's review history, and `findings` moves with how
+  much reviewing happened rather than with the change.
+
+Two marts in `views.sql` are NOT report panels and are not exported by
+`--snapshot`: `mart_records_by_kind` and `mart_session_run_handoff`.
+Read them with DuckDB directly against `views.sql`.
+
+- **Run observability** (`mart_run_observability`) — one row per folded
+  `run_id`, appended as the tenth report/snapshot table after the established
+  nine tables. It reports lifecycle identifiers/status/timestamps, latency
+  only when both timestamps exist, event and label counts, child-run count,
+  guidance count, lineage provider/model, and token/cost source totals. These
+  are bounded observations and proxies: event counts do not infer tool calls,
+  retries, or human interventions, and no field claims guidance caused an
+  outcome. `directive_event_count` and `guidance_count` are counts only;
+  directive and guidance text is never emitted. `*_unknown` columns explicitly
+  expose missing joins/coverage, including missing session/project/task/lineage,
+  end timestamps, event times, costs, and guidance. Workspace absolute paths
+  and verbatim directives/guidance are intentionally omitted. The adapter
+  contract is strict read-only validation; this panel does not execute
+  adapters or enforce provider sandbox capabilities. Privacy-safe omission of
+  paths and directive/guidance text is part of the current semantics.
+
+## What this skill does NOT cover
+
+- The underlying view layer that computes the marts — see `canon-storage`.
+- `canon gate`'s evidence-gated checkbox flip / trust ladder — see
+  `canon-gate`. The trust-matrix and scope-status panels READ the same
+  corpus `canon gate check` validates but never gate or flip anything.
+- Strategy distillation/promotion — see `canon-learn`; the role-memory and
+  flywheel panels are read-only views over that store.
+- Authoring subjects and their status lifecycle — see `canon-subject`; the
+  subjects panel is the read-only rollup over those records.

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

@@ -0,0 +1,123 @@
+# canon-retrieve
+
+`canon retrieve` surfaces a role's promoted strategy memory (see
+`canon-learn`) at task-dispatch time. It is a fail-soft, advisory-only
+read: it NEVER blocks a dispatch and NEVER gates reproducibility.
+
+## `canon retrieve --role <r> --regime <k> [--k <n>] [--repo <dir>] [--json]`
+
+Prints the top-`k` retrievable strategies stored for `regime_key = <k>`
+(active strategies plus backward-compatible legacy rows without a lifecycle;
+guardrails are just strategies distilled from a failure-polarity verdict),
+newest-distilled first, capped at `--k` (default 5). Demoted,
+quarantined, rejected, and rolled-back rows are not retrievable.
+
+```bash
+canon retrieve --role dev --regime dev/canon/join-spine/9c93d024b1a2
+canon retrieve --role dev --regime dev/canon/join-spine/9c93d024b1a2 --k 3 --json
+```
+
+- `--regime` is the FULL `regime_key` string
+  (`<role>/<repo>/<area>/<hash>`) — the same serialization the write side
+  produces.
+- Assembling `--regime` in a script or hook? Use `canon regime-key
+  --role <r> --repo <r> --area <a> --hash <h>`: it runs canon's ONE
+  canonical `regime_key` serializer and prints the validated key, so a
+  caller routes through the exact normalizer the write path uses instead
+  of a drifting shell slug. Exits `2` with empty stdout on a malformed
+  result (empty segment / bad `<hash>`) — a clean fail-soft branch for
+  `|| exit 0` callers.
+- `--role` MUST equal `--regime`'s leading segment — a mismatch is a
+  clean usage error, exit `2` (mirroring `canon gate check`'s
+  0-clean/1-red/2-usage convention), never a panic or a silently-ignored
+  mismatch.
+- `--repo` resolves through the same nearest-`canon.yaml`-ancestor walk
+  `canon context`/`canon format`/`canon gate` use. The resolved
+  `canon.yaml` `learn:` section names the store root (`.canon/learn` by
+  default); a repo with no `canon.yaml` still works, defaulting cleanly.
+
+**FAIL-SOFT, always exit `0`** once `--role`/`--regime` agree: a store
+outage, an empty/nonexistent store, or a malformed on-disk row all
+degrade to an empty guidance list — never a nonzero exit or an error a
+caller must handle.
+
+## The pre-dispatch hook (`scripts/canon-retrieve-pre-dispatch.sh`)
+
+A generic, fail-soft, advisory-only shell script that fires at a
+PreToolUse-equivalent point for a `task`-shaped dispatch (Claude Code's
+`Task` tool / Codex's equivalent). It reads the tool's `subagent_type`
+as `--role`, assembles `--regime` by routing its repo/area segments
+through `canon regime-key` (so it never re-derives the join key with a
+drifting shell slug), calls `canon retrieve --json`, and emits the
+result as a `PreToolUse` `hookSpecificOutput.additionalContext` JSON
+envelope on stdout — Claude Code's convention for surfacing advisory
+context without a permission decision. It NEVER blocks: a missing
+`canon`/`jq`, a non-`Task` tool call, or empty guidance are all silent
+no-ops, exit `0`.
+
+Segment sources and override env vars
+(`CANON_RETRIEVE_ROLE`/`CANON_RETRIEVE_AREA`/`CANON_RETRIEVE_HASH`/
+`CANON_RETRIEVE_REGIME`) are documented in the script's own header.
+
+### Wiring it
+
+Place the script wherever your repo keeps materialized hook scripts
+(e.g. `.claude/hooks/canon-retrieve-pre-dispatch.sh`), then register the
+hook-seam entry with `canon gate install-hooks`:
+
+```bash
+canon gate install-hooks --repo . --event PreToolUse \
+  --matcher Task --command "sh .claude/hooks/canon-retrieve-pre-dispatch.sh" \
+  --timeout 15
+```
+
+This merges the standard `{matcher, hooks: [{type: "command", command,
+timeout}]}` entry into BOTH `<repo>/.claude/settings.json` and
+`<repo>/.codex/hooks.json`, additive and idempotent — see the
+`canon-gate` skill for `install-hooks`'s full contract.
+
+## Replay vs. live retrieval
+
+A run manifest records `injected_guidance` — a full SNAPSHOT (each entry
+`{strategy_id, title, content}`) of what `canon retrieve` returned at
+dispatch time, visible in `--json` output. It is never a live pointer, so
+a later edit or demotion of the source strategy can never retroactively
+change what a manifest already recorded.
+
+- **New run:** dispatch calls `canon retrieve` (live), then records the
+  result into the run manifest's `injected_guidance`.
+- **Replay:** reuse the manifest's recorded `injected_guidance` UNCHANGED
+  — never a fresh `canon retrieve` call. A replay MUST read the stored
+  guidance, so a live store change after the original run (a strategy
+  added, edited, demoted, or removed) can never perturb the replay.
+
+`canon retrieve` and the pre-dispatch script work standalone today — a
+caller can print retrieved guidance with zero manifest integration.
+
+## Lifecycle and legacy limitations
+
+Retrieval is a read path, not an activation or evidence path. It serves only
+exact role/regime matches and excludes `quarantined`, `rejected`,
+`rolled_back`, and demoted strategies. Newly distilled strategies are
+quarantined by default and therefore do not appear until the paired evaluation
+and signed approval workflow in `canon-learn` activates them.
+
+Rows written before lifecycle tracking (`lifecycle: null`) remain readable for
+backward compatibility when they are not demoted. They have no current
+quarantine, paired-evaluation, or SSH-approval provenance; retrieval MUST NOT
+interpret them as proof of the signed workflow, upgrade them, or claim
+measured uplift. The repository currently has no published measured uplift
+result.
+
+Role/regime retrieval is exact and advisory, not similarity search or a
+quality guarantee. A live lookup is also not a replayable proof: dispatch
+manifests snapshot the returned `{strategy_id, title, content}` entries, and
+replay uses that snapshot rather than refreshing the store.
+
+## What this skill does NOT cover
+
+- Strategy distillation/promotion/demotion — see the `canon-learn`
+  skill.
+- `canon gate install-hooks`'s full contract — see the
+  `canon-gate` skill; this skill documents only the one entry it
+  installs for `canon retrieve`.