@journeykit/canon 0.7.0 → 0.8.0

package/dist/index.js

@@ -155,5 +155,10 @@ if (!binary) {
   console.error("  build from source: cargo build --release -p canon-cli");
   process.exit(1);
 }
-var result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
-process.exit(result.status ?? 1);
+var bundledSkills = join(cliDir, "dist", "skills");
+var checkoutSkills = join(workspaceRoot, "canon", "skills");
+var skillsSource = existsSync(join(bundledSkills, "SKILL.src.md")) ? bundledSkills : checkoutSkills;
+var result = spawnSync(binary, process.argv.slice(2), {
+  stdio: "inherit",
+  env: { ...process.env, CANON_SKILLS_SOURCE: skillsSource }
+});

package/dist/skills/SKILL.src.md

@@ -0,0 +1,46 @@
+---
+name: canon
+description: The provider-neutral Canon companion skill for agents using the canon CLI. Routes setup, authoring, validation, storage, ingestion, learning, retrieval, reporting, and provider-specific lazy references.
+---
+
+# Canon
+
+Use this single skill when working with Canon in a consumer repository. Canon's CLI remains explicitly modular; choose the command that matches the operation rather than asking an implicit router to guess.
+
+## Setup and provider projection
+
+```bash
+canon init
+canon skills install                         # detects .claude/.codex/.omp/.pi; if none exists, installs Claude+Codex
+canon skills install --providers=claude,codex,omp,pi
+canon skills check                           # read-only drift check
+canon skills doctor                          # diagnostics; never deletes user files
+```
+
+The canonical bundle is read-only. Claude receives
+`.claude/skills/canon/SKILL.md`; Codex receives the flattened
+`.codex/skills/canon.md`; OMP receives `.omp/skills/canon/SKILL.md`; and Pi
+receives `.pi/skills/canon/SKILL.md`. Every selected provider receives matching
+`reference/**` and `scripts/**` sidecars under its `canon` bundle. OMP and Pi
+projections are project-local passive skill bundles: the
+`scripts/canon-retrieve-pre-dispatch.sh` file is available as a sidecar, not
+installed as a native hook. Load only the reference needed for the current
+task. `canon/skills-dev` is a separate developer-only legacy source and is
+installed explicitly with `--source canon/skills-dev`.
+
+## Route by task
+
+- **Start product work / pin a durable unit:** read `reference/canon-subject.md`, then run `canon context` and `canon subject`.
+- **Write or reorganize `.feature` specs:** read `reference/canon-authoring.md` before editing; use the scaffold.
+- **Understand available fields/enums/policy bindings:** read `reference/canon-context.md` and `reference/canon-vocab.md`.
+- **Capture replayable run inputs / version prompts:** read `reference/canon-context.md`, then use `canon context-pack create|show|verify` and `canon prompt register|show` with explicit repository-relative JSON manifests.
+- **Validate or index specs:** read `reference/canon-fmt.md` and `reference/canon-inventory.md`.
+- **Run evidence gates, flip tasks, install hooks:** read `reference/canon-gate.md`.
+- **Ingest artifacts or sessions:** read `reference/canon-artifact-ingest.md`, `reference/canon-session-ingest.md`, or `reference/canon-plan-import.md`.
+- **Configure storage, policy, plugins, or strategy learning:** read `reference/canon-storage.md`, `reference/canon-policy.md`, `reference/canon-plugins.md`, or `reference/canon-learn.md`.
+- **Retrieve dispatch guidance:** read `reference/canon-retrieve.md` and load `scripts/canon-retrieve-pre-dispatch.sh` when wiring hooks.
+- **Read generated reports and dashboards:** read `reference/canon-report-dashboard.md`.
+
+## Safety contract
+
+`canon format --check`, `canon skills check`, and `canon gate check` are read-only. Do not hand-edit generated reports, provenance lines, locks, or task evidence. Inspect `canon context` before authoring typed artifacts, and treat every failure class as actionable evidence rather than bypassing the gate.

package/dist/skills/reference/canon-artifact-ingest.md

