@journeykit/canon 0.7.0 → 0.8.0

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.

package/dist/skills/reference/canon-plan-import.md

@@ -0,0 +1,143 @@
+# canon-plan-import
+
+`canon ingest plans` imports a FOREIGN plan dialect's on-disk state into
+canon's `change`/`task` records, through the same validated path every
+other ingest family uses. Imported rows carry no special marker — once
+imported, `canon query` cannot tell an imported row from a hand-authored
+one, and neither can `canon gate`.
+
+## 1. Configure a `plans:` source
+
+`canon.yaml`:
+
+```yaml
+plans:
+  sources:
+    - dialect: openspec
+      root: .              # resolved relative to canon.yaml's directory
+```
+
+- An absent `plans:` section = zero sources (a clean no-op).
+- A present section parses STRICTLY: a typo'd key, an unregistered
+  `dialect`, or a nonexistent `root` fails the command loud, naming the
+  offender.
+- `root` is whatever the dialect's adapter scans — for `openspec`, a
+  repo root containing `openspec/changes/`, or that changes dir directly.
+
+One-shot override (bypasses `canon.yaml` for a single ad hoc import;
+either flag alone fails loud):
+
+```bash
+canon ingest plans --dialect openspec --source ../other-repo
+```
+
+## 2. Run the import
+
+```bash
+canon ingest plans                 # canon.yaml-driven, every configured source
+canon ingest plans --json          # machine-readable outcome
+canon ingest plans --repo ../svc   # a specific repo root
+```
+
+Per source the summary reports `changes_parsed`/`tasks_parsed`,
+`changes_persisted`/`tasks_persisted`, `changes_unwritten`/
+`tasks_unwritten` (an unreachable tier — printed, never silently
+dropped), `duplicate_change_id` (two sources producing the same
+`change_id` this pass — the LATER is skipped and counted, never merged),
+the adapter's `unmapped` drop counts, and `malformed` (structurally
+broken constructs). A source whose content is byte-identical to its last
+successful run is `skipped_unchanged` — re-importing writes zero records.
+
+## 3. Read the imported rows
+
+```bash
+canon query --kind change [--json]
+canon query --kind task [--json]
+```
+
+No dialect/plugin filter exists or is needed — an imported `change`/
+`task` is an ordinary core record.
+
+## The `openspec` dialect
+
+Maps `openspec/changes/**` onto core kinds:
+
+| openspec construct | Core mapping |
+| --- | --- |
+| change dir's basename | `change_id` (verbatim — no slug massaging) |
+| `proposal.md`'s `## Why` first paragraph | `Change.summary` (absent heading → empty summary + a `proposal-missing-why` diagnostic) |
+| archive location vs. checkbox tallies | `Change.status` (`archived` wins; else zero rows → `proposed`, all done → `completed`, mixed → `in_progress`) |
+| each `tasks.md` checkbox row | `Task` (`task_id = <change_id>#<n>`, status verbatim, evidence_note from a ` — ✅ ` suffix or a `**DEFERRED**`/`**DROPPED**` annotation) |
+| `specs/**/spec.md` `#### Scenario:` blocks | dropped, counted under `spec-delta-scenario` |
+| `design.md` | dropped, counted under `design-doc` |
+
+A missing/unreadable `proposal.md`, or a basename that isn't a valid
+`change_id`, skips the WHOLE dir (counted `malformed`); siblings
+unaffected. A proposal-only dir imports as `Change { status: proposed }`
+with zero tasks and zero diagnostics.
+
+## The `superpowers` dialect
+
+Maps one plan document (an `*.md` immediate child of the plans root),
+following the superpowers `writing-plans` skill's grammar:
+
+| `writing-plans` construct | Core mapping |
+| --- | --- |
+| the filename stem, slugified (lowercased, each `[^a-z0-9]+` run → one `-`, edge `-` trimmed; date prefix kept verbatim) | `change_id` |
+| the `**Goal:**` line's remainder, whitespace-normalized | `Change.summary` (absent → empty summary + a `goal-missing` diagnostic) |
+| checkbox tallies across every `### Task N:` section | `Change.status` (zero tasks → `proposed`, all done → `completed`, mixed → `in_progress`) |
+| each `### Task N: <name>` section | `Task` (`task_id = <change_id>#<N>`, title = text after the colon; status `done` iff the section has ≥1 checkbox line and ALL are checked, else `open`) |
+| steps, `**Architecture:**`/`**Tech Stack:**` prose, Global Constraints, non-task headings | never read, never a diagnostic |
+
+Worked example — `2026-07-14-website-design.md`:
+
+```markdown
+# Website Implementation Plan
+
+**Goal:** Build the project website.
+
+### Task 1: Layout
+
+- [x] **Step 1: scaffold the grid**
+- [x] **Step 2: wire the nav**
+
+### Task 2: Copy
+
+- [x] **Step 1: draft the homepage**
+- [ ] **Step 2: proofread**
+```
+
+imports as `Change { change_id: "2026-07-14-website-design", summary:
+"Build the project website.", status: in_progress }`, plus
+`Task { task_id: "…#1", title: "Layout", status: done }` and
+`Task { task_id: "…#2", title: "Copy", status: open }`. The `**Step N:**`
+bolding is NOT load-bearing — a plain `- [ ]`/`- [x]` row still counts.
+
+An invalid task-number heading is skipped and named `malformed`; a
+duplicate `Task N` heading keeps the first section and names the later one
+`malformed`. A filename stem that fails to slug into a valid `change_id`
+is malformed too. A markdown file with neither a `**Goal:**` line nor any
+`### Task N:` heading (a stray `README.md`) is skipped with a
+`not-a-plan-doc` diagnostic, not imported as garbage. Only immediate-child
+`*.md` files are read, byte-lexically sorted; an absent/unreadable root
+yields zero records, never an error.
+
+## The task_id join
+
+An imported `Task.task_id` is byte-identical to the join key of the
+openspec-task verdict events canon's artifact ingest derives from the same
+checkbox tree — so `canon report`'s trust matrix joins the two sides on
+`task_id` for its coverage columns, and `canon ingest plans` is that
+join's bulk producer. `canon ingest plans` itself performs no join and
+writes no verdict/evidence — joining plan state against evidence is a
+downstream reader's job.
+
+## What this skill does NOT cover
+
+- **Authoring an openspec change dir** (`proposal.md`/`tasks.md`
+  conventions) — see the openspec CLI's own docs; this skill covers
+  IMPORTING that shape, not producing it.
+- **`canon gate check`/`canon gate task`** (the hand-authored one-task-at-
+  a-time path this complements at bulk) — see `canon-gate`.
+- **Wiring an imported `Task`/`Change` into a `canon gate` decision** —
+  out of scope; needs its own reviewed change.

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

