@journeykit/canon 0.6.0 → 0.8.0

package/dist/index.js

@@ -78,6 +78,11 @@ function resolveTargetPackageName() {
       return "core-linux-x64";
     return null;
   }
+  if (process.platform === "win32") {
+    if (arch === "x64")
+      return "core-win32-x64";
+    return null;
+  }
   return null;
 }
 function resolveRustTargetTriple() {
@@ -150,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.