@@ -0,0 +1,72 @@
+# canon-artifact-ingest
+
+`canon ingest artifacts` turns a repo's canon-native ARTIFACTS — the
+outputs of review/divergence/task/handoff work — into the regime-keyed
+verdict trajectories that strategy memory and the reward gate consume
+(see `canon-learn`). One pass runs the four adapters, normalizes, derives
+verdicts, and writes idempotently.
+
+## `canon ingest artifacts [--repo <dir>] [--watch]`
+
+```bash
+canon ingest artifacts                # one pass over the repo's artifacts
+canon ingest artifacts --repo ../svc  # a specific repo
+canon ingest artifacts --watch        # poll loop
+```
+
+Source roots resolve from `canon.yaml`'s `artifacts.sources` config
+(`openspec_root`, ledger/divergence/handoff roots) — generic, never a
+hardcoded path; ordinarily the consumer repo's own roots. Unconfigured =
+no scan for that family.
+
+## The four adapters
+
+Each reads one artifact family and emits a normalized event keyed by that
+family's join key:
+
+- **`divergence`** — parity/divergence reports → verdict keyed by the
+  lane derived from the report's on-disk path.
+- **`ledger`** — review ledger records → verdict; the record's
+  trust-level tag (`@reviewed`/`@ratified`) rides through as a
+  passthrough `trust_level` field, not collapsed into one "success"
+  bucket. (The other three adapters carry no trust-level concept.)
+- **`openspec_task`** — `tasks.md` checkbox rows: a `- [ ]` → `- [x] … —
+  ✅ <evidence>` flip, or a `**DEFERRED**`/`**DROPPED**` rewrite, keyed by
+  `task_id` (`<change_id>#<n>`). The evidence string is parsed for a
+  mergeable PR / CI reference where present (CI-first).
+- **`handoff`** — handoff transitions, keyed by `handoff_id`.
+
+## Verdict derivation
+
+Verdict derivation is a pure function from a normalized event to an
+optional verdict `{role, polarity, becomes}`:
+
+- A matched mapping row → a verdict for that role.
+- No mapped row → NO verdict. A prose-only task flip, a deferred/dropped
+  task, or a handoff transition alone produces none — deliberate, not a
+  gap.
+
+## Idempotence — a re-ingest is a no-op
+
+Write-identity is content-digest based: the digest derives both the
+`regime_key` `<hash>` segment and the trajectory write-identity. Before
+writing, the driver does a regime-key existence check — a second ingest
+over an unchanged corpus re-derives the identical id and persists zero
+new trajectories (reported as `trajectories_skipped_duplicate`).
+
+## Reading a role's own verdict stream
+
+Verdicts persist regime-keyed (`<role>/<repo>/<area>/<hash>`), so a
+role-scoped agent reads only its own lane — the same regime namespacing
+`canon retrieve --role <r> --regime <k>` and `canon learn` query. This
+verdict stream is the evidence the reward gate scores when deciding
+promotion/demotion.
+
+## What this skill does NOT cover
+
+- Session/cost ingestion (`canon ingest sessions`) — a different
+  pipeline; see the `canon-session-ingest` skill.
+- Strategy promotion/demotion mechanics — see the `canon-learn` skill;
+  this skill only produces the verdict evidence promotion reads.
+- The `regime_key` grammar itself — see `canon-retrieve`, which derives
+  the same key via the `canon regime-key` serializer.

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

