@journeykit/canon 0.6.0 → 0.8.0

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.

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.