@journeykit/canon 0.6.0 → 0.8.0

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.

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

@@ -0,0 +1,102 @@
+# canon-inventory
+
+`canon inventory sync` is the FIRST stage of canon's unified spec loop:
+it turns a hand-authored, `canon format`-validated `.feature` corpus into
+the scenario ledger-INDEX records every downstream stage joins against.
+
+## The unified loop
+
+```
+author .feature corpus  →  canon format --check (validate)
+        │
+        ▼
+canon inventory sync            # THIS skill — materializes scenario index records
+        │
+        ▼
+canon review add                # attests a review — see canon-inventory downstream / canon-gate
+canon divergence {stage,promote,resolve,defer,status}   # tracks/resolves a divergence
+canon gate check [--release]    # trust-ladder / staleness / coverage — see canon-gate
+        │
+        ▼
+canon ingest artifacts          # with artifacts.native_records: true in canon.yaml —
+                                # feeds review/divergence verdicts into the flywheel
+                                # (see canon-artifact-ingest)
+```
+
+Every stage after `sync` joins on the SAME `(project_id, scenario_id)`
+pair `sync` materializes — one identity scheme, no second one.
+
+## `canon inventory sync [--repo <dir>] [--spec-root <dir>]`
+
+```bash
+canon inventory sync                        # every canon.yaml specs.roots[] entry
+canon inventory sync --repo ../svc          # a specific repo
+canon inventory sync --spec-root ./specs    # ad hoc: ignore canon.yaml entirely
+```
+
+Per configured root, in order:
+
+1. **Validate** — runs `canon format --check` over the root. ANY violation
+   (missing provenance, layout-grammar, …) ABORTS THE WHOLE ROOT: zero
+   records written for it, the violation(s) reported. Never a partial sync.
+2. **Scan** — walks `<root>/features/**/*.feature`, pairing each
+   `@<area>.<surface>.<nn>` tag with its header label as `title` and a
+   `source_digest` (sha256 over the raw `.feature` bytes). `@subject:<id>`
+   → `subject_id`, `@lane:<v>` → `lane` (first tag wins; a second, a
+   malformed value, or a value outside a declared `lane` enum is dropped
+   with a counted, non-fatal diagnostic). Any other `@name:value`
+   namespace is counted as a diagnostic so a dropped classification is
+   visible; plain tags (`@p2`) are ignored. The index derives from the
+   `.feature` corpus alone. See `canon-authoring` for the organizing rule.
+3. **Materialize** — upserts ONE scenario index record per
+   `(project_id, scenario_id)` via the append-only git-tier write.
+   Logically idempotent: an unchanged `source_digest` is a no-op; a
+   changed `.feature` file appends exactly one new record. A `.feature`
+   edit re-materializes every scenario in that file (file granularity).
+4. **Duplicate guard** — a `scenario_id` scanned more than once WITHIN
+   one root's corpus aborts that root (0 writes), reported as a sync
+   error. Two DIFFERENT roots sharing a `scenario_id` stay distinct —
+   `project_id` isolates them.
+
+The scenario index shape is deliberately general: `title` +
+`source_digest`, nothing else. It carries no coverage field — coverage
+stays `canon gate check`'s own authority (see `canon-gate`).
+
+## `specs.roots[]` config (`canon.yaml`)
+
+```yaml
+specs:
+  roots:
+    - id: app-a          # STABLE LITERAL — never the checkout directory name
+      root: apps/a/specs
+    - id: app-b
+      root: apps/b/specs
+```
+
+- **Absent `specs:` key** → the single default root `{id: root, root: specs}`.
+- **Present `specs:` with an empty/missing `roots[]`** → fails LOUD; a
+  present-but-incomplete config never silently resolves to zero roots.
+- **A malformed entry** (missing `id`, `roots` not a list, `id` not a
+  valid project id) → fails LOUD, never a silent fallback to the default.
+- `--spec-root <dir>` bypasses `specs.roots[]` entirely and syncs
+  exactly that one directory under the same stable `root` id the
+  absent-`specs:` default uses.
+
+## Sync-abort causes
+
+- **A `canon format --check` validation violation** in the root's corpus →
+  whole root aborts, 0 writes, violations reported.
+- **A duplicate `scenario_id`** within one root → that root aborts, 0
+  writes, reported as a sync error (a distinct lane from fmt violations).
+
+## How the index feeds the rest
+
+- **Review** — `canon review add` attests a verdict against a synced
+  scenario. (See `canon-inventory` downstream commands and each command's `--help`.)
+- **Divergence** — `canon divergence {stage,promote,resolve,defer,status}`
+  tracks/resolves divergences against synced scenarios.
+- **Gate** — `canon gate check` enforces trust-ladder / staleness /
+  coverage over the corpus (see `canon-gate`).
+- **Ingest** — `canon ingest artifacts` with `artifacts.native_records:
+  true` in `canon.yaml` feeds review/divergence verdicts into the
+  reward flywheel (see `canon-artifact-ingest`).

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

@@ -0,0 +1,245 @@
+# canon-learn
+
+canon's role-namespaced strategy memory turns accumulated verdict
+trajectories into retrievable, promotable insights. Two tiers:
+
+- **Trajectories (warm, local).** Raw verdict-keyed rows under
+  `<repo>/.canon/learn/trajectories/`, written by ingest. Rebuildable,
+  gitignored, never hand-committed.
+- **Strategies (durable, git).** Distilled, reviewable
+  `<repo>/.canon/strategies/<role>/<id>.md` files — the tier a promotion
+  writes into and a demotion soft-flags.
+
+## Rebuilding strategy memory
+
+Strategy memory is re-derived from the current trajectory set as part of
+`canon ingest artifacts` (see `canon-artifact-ingest`): after it
+persists a repo's verdict trajectories, it re-derives the distilled
+strategies. This is NON-DESTRUCTIVE — a rebuild never drops a
+hand-promoted strategy the trajectory rows don't touch. There is no
+standalone `canon learn` rebuild command; the only subcommand is
+`promote`.
+
+# `canon learn promote <strategy_id> [--repo <dir>] [--evaluation <path> --approval <path>] [--signature <path>] [--dry-run]`
+
+The production activation path is a signed, paired-evaluation workflow:
+
+1. Run `canon ingest artifacts`. Ingest resolves covering verdicts and rebuilds
+   newly distilled strategies as `lifecycle: quarantined`.
+2. Check eligibility with the configured `occurrence` or `crn` gate. This is
+   only a prerequisite; occurrence alone MUST NOT activate a strategy.
+3. An honest external evaluator writes a `PromotionEvaluation` JSON bundle.
+   It MUST bind the candidate's id, version, quarantined lifecycle, strategy
+   digest, source trajectory ids, baseline and candidate result digests, and
+   non-empty corpus/evaluator/context/policy/model/tool provenance.
+4. Require paired evidence: baseline and candidate digest arrays MUST be
+   non-empty, equal-length, disjoint, and duplicate-free. The evaluation's
+   finite `paired_metrics` MUST include `pairs`, `uplift`, and `regressions`;
+   `pairs` MUST equal the array length, `uplift` MUST be strictly positive,
+   `regressions` MUST be zero, `passed` MUST match those derived checks, and
+   `decision` MUST be `pass`, `promote`, or `approved`. Missing or unknown
+   metrics are rejected; the repository currently publishes **no measured
+   uplift result**, so this command is not evidence that retrieval improves
+   agent outcomes.
+5. Produce the unsigned approval payload:
+
+   ```bash
+   canon learn approve <strategy_id> --evaluation evaluation.json \
+     --principal alice --repo .
+   # `request` is an exact alias:
+   canon learn request <strategy_id> --evaluation evaluation.json \
+     --principal alice --repo .
+   ```
+
+   The JSON output contains the evaluation digest, RFC3339 `approved_at`,
+   subject `strategy:<strategy_id>`, namespace
+   `canon-learning-approval-v1`, and `payload_hex`. `approve`/`request` never
+   read a private key and never set `verified`.
+6. Decode `payload_hex` to the exact canonical JSON bytes. The signed object
+   is:
+
+   ```json
+   {
+     "namespace": "canon-learning-approval-v1",
+     "subject": "strategy:<strategy_id>",
+     "project": null,
+     "artifact_sha": "<evaluation_digest>",
+     "run_id": null,
+     "surface": [],
+     "effects": [],
+     "actor": "<principal>",
+     "timestamp": "<RFC3339 nanosecond timestamp>"
+   }
+   ```
+
+   For rollback, the corresponding signed object uses subject
+   `strategy:<id>:rollback:<sha256(reason)>`, `artifact_sha` equal to that
+   reason digest, and the rollback actor/timestamp. Sign the decoded bytes
+   externally with an SSH key using the `canon-learning-approval-v1`
+   namespace (for example, `ssh-keygen -Y sign -n canon-learning-approval-v1
+   -f <private-key>`). Put the armored detached signature in
+   `PromotionApproval.signature` and set `signer_key` to the same principal.
+   The approval JSON has exactly these fields: `schema_version`,
+   `candidate_strategy_id`, `evaluation_digest`, `approver_identity`,
+   `approver_role` (`human`), `verified` (non-authoritative display data),
+   `approved_at`, optional `signature`, optional `signer_key`, and
+   `integrity_digest`.
+7. Configure the verifier in the repository policy:
+
+   ```yaml
+   approval:
+     allowed_signers: .canon/allowed_signers
+   ```
+
+   The path is policy-pinned (relative paths resolve from the repository).
+   The verifier runs `ssh-keygen -Y verify` against that file; an absent,
+   unreadable, or non-matching signer fails closed. A detached signature is
+   authentication of the configured principal, not proof that the principal
+   is a human or is otherwise authorized outside this policy.
+8. Activate only with both evidence files:
+
+   ```bash
+   canon learn promote <strategy_id> --repo . \
+     --evaluation evaluation.json --approval approval.json
+   # Or attach an armored signature file and recompute the approval digest:
+   canon learn promote <strategy_id> --repo . \
+     --evaluation evaluation.json --approval approval.json \
+     --signature approval.sig
+   ```
+
+   `--evaluation` and `--approval` MUST be supplied together. A quarantined
+   candidate without valid paired evaluation, policy-pinned SSH verification,
+   and human approval remains quarantined. `--dry-run` previews the render but
+   does not activate or write.
+
+The command resolves the repo via the nearest-`canon.yaml`-ancestor walk,
+evaluates the role gate before any write, and runs advisory lints
+(content-length ceiling and literal-absolute-path rejection). There is no
+`--force`. Promotion re-renders the whole git-tier file with YAML front matter
+(`status`, `regime_key`, `role`, `title`, `source_trajectory_ids`,
+`recorded_at`) plus evaluation and approval digests; a re-promote does not
+preserve manual edits.
+
+An unknown `strategy_id` fails nonzero. A candidate's lifecycle defaults to
+`quarantined` when newly distilled and quarantine is excluded from retrieval.
+The old public writer is retained only for already-`active` items; it is not a
+way to activate new or legacy candidates.
+
+### The eligibility gates: `crn` vs `occurrence`
+
+A role's eligibility gate is a `canon.yaml` `learn:`-section choice:
+
+```yaml
+# canon.yaml
+learn:
+  promotion:
+    dev:
+      mode: occurrence
+      n_min: 8            # optional — defaults to 5
+      window_days: 14     # optional — defaults to 30
+    sim:
+      mode: crn
+  demotion:
+    hard_delete: false                 # optional — soft-flag is the default
+    strategies_root: .canon/strategies # optional
+```
+
+A role with no explicit `promotion.<role>` entry defaults to
+`mode: occurrence, n_min: 5, window_days: 30`.
+
+- **`occurrence`** — for roles whose domain does NOT support deterministic
+  replay. Within the trailing window, at least `n_min` resolved `Success`
+  trajectories for the same `regime_key` are required and no `Failure` or
+  `RolledBack` trajectory may be present. A contradiction resets the count;
+  it is never averaged away. This eligibility does not replace paired
+  evaluation or signed approval.
+- **`crn`** — for roles that CAN run a deterministic simulator. A paired
+  common-random-number statistical eligibility gate uses the same
+  `crn:config=<label>` and `crn:panel=<index>` panels across compared
+  configurations. Insufficient panels/noise evidence is not a pass. CRN
+  eligibility still does not replace the external `PromotionEvaluation` and
+  signature.
+
+Both gates read resolved `verdict_record.outcome`, not raw verdict rows.
+`Pending` trajectories neither corroborate nor contradict. `canon ingest
+artifacts` is therefore always first:
+
+```bash
+canon ingest artifacts
+canon learn promote <id> --evaluation evaluation.json --approval approval.json
+```
+
+### Demotion versus authenticated rollback
+
+A later ordinary contradictory `Failure`/`RolledBack` trajectory demotes an
+already-active strategy when a non-dry-run promotion observes it. The default
+is append-only soft-flagging of the existing git file with `status: demoted`
+and `reason:`; `demotion.hard_delete: true` deletes that file instead. This
+ordinary contradiction path is not an approval and does not create a rollback
+record.
+
+An operator-requested rollback is a distinct authenticated action:
+
+```bash
+canon learn rollback <strategy_id> --reason "<reason>" --actor alice \
+  --signature-file rollback.sig --approved-at 2026-10-02T12:00:00Z \
+  [--contradicting-trajectory-id <trajectory_id>] --repo .
+```
+
+`--signature-file` is an armored SSH detached signature over the
+`canon-learning-approval-v1` payload bound to
+`strategy:<id>:rollback:<sha256(reason)>`, actor, and `--approved-at`.
+`actor` MUST be listed in policy-pinned `approval.allowed_signers`; verification
+uses that file and `ssh-keygen -Y verify`. Successful rollback writes durable
+provenance, sets lifecycle `rolled_back`, and records the optional contradicting
+trajectory. Missing policy, signer, timestamp, or signature fails closed.
+
+### What retrieval can and cannot serve
+
+Retrieval serves only exact role/regime matches and excludes demoted,
+quarantined, rejected, and rolled-back strategies. Legacy rows with
+`lifecycle: null` remain readable for backward compatibility, but they have no
+quarantine/evaluation/signature provenance and MUST NOT be treated as proof of
+the current activation workflow. Retrieval is fail-soft and advisory; it does
+not upgrade legacy rows or establish measured uplift.
+
+## How verdicts feed scoring
+
+Verdicts arrive from `canon ingest artifacts` (see
+`canon-artifact-ingest`), persisted regime-keyed
+(`<role>/<repo>/<area>/<hash>`). Each verdict scores its covering
+trajectory into `Success` / `Failure` / `RolledBack` / `Pending`; the
+eligibility gate reads a regime's accumulated resolved verdicts, while the
+paired evaluation and signed approval decide whether a quarantined strategy
+may become active. A contradicting trajectory for an already-promoted
+strategy triggers ordinary demotion; an explicit rollback is separate and
+authenticated.
+
+## Reading a demoted or rolled-back strategy
+
+An ordinary contradicting trajectory demotes an active strategy append-only:
+the default soft-flag merges `status: demoted` + `reason: <text>` into the
+existing front matter and leaves the body byte-unchanged. Set
+`demotion.hard_delete: true` to delete the file instead. A strategy demoted
+before it reached the git tier has no file to flag — that is not an error.
+`canon retrieve` skips demoted and rolled-back strategies. An authenticated
+rollback is different: it records signed operator provenance and sets the
+stored lifecycle to `rolled_back`.
+
+## The flywheel
+
+```
+ingest → resolved trajectories → quarantined strategies
+   ↑                                  │
+verdicts                 eligibility + paired evaluation + SSH approval
+                                      │ (activate)
+                                      ▼
+                      active git strategies → advisory retrieve
+```
+
+## What this skill does NOT cover
+
+- Retrieval at dispatch time (`canon retrieve`, the pre-dispatch hook) —
+  see the `canon-retrieve` skill.
+- Producing the verdict trajectories promotion reads — see the
+  `canon-artifact-ingest` skill.