@@ -0,0 +1,155 @@
+# canon-authoring
+
+A `.feature` corpus is the join spine everything else in canon hangs
+off: `canon inventory sync` indexes it, `canon review`/`canon evidence`
+attest against it, `canon gate check` measures coverage over it. A
+corpus that is organized badly does not fail `canon format` — it
+produces a green gate that measures the wrong thing. This skill is the
+organizing rule.
+
+## Vocabulary
+
+| Term | Is | Is NOT |
+|---|---|---|
+| **area** | One bounded context of the product, a kebab noun (`checkout`, `world-map`, `dm`). The directory `area=<area>/`. | A sprint, a team, a theme ("experience", "quality"). |
+| **surface** | One screen, flow, or API a user or caller actually meets (`cart`, `place-lock`, `session-create`). Exactly ONE `.feature` file per surface. | A grab-bag ("misc", "experience", "review") — see anti-patterns. |
+| **scenario** | One observable behavior of that surface: a refusal, a transition, a boundary, a derived value, an idempotence property. Readable by someone who has never seen the code. | A function name, an implementation step, a rule about a document or a report. |
+| **`<area>.<surface>.<nn>`** | The scenario's durable id. Assigned once, never renumbered; gaps are fine. | A sort key you tidy up. |
+
+A `Feature:` title names the surface. If you cannot name the surface,
+you do not have one yet.
+
+## Lanes: what kind of requirement is this?
+
+Every scenario is one of a small set of lanes, tagged `@lane:<value>`:
+
+| Lane | The scenario is about | Attested by |
+|---|---|---|
+| `behavior` | What the product does — state, input, data, navigation, errors. The default. | A test or an observed run. |
+| `design` | How it looks and moves — tokens, spacing, motion, easing. | A design review. |
+| `architecture` | How the code is shaped — layering, ownership, error surfacing. | An architecture review. |
+| `process` | How the TEAM works — what a review report may claim, how acceptance is run, what a build must check. | Nothing in the product. |
+
+`process` rules are real, but they have no code surface and can never
+be `faithful` from a test. Keep them out of the coverage number:
+
+```yaml
+# .canon/policy.yaml
+spec_coverage:
+  require_evidence: true
+  scope: [building, verifying]
+  exclude_lanes: [process]
+```
+
+The base set comes from `canon.core`; a repo declares its own `lane`
+enum in `.canon/vocab/<id>/enums.yaml` to replace it (see
+`canon-vocab`). `canon context` shows the set in force. A value outside
+a declared set is refused at the scaffold and dropped, with a counted
+diagnostic, at `canon inventory sync`.
+
+**The test for a `behavior` scenario:** name the test or run that would
+attest it. If you can't, it is a `process` rule, or it is a gap — record
+the gap, do not write the scenario.
+
+## Subject pinning
+
+Every scenario belongs to a Subject (the durable product unit, see
+`canon-subject`). Write the Subject first, then pin with `--subject`;
+`canon inventory sync` carries the tag onto the index record and
+`spec_coverage.scope` filters on it. An unpinned scenario is invisible to
+a scoped gate.
+
+## The commands — and the one thing you never type
+
+```bash
+canon feature new checkout.cart --title "Cart"                       # once per surface
+canon scenario new checkout.cart.01 --title "Adding an item raises the count" \
+  --subject checkout-core --lane behavior                            # once per behavior
+canon format specs                                                   # clean?
+canon inventory sync                                                 # index it
+```
+
+- `--actor <id>` (or `CANON_ACTOR` in the environment) puts YOUR id on the
+  provenance line. Default is `canon-scaffold`.
+- **Never hand-type, move, or edit a `# canon:` line.** The scaffold
+  writes it directly above the scenario's tags:
+
+  ```gherkin
+    # canon: {"schema":1,"at":"2026-09-16T10:02:11Z","actor":{"agent_id":"Main"}}
+    @subject:checkout-core
+    @lane:behavior
+    @checkout.cart.01
+    Scenario: Adding an item raises the count
+      Given an empty cart
+      When one item is added
+      Then the count reads 1
+  ```
+
+  A line directly UNDER the header (older corpora) is also accepted.
+  Anywhere else — separated by a blank line, above `Feature:` with
+  scenario tags in between — is `missing-provenance`, and the whole
+  root's sync aborts.
+- Steps are yours to write; the scaffold's `Given a step` is a
+  placeholder, not a spec.
+
+## Anti-patterns, by name
+
+- **The grab-bag surface.** One `experience.feature` holding pointer
+  capture, i18n fallback, a compiler tag rule, and "the review report
+  must not claim video quality". Four surfaces and a process rule. Split
+  by what the user meets; move the rule to `lane:process`.
+- **A Then about a document.** "Then the report distinguishes X from Y."
+  The product has no report. `lane:process`, or `policy.yaml`.
+- **A Feature title that is a theme.** "Fidelity of the original
+  experience" names no surface. Name the screen.
+- **Hand-stamped provenance.** Eighty lines with one timestamp and the
+  same `agent_id`. Use `canon scenario new --actor`.
+- **Coverage by splitting.** One behavior as two scenarios so two rows go
+  green. One behavior, one id.
+- **Runner tags as classification.** `@design`, `@p2`, `@wip` are
+  invisible to canon — they index nothing. Only `@lane:` and `@subject:`
+  are read; any other `@name:value` namespace is counted as a diagnostic
+  at sync so you can see it was dropped.
+
+## Worked example
+
+```
+specs/features/kind=feature/area=checkout/
+  cart.feature        # surface: the cart screen
+  payment.feature     # surface: the payment step
+```
+
+```gherkin
+Feature: Cart
+  # canon: {"schema":1,"at":"2026-09-16T10:02:11Z","actor":{"agent_id":"Main"}}
+
+  # canon: {"schema":1,"at":"2026-09-16T10:02:11Z","actor":{"agent_id":"Main"}}
+  @subject:checkout-core
+  @lane:behavior
+  @checkout.cart.01
+  Scenario: Adding an item raises the count
+    Given an empty cart
+    When one item is added
+    Then the count reads 1
+
+  # canon: {"schema":1,"at":"2026-09-16T10:02:40Z","actor":{"agent_id":"Main"}}
+  @subject:checkout-core
+  @lane:design
+  @checkout.cart.02
+  Scenario: The count badge uses the accent token and a 120ms ease-out
+    Given a cart with one item
+    When a second item is added
+    Then the badge animates over 120ms with ease-out in the accent color
+
+  # canon: {"schema":1,"at":"2026-09-16T10:03:02Z","actor":{"agent_id":"Main"}}
+  @subject:checkout-core
+  @lane:process
+  @checkout.cart.03
+  Scenario: A cart review names the device it was run on
+    Given a cart design review
+    When the report is written
+    Then it names the device and OS the review ran on
+```
+
+`.03` is excluded from coverage by `exclude_lanes: [process]`; `.01` is
+attested by a test, `.02` by a design review.

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