@@ -0,0 +1,131 @@
+# canon-plugins
+
+A plugin adds fields to a core record WITHOUT changing that record's
+schema. It declares a NAMESPACED overlay kind (`<namespace>.<kind>`, e.g.
+`porting.coverage`), writes overlay records into that namespace, and a
+read-time JOIN projects the declared fields onto the core view. Core
+records are NEVER rewritten by any step — the overlay write path is
+append-only under a foreign namespace, and a manifest cannot alias a
+core kind's on-disk path even by accident. Today overlays attach to the
+`scenario` core kind only.
+
+## 1. Author a `plugin.yaml` manifest
+
+`.canon/plugins/<id>/plugin.yaml`:
+
+```yaml
+id: porting
+namespace: porting
+overlays:
+  - kind: coverage
+    attaches_to:
+      core_kind: scenario           # `scenario` ONLY
+      join_key: [project_id, scenario_id]
+    fields:
+      - name: covered
+        type: bool
+      - name: surface_ref
+        type: { list: string }
+```
+
+- `id`/`namespace`/`overlays[].kind` are REQUIRED — a missing field fails
+  the load outright, never defaulted.
+- `namespace` and every overlay `kind` MUST match the kebab-token grammar
+  `[a-z0-9]+(-[a-z0-9]+)*` — else rejected with `E-PLUGIN-GRAMMAR`.
+- `<namespace>.<kind>` MUST NOT collide with a core record kind name
+  (`E-PLUGIN-CORE-COLLISION`) and MUST be unique across installed plugins
+  (`E-PLUGIN-DUP-OVERLAY`).
+- `attaches_to.core_kind` MUST be `scenario` — any other value fails with
+  `E-PLUGIN-CORE-KIND`.
+- `type` is a bare scalar (`bool`/`number`/`string`), `{ enum: […] }`, or
+  `{ list: <type> }`.
+- Two packages declaring the SAME `id`: the later (directory-sort order)
+  is dropped and diagnosed, never merged (`E-PLUGIN-DUP-ID`).
+- An absent `.canon/plugins/` directory resolves an empty, valid snapshot —
+  never a panic.
+
+## 2. Validate + write overlay records
+
+Drive it through the sync command (never hand-write records):
+
+```bash
+canon plugin sync porting                       # every canon.yaml specs.roots[] entry
+canon plugin sync porting --repo ../svc         # a specific repo
+canon plugin sync porting --spec-root ./specs   # ad hoc: ignore canon.yaml
+```
+
+`canon plugin sync <plugin-id>` resolves the manifest, then for each
+candidate validates FIRST (envelope present + typed; every required
+`join_key` field present + a string; every declared field present + type-
+matching; no field outside envelope ∪ join-key ∪ declared), then writes.
+The on-disk path is derived from the join-key field values in declared
+order plus a body digest — a byte-identical resubmission dedupes to the
+same path; a different body for the same join key appends at a new path,
+never overwriting.
+
+## 3. Project a read
+
+```bash
+canon query --kind scenario --plugin porting          # human table, projected fields appended
+canon query --kind scenario --plugin porting --json   # merged record bodies
+canon query --kind scenario                           # no --plugin: byte-identical to the core view
+```
+
+`--plugin <id>` folds the plugin's overlay records (latest-by-
+`(join_key, at)`) onto each queried core record. Fail-soft everywhere:
+
+- No overlay record for a core key → that record projects UNMODIFIED (no
+  value invented).
+- A malformed overlay record (fails validation against the CURRENT
+  manifest — e.g. the schema drifted after the record was written) →
+  SKIPPED + diagnosed; siblings still project.
+- An absent plugin/manifest → the unmodified core view + a diagnostic,
+  never a process error.
+- Omitting `--plugin` is byte-identical to `canon query`'s output without
+  plugins — it's a purely additive layer.
+
+## The `porting` worked example
+
+`porting` moves the `covered`/`surface_ref` fields off the core
+`scenario` record and into a plugin overlay:
+
+1. `.canon/plugins/porting/plugin.yaml` — the manifest above.
+2. Its overlay source reads a spec root's `inventory/**/*.yaml` (the same
+   inventory files `canon format --check` covers) and, for every
+   `(project_id, scenario_id)` `canon inventory sync` would index, emits
+   one candidate: `covered = true` iff that `scenario_id` appears in ANY
+   inventory entry's `covered_by` list; `surface_ref` = every inventory-
+   entry key whose `covered_by` contains it (empty when uncovered). The
+   candidate's envelope `at` is the source version (the max inventory-file
+   `at`), so an unchanged inventory re-syncs to a byte-identical body
+   (zero new files) and a genuine coverage edit supersedes the prior
+   overlay via latest-`at`-wins.
+3. `canon plugin sync porting` writes/dedupes those candidates.
+4. `canon query --kind scenario --plugin porting [--json]` projects
+   `covered`/`surface_ref` back onto each scenario.
+
+`canon gate check`'s verdicts are byte-identical with and without a
+`canon plugin sync porting` run — the gate reads NO plugin overlay. Wiring
+an overlay field into a gate decision needs its own reviewed change
+("covered ≠ coverage").
+
+## Do not confuse the two `plugin.yaml` surfaces
+
+The typed-authoring vocabulary (`.canon/vocab/<id>/plugin.yaml`: directives
++ enums for task-atom authoring — see `canon-vocab`) is a
+DIFFERENT directory and a DIFFERENT schema. A ledger-overlay manifest
+misplaced under `.canon/vocab/<id>/` fails that loader (missing
+`directives`/`enums`), not silently parsing as an authoring vocabulary.
+
+## What this skill does NOT cover
+
+- **`canon inventory sync`** (the core index `porting`'s source reads) —
+  see `canon-inventory`.
+- **`canon gate check`** — see `canon-gate`; the gate never reads a
+  plugin overlay.
+- **`canon scenario new`/`canon feature new`** (corpus-authoring
+  scaffold, independent of the plugin machinery) — template generators
+  that write no ledger record.
+- **A projection over a core kind other than `scenario`, or wiring an
+  overlay field into a `canon gate` decision** — out of scope; each needs
+  its own reviewed change.