@@ -0,0 +1,137 @@
+# canon-context
+
+`canon context` is a capability QUERY over the same schema/policy/
+vocabulary registry `canon format`/`canon gate` validate against — never
+validation itself. It answers "what CAN I author in this repo, and how?":
+record kinds + their envelope fields, enum domains, join-key grammars,
+partition layout, policy-derived evidence requirements, the typed
+authoring vocabulary, and the CEL binding surface — folded into one
+deterministic authoring surface.
+
+## `canon context [--repo <dir>] [--json]`
+
+```bash
+canon context                 # compact human outline (prompt-injectable)
+canon context --json          # the full machine-readable surface
+canon context --repo ../other # resolve a specific repo's surface
+```
+
+## Reproducible context packs and prompt bundles
+
+Use an explicit, repository-relative JSON manifest when a run needs a
+replayable snapshot. The manifest selects files; Canon copies their bytes into
+an immutable content-addressed registry and records only metadata and digests
+in the pack manifest.
+
+```bash
+canon context-pack create --manifest .canon/context-manifest.json
+canon context-pack create --manifest .canon/context-manifest.json --repo ../my-repo --json
+canon context-pack show sha256:<pack-digest> --repo . --json
+canon context-pack verify sha256:<pack-digest>
+```
+
+`create` prints only the pack id by default, so captured content is never
+written to concise terminal output. `--json` prints the pack manifest,
+including selected-path metadata and content digests. `show` verifies the
+manifest and immutable content objects before returning it; `verify` exits
+nonzero when the pack is missing, stale, or tampered. Manifest paths must be
+relative to the resolved repo, remain inside it, and contain no symlink;
+missing or unsafe paths are rejected by the context-pack module.
+
+## Provider-neutral adapter responses
+
+An execution provider may return a versioned response envelope for Canon to
+validate. Validation is read-only: `canon` never starts a provider, interprets
+provider-specific extension payloads, or enforces declared capabilities.
+
+```bash
+canon adapter validate --response response.json
+canon adapter validate --response response.json --repo . --json
+```
+
+The envelope has `protocol_version: 1`, required `run_id`, `provider`,
+`model`, and `context_pack_id`, a closed status vocabulary
+(`succeeded`/`failed`/`aborted`), and strict filesystem/network/secrets
+capability vocabularies. Evidence references are safe, relative references
+with `sha256:<64-hex>` digests. Telemetry timestamps must be RFC3339 with
+`ended_at >= started_at`, and counts/cost are nonnegative.
+
+Core fields are closed and unknown fields are rejected. Provider-specific JSON
+belongs only under opaque `extensions`; successful JSON output contains the
+normalized core summary and extension key names, never extension payloads.
+`--repo` can verify the referenced context pack; file-only validation reports
+`context_join_verified: null`. A valid declaration is not a sandbox:
+providers MUST enforce filesystem, network, and secret capabilities before
+execution.
+
+Version prompt inputs separately when several runs should share the same
+prompt files:
+
+```bash
+canon prompt register --name reviewer --version v1 \
+  --manifest .canon/reviewer-prompt.json
+canon prompt show --name reviewer --version v1 --json
+```
+
+Prompt registration uses the same immutable content registry. `prompt show`
+verifies the selected bundle and returns its metadata/digests; neither concise
+output form includes captured prompt bytes.
+
+- **A capability query, never validation:** `canon context` ALWAYS exits
+  `0` with the full surface — even when `canon format --check` or
+  `canon gate` would report diagnostics against the same repo. It reads
+  only the schema/policy/vocabulary registry, never the corpus or the
+  evidence ledger.
+- `--repo` resolves through the same nearest-`canon.yaml`-ancestor walk
+  `canon format`/`canon gate`/`canon retrieve` use: omitted or `.` walks up
+  from cwd to the project root; any other explicit dir is used as-is.
+- `--json` renders the full surface; the default renders a compact per-
+  section outline. Both project from the identical resolution (byte-stable
+  across runs).
+
+## The surface sections
+
+- **`kinds`** — each record kind's `{schema_version, envelope_fields,
+  partition}`.
+- **`enums`** — each enum domain's members (verdicts, statuses, lanes,
+  roles, polarity, …).
+- **`joinKeys`** — the join-spine grammar string per key (`regime_key`,
+  `session_id`, `task_id`, …).
+- **`policy`** — the resolved `policy.yaml`-derived evidence/trust
+  requirements per kind.
+- **`vocab`** — the typed authoring vocabulary (directive/enum/evidence-
+  kind index) + its content-hash version.
+- **`cel`** — the per-kind CEL binding surface: the bindable
+  `record.<field>` names + types and the callable function allowlist a
+  `policy.yaml` `applies_when:`/predicate may reference. The agent-facing
+  answer to "what can a CEL predicate for this kind reference?"
+
+## Single source of truth
+
+`canon context` never re-derives a schema/policy/enum list of its own — it
+resolves through the same shared schema, policy, and vocabulary loaders
+the validators use. A schema edit propagates to `canon context`'s output
+AND `canon format`'s diagnostics from one edit site, never two.
+
+## Reading an "expected one of: …" validator error
+
+When `canon format --check` rejects an out-of-domain enum value it emits:
+
+```
+`not-a-real-kind` is not a valid value for `kind` of `run` (expected one of: run, review, divergence, …)
+```
+
+The `expected one of:` member list is the SAME enum domain `canon context
+--json`'s `enums.<field>` reports for that kind — so to fix the artifact,
+pick a member `canon context` lists. Both read the member list off the
+same schema, no hand-maintained second copy.
+
+## What this skill does NOT cover
+
+- `canon format --check`'s full violation taxonomy — see `canon-fmt`;
+  this skill only covers reading its enum diagnostic against the surface.
+- Authoring a typed task atom / handoff body — see
+  `canon-vocab`; `canon context`'s `vocab`/`cel` sections
+  tell you what's declarable, not how to declare it.
+- `policy.yaml` CEL authoring semantics — see `canon-policy`; this skill
+  only surfaces the bindable identifier/function set per kind.

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

@@ -0,0 +1,43 @@
+# canon-fmt
+
+`canon format --check` is canon's read-only format validator over a
+consumer-repo artifact corpus: ledger records (run/drill/review/clear/
+code-review/design-review), divergence events (manifest/review/
+remediation), `features/`, `inventory/`, and `policy.yaml`. It never
+rewrites or mutates the corpus — it only validates and reports.
+
+## Running
+
+```bash
+canon format --check <corpus-root>   # e.g. a consumer repo's spec/
+```
+
+Read-only, always. Exits nonzero if any violation is found, and prints
+a report grouped by failure class in this fixed order:
+
+| Failure class | Meaning | Fix |
+|---|---|---|
+| `layout-grammar` | Wrong Hive path shape — a `features/`/`inventory/` file not under a `kind=<kind>/area=<area>/` prefix, a wrong leaf filename, or `assets.lock`'s ad-hoc format. | Move the file under the correct `kind=…/area=…/` prefix with the expected leaf name. |
+| `missing-envelope` | A YAML file (`inventory/`, `policy.yaml`) has no top-level `schema`/`kind`/`at`/`actor` keys. | Add the four envelope keys at the top level. |
+| `missing-provenance` | A `.feature` file's `Feature:`/`Scenario:` header has no `# canon: {...}` comment either directly above it (with its tags, no blank line) or directly below it. | Use `canon scenario new` / `canon feature new`, which stamp it; never hand-type the line. See `canon-authoring`. |
+| `missing-actor` | No structured `actor` object — a bare `by` string, or absent. | Replace `by: <name>` with a structured `actor` object. |
+| `unspecified-evidence` | A ledger `run`/`drill` record's `evidence` field is absent or an empty, untyped array. | Add a typed `evidence` array. |
+| `free-text-ref` | `upstream_ref`/`port_ref` has a segment not matching `<file>#<symbol>[:<a>-<b>]`. | Rewrite the ref into the `<file>#<symbol>[:<a>-<b>]` grammar. |
+| `joined-ref` | `upstream_ref`/`port_ref` is `;`- or `,`-joined but not split into a structured `refs` array. | Split into a `refs:` array, one entry per ref. |
+| `abbreviated-sha` | `app_sha`/`harness_sha` is present but shorter than the full 40-hex form. | Use the full 40-character SHA. |
+| `one-way-backref` | A divergence review event's `ledger_ref` has no reciprocal `divergence_refs` entry on the ledger record it names. | Add the matching `divergence_refs` entry to that ledger record. |
+| `missing-join-identity` | Corpus-wide, one line: no ledger record carries `change_id`/`task_id`. | Standing note only — new records carry these going forward; historical backfill is out of scope. |
+
+Every class is a stable string, safe to grep/diff across runs.
+
+## What it does NOT do
+
+- **Rewrite anything.** It only validates and reports; a one-shot
+  migration of an existing corpus is a separate, per-repo concern.
+- **Backfill `change_id`/`task_id` on historical records.** Both stay
+  absent on records that predate the schema; `missing-join-identity` is
+  a standing corpus-level note, not a per-record defect it fixes.
+- **Guess a `{file, symbol}` from free prose.** A non-conforming ref is
+  reported as `free-text-ref` exactly as found, never fabricated.
+- **Touch a consumer repo's CI gates.** Conforming a corpus and
+  reconciling its own tooling is that repo's own operational step.

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

@@ -0,0 +1,199 @@
+# canon-gate
+
+`canon gate` is canon's trust spine: a two-layer evidence gate over a
+repo's artifact corpus. It answers two DIFFERENT questions per artifact —
+"does required evidence exist" (coverage) and "did the evidence pass, by
+whom, how stale" (verdict-ledger) — never collapsing them into one
+"done" boolean.
+
+## The trust ladder
+
+Each artifact climbs a trust ladder as evidence accrues: an unreviewed
+record is weaker than a reviewed one, which is weaker than a ratified
+one. `policy.yaml` sets a `trust_required` level per artifact class; the
+release-scoped check (below) enforces it. A human-only `flagged` overlay
+overrides the ladder — a flagged artifact is never green regardless of
+evidence. (Author `policy.yaml`'s trust/staleness fields via `canon-policy`.)
+
+## The eight failure classes
+
+Every violation carries one of these stable, grep-able strings:
+
+| Class | Meaning |
+|---|---|
+| `uncovered-cell` | Either a policy-required evidence cell (role × artifact) with no matching record, or — with `spec_coverage` enabled — a spec scenario that is unimplemented or mismatched. The detail string distinguishes them. Coverage means "a test exists", not "a test passed": even a `Divergent` verdict satisfies the role-cell form. |
+| `unreviewed-promotion` | An artifact tagged `reviewed` has no matching ledger review record. |
+| `trust-below-required` | Achieved trust level is below `policy.yaml`'s `trust_required` for its class — RELEASE-scoped only (`canon gate check --release`); never fires on an ordinary run. |
+| `stale-evidence` | A passing record degraded to stale: its declared surface changed since its `evidence_sha`, or HEAD moved past `staleness.max_commits_behind`. Only degrades an already-green record. |
+| `malformed-evidence` | A candidate record doesn't parse, is misfiled, or carries an unparseable interim tag. Malformed evidence is no evidence. |
+| `flagged` | The human-only `flagged` overlay is set — never green regardless of passing evidence. |
+| `unevidenced-flip` | `canon gate task <task_id>` was asked to flip a checkbox with no matching, non-`Divergent` evidence record. |
+| `fabricated-evidence` | An evidence note contains a blocklisted marker (`"would pass"`, `"TBD"`, `"n/a"`) or a bare `verified` claim with no attached command result. |
+
+## `canon gate check [--repo <dir>] [--release]`
+
+Assembles coverage + ledger + staleness + the always-on trust-ladder
+check, plus the opt-in spec-coverage check, over the resolved repo's
+corpus and runs them, printing every violation grouped by failure class.
+`--release` additionally engages the release-scoped
+`trust-below-required` check; the trust-ladder check is never dropped
+when `--release` is passed.
+
+```bash
+canon gate check --repo .            # ordinary evaluation
+canon gate check --repo . --release  # + trust-below-required
+```
+
+Exit `0` clean, `1` gate-red (any violation), `2` usage/load failure
+(unreadable ledger, corrupt `canon.yaml`). `--repo` (or its omission)
+resolves through the nearest-ancestor `canon.yaml` walk, so it reads the
+repo ROOT's `.canon/policy.yaml` and `.canon/ledger` from any subdirectory.
+
+### The spec-derived worklist (`spec_coverage`, opt-in)
+
+Coverage groups the EVIDENCE corpus, so it can only ever enumerate
+artifacts that already have evidence. A `.feature` scenario nobody has
+attested to appears in no group and is invisible to it. `spec_coverage`
+adds the other direction: it starts from the Scenario corpus
+`canon inventory sync` materializes and left-joins evidence onto it, so
+an unimplemented or mismatched spec becomes a reported violation.
+
+```yaml
+# .canon/policy.yaml — ABSENT by default; absent means zero violations
+spec_coverage:
+  require_evidence: true
+  scope: [building, verifying]   # optional; omit for the whole corpus
+```
+
+- **Unimplemented** — no `EvidenceRecord` carries the scenario's
+  `(project_id, scenario_id)`. Author one with
+  `canon evidence add --scenario-id <id> --project-id <root-id>`; both
+  flags are required together, because two spec roots may carry the same
+  scenario id.
+- **Mismatched** — the folded divergence state is `open`,
+  `still-divergent`, or `resolved-invalid` (a resolution whose app sha
+  has moved), or the latest ledger verdict is `divergent`.
+- **`scope`** narrows blocking to scenarios whose `@subject:<id>` tag
+  links them to a Subject in one of the named statuses. With a `scope`
+  set, an untagged scenario is out of scope; with `scope` omitted, every
+  scenario is in scope. A tag naming no Subject record is reported as a
+  dangling link, never silently skipped.
+
+Two refusals rather than a silent pass, both surfacing as
+`uncovered-cell` on the subject `spec_coverage`:
+
+- A **malformed section** (unknown key, unknown `scope` status) refuses
+  at check time. It is never treated as absent — a typo must not be
+  silently equivalent to not opting in.
+- A **corpus kind routed off the gate's rung** (`scenario`,
+  `divergence`, or `subject` sent anywhere but `local`) refuses, because
+  the gate reads one tier and would otherwise pass by seeing nothing.
+
+Malformed rows in those three kinds do NOT surface as
+`malformed-evidence`; they are kept off the evidence violation set on
+purpose, so enabling nothing changes no existing verdict.
+
+## Effect-aware risk approvals (`risk_tiers`)
+
+`risk_tiers` is absent by default and remains a no-op when absent. When it
+is present, `canon gate check` selects the highest-ranked configured tier
+whose current evidence binding matches a path or exact `effect:<kebab-slug>`.
+The current generation is selected deterministically; approvals from an
+older `evidence_sha`, a non-`faithful` verdict, or an unverified attestation
+never count. A required tier also fails closed when the current record has
+no usable `surface_ref`/effect binding, so a caller cannot suppress a
+configured rule by declaring a safe path.
+
+`canon evidence add --surface-ref src/auth/login.rs` (repeatable) or
+`--surface-ref effect:secret-access` persists an explicitly validated
+binding. This is still attestation input, not proof of the changed paths;
+run/diff metadata is authoritative when available, and an unavailable
+binding is a gate violation rather than a clean result.
+
+Approval identity is separate from attestation text. `--approval-by` is
+accepted as a verified approval only when it equals a non-empty
+`CANON_ACTOR` environment identity and `--approval-role human` is supplied.
+The record persists that verification bit for replay; arbitrary caller
+strings, empty identities, and `agent` roles never satisfy a risk tier.
+Malformed `risk_tiers` sections produce a stable `uncovered-cell` policy
+violation (`risk_tiers policy-invalid: ...`) instead of degrading to an
+empty clean map.
+
+## `canon gate task <task_id> [--repo <dir>]`
+
+The evidence-gated task checkbox flip. Resolves `<task_id>`
+(`<change_id>#<n>`) through `canon.yaml`'s `plans:` sources — the first
+configured dialect whose `PlanWriteBack` locates the task's document
+wins, so the flip is plan-dialect agnostic (`openspec` change dirs,
+`superpowers` plan docs). A repo with no `plans:` section falls back to
+the compat default `[{ dialect: openspec, root: <repo> }]`; no source
+locating the task at all is a loud failure naming every source consulted.
+It requires
+a matching non-`Divergent` evidence record, and flips `- [ ]` → `- [x]`
+with an appended evidence note ONLY on a clean check. Every other path —
+missing evidence, a `Divergent` verdict, a fabricated note — leaves the
+row byte-unchanged and exits `1` with the blocking violation on stderr.
+An already-`[x]` row is an idempotent no-op (exit `0`). An unknown
+`task_id` is reported (exit `1`).
+
+```bash
+canon gate task my-change#5.2 --repo .
+```
+
+This is canon's own authority for the checkbox grammar — always flip
+through `canon gate task`, never by hand.
+
+## `canon gate promote [--repo <dir>] [--dry-run]`
+
+Staging → committed: every well-formed record under
+`.canon/ledger/_staging/` is re-validated with the SAME checks the gate
+applies, assigned a monotonic per-(role, surface) `run_seq` (gap-free
+within one invocation, continuing from the committed max), and moved into
+the committed ledger. A malformed or unpartitionable candidate is refused
+— exit `1`, no `run_seq` consumed, the file left in place. `--dry-run`
+prints the plan (target path + assigned `run_seq` per candidate) without
+writing or deleting.
+
+```bash
+canon gate promote --repo .            # land every staged candidate
+canon gate promote --repo . --dry-run  # preview only
+```
+
+## `canon gate install-hooks [--repo] [--event] [--matcher] [--command] [--timeout]`
+
+Idempotent, diff-only hook-seam installation: merges one
+`{matcher?, hooks: [{type: "command", command, timeout}]}` entry into
+BOTH `<repo>/.claude/settings.json` and `<repo>/.codex/hooks.json` —
+additive only, never touching an existing entry in the same matcher
+group. Running it twice with no manual edits between reports "no diff"
+and writes nothing. When neither file already carries a `canon
+gate`-invoking command, it ALSO emits
+`<repo>/.canon/scripts/canon-gate-pre-commit.sh` (advisory by default — set
+`CANON_GATE_ADVISORY=0` to make it block the commit on a failing gate).
+
+```bash
+canon gate install-hooks --repo .
+# non-default wiring:
+canon gate install-hooks --repo . --event PreToolUse --matcher Edit --command "canon gate check" --timeout 30
+```
+
+Prefer this over hand-editing `settings.json`/`hooks.json`.
+
+## `canon gate selftest`
+
+Runs the shipped fixture corpus — one fixture per failure class, each a
+deliberately broken corpus proving that class fires and ONLY that class
+(both under-detection and over-triggering fail the run). Takes no
+`--repo`; self-contained. Run it before trusting any other `canon gate
+check` run's green.
+
+```bash
+canon gate selftest
+```
+
+## Reading a violation
+
+Every printed line is `<failure-class> <subject> — <detail>`. `<subject>`
+is the artifact's own join identity (`task_id` preferred, then
+`scenario_id`, then `run_id`) — grep the ledger or `tasks.md` for it
+directly, never guess.