@journeykit/canon 0.13.1 → 0.14.0

package/dist/skills/SKILL.src.md

@@ -1,16 +1,81 @@
 ---
 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.
+description: Use for every build, implement, add-a-feature, change-a-feature or fix request in a repo that has canon.yaml, including sites, apps and games; prefer it there over generic site, app or game builder skills. Runs canon's working loop (brief, subject, scenarios with failure paths, units, implement, evidence, independent review, status transition) and routes to the canon CLI reference for setup, specs, gates, storage, ingestion, retrieval and reports.
 ---
 
 # 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.
+Features in this repo are managed with canon. This skill's job is the
+working loop below; the CLI manual lives in `reference/*.md` and
+`canon <command> --help`. Start every session with `canon status`: it says
+where each subject stands and lists the next commands.
 
-## Setup and provider projection
+## The working loop
+
+Follow these steps in order for every request that builds, changes or fixes
+a feature, a one-line request included. Two points stop for a human:
+
+- **The brief** (step 1): the request, your assumptions, your open questions.
+- **The policy**: `.canon/policy.yaml` (written by `canon init`) is what the
+  gate grades the work against. A human approves it; never edit it to make
+  the gate pass.
+
+When no human can answer, write the question into the brief, proceed on the
+assumption you state there, and say so in your final report.
+
+1. **Brief.** Write down the request verbatim, your assumptions, and the
+   questions you could not ask. It becomes the change's
+   `openspec/changes/<slug>/proposal.md`, which
+   `canon change new <slug> --subject <id> --title "…"` scaffolds once the
+   subject exists (step 2). A human approves the brief.
+2. **Subject.** `canon subject new <id> --domain <domain> --title "…"`, then
+   `canon change new <slug> --subject <id> --title "…"`, and put the brief in
+   the change's `proposal.md`.
+3. **Scenarios.** `canon feature new <area>.<surface> --title "…"`, then one
+   `canon scenario new <area>.<surface>.<nn> --subject <id> --case <case> --title "…"`
+   per behavior, with failure paths (`--case failure`) as well as `happy`
+   and `edge`. When the gate asks for a missing case (`require_cases`), add
+   a new scenario; never retag an existing one to satisfy it. Check the
+   corpus with `canon format specs` and index it with `canon inventory sync`.
+4. **Units.** Split the work into units (for example specs, domain code,
+   assets, review). Give each unit its own actor id and session id, and pass
+   them on everything the unit records (`--actor-id <unit> --session-id <session>`),
+   so the ledger shows which unit did what. A delegated unit attests its own
+   work; never attest another unit's work under your id.
+5. **Implement.** Write the code with tests whose names carry the scenario
+   id (`game.run.01: …`), so a test report binds to its scenario.
+6. **Evidence.** Per scenario:
+   `canon evidence add --project-id <root-id> --scenario-id <id> --kind test-run --role implementer --ref "<command>" --actor-id <unit> --session-id <session>`,
+   with `--report junit:<path>` or `--artifact <path>` when files prove it.
+   canon stores those bytes in `.canon/artifacts/sha256/` (commit it with the
+   ledger) and `canon gate check` re-checks them. Then `canon gate promote`.
+7. **Independent review.** A different session from the one that wrote the
+   code and evidence reviews the change. Record every defect as a finding,
+   including the ones the author found and fixed during implementation:
+   `canon finding add --change-id <slug> --round <n> --seq <n> --severity <blocker|should-fix|note> --reviewer <me> --actor-id <me> --session-id <session> --summary "…"`,
+   then `canon gate promote`; once fixed,
+   `canon finding close --change-id <slug> --round <n> --seq <n> --disposition fixed --resolution-sha <sha>`
+   and `canon gate promote`. Every bug fix adds or extends a scenario. The
+   reviewer signs off each scenario:
+   `canon review add --project-id <root-id> --scenario-id <id> --reviewer <who> --actor-id <who> --role reviewer --session-id <review-session> --pin <sha> --upstream-ref <ref>`
+   (written directly; nothing to promote).
+8. **Transition.** `canon subject status <id> <state>` along
+   `proposed → specced → building → verifying → shipped`. It refuses a move
+   the policy does not yet allow (missing evidence, missing reviews, open
+   blocker findings); fix the gap rather than overriding, and finish with
+   `canon gate check` clean.
+
+Every write command says whether it staged the record (then
+`canon gate promote`) or wrote it directly.
+
+## Command reference
+
+Load only the reference the current step needs.
+
+### Setup and provider projection
 
 ```bash
-canon init
+canon init                                   # canon.yaml, starter policy, AGENTS.md block, plans home
 canon skills install                         # detects .claude/.agents|.codex/.omp/.pi; if none exists, installs Claude+Codex
 canon skills install --providers=claude,codex,omp,pi
 canon skills check                           # read-only drift check
@@ -26,24 +91,23 @@ legacy `.codex/skills/canon*` projection from canon 0.13.0 or earlier is
 migrated by `canon skills install` and reported by `check`/`doctor`. 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`.
+installed as a native hook. `canon/skills-dev` is a separate developer-only
+legacy source and is installed explicitly with `--source canon/skills-dev`.
 
-## Route by task
+### 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.
+- **Where the repo stands, subjects and changes (loop steps 1, 2, 8):** read `reference/canon-subject.md`; it covers `canon status`, `canon subject new|adopt|status` and `canon change new`.
+- **Write or reorganize `.feature` specs (step 3):** 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`.
-- **Finish a subject (claim work done):** read `reference/canon-review.md`. Order: test-run evidence (`canon evidence add`) → independent review of the adopted change (`canon finding add` per issue, fix, `canon finding close --disposition fixed --resolution-sha <sha>`) → `canon review add` per scenario by a reviewer other than the evidence actor → `canon subject status`. Commit each record with `canon gate promote`.
-- **Ingest artifacts or sessions:** read `reference/canon-artifact-ingest.md`, `reference/canon-session-ingest.md`, or `reference/canon-plan-import.md`.
+- **Evidence, gates, task checkboxes, hooks (step 6):** read `reference/canon-gate.md`.
+- **Findings and reviews (step 7):** read `reference/canon-review.md`.
+- **Ingest artifacts, sessions or plans:** 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
+### 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.
+`canon status`, `canon format <root>`, `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-context.md

@@ -18,6 +18,23 @@ canon context --json          # the full machine-readable surface
 canon context --repo ../other # resolve a specific repo's surface
 ```
 
+The outline opens with a short header, then a blank line, then the
+schema outline starting at `capabilityVersion:`:
+
+```text
+status: run `canon status` for this repo's subjects, gaps and next commands
+warning: no policy: .canon/policy.yaml not found, so `canon gate check` requires no evidence, failure cases or review here
+```
+
+The `warning:` line appears when the policy file is absent or unreadable
+or has no `spec_coverage` section (the gate then requires no evidence,
+cases or review), or when that section is invalid (the gate refuses until
+it is fixed); it is omitted when coverage is in force. `context` describes what CAN be
+authored; `canon status` (see `canon-subject`) says where the repo stands
+and what to run next. `--json` is unchanged: the header adds no field,
+and `policy.spec_coverage`/`policy.diagnostics` already carry the same
+fact.
+
 ## Reproducible context packs and prompt bundles
 
 Use an explicit, repository-relative JSON manifest when a run needs a

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

@@ -24,7 +24,7 @@ Every violation carries one of these stable, grep-able strings:
 | `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, or a feature surface missing a `require_cases` case. 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 — or, with `spec_coverage.require_review` set, an in-scope scenario has no qualifying `Review` (none at all, or only reviews by its own evidence actor). See `canon-review`. |
 | `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. |
+| `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. Also: a file bound to a latest evidence record whose bytes are gone — no intact blob in `.canon/artifacts/sha256/` and no working-tree copy with the recorded digest (see Bound evidence stays provable below). |
 | `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. |
@@ -34,7 +34,7 @@ Every violation carries one of these stable, grep-able strings:
 ## `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
+check + the bound-artifact 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
@@ -60,7 +60,7 @@ adds the other direction: it starts from the Scenario corpus
 an unimplemented or mismatched spec becomes a reported violation.
 
 ```yaml
-# .canon/policy.yaml — ABSENT by default; absent means zero violations
+# .canon/policy.yaml — absent means zero violations; `canon init` writes a starter
 spec_coverage:
   require_evidence: true
   scope: [building, verifying]   # optional; omit for the whole corpus
@@ -69,11 +69,28 @@ spec_coverage:
   require_review: {}             # optional; see Independent review below
 ```
 
+`canon init` writes a starter `.canon/policy.yaml` with this section on
+(`require_evidence: true`, `require_cases: [failure]`,
+`require_review: {}`; see `canon-policy`). When the section is absent and
+the indexed corpus has scenarios, the gate says so after its result, on
+stdout like its other advisories, and the exit code is unchanged:
+
+```
+advisory: spec_coverage is off — 12 scenario(s) are not checked for evidence; see .canon/policy.yaml
+```
+
+A present section, even `require_evidence: false` or a malformed one
+(already a violation), and an empty corpus print no advisory.
+
 - **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.
+  scenario id. `--summary` is allowed here too (scanned for fabrication
+  markers like a task's); it is a row suffix only when the record also
+  names a `--task`. A record carrying both `--task` and `--scenario-id`
+  is one attestation answering both joins: it counts for the task cell
+  and for the scenario cell (verdicts, the shipped gate, the review gate).
 - **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`.
@@ -95,7 +112,9 @@ spec_coverage:
   in `require_review.scope` (default `[verifying, shipped]`; `[]` = every
   scenario; independent of `scope` above) need a `Review` record
   (`canon review add`), by a reviewer and actor other than the
-  scenario's evidence actor when `distinct_actor` (default `true`);
+  scenario's evidence actor, and from a session other than any evidence
+  session when both carry one (`--session-id`), when `distinct_actor`
+  (default `true`);
   gaps are `unreviewed-promotion`. With `block_on_findings` (default
   `true`), an open `blocker` Finding on a change an in-scope subject
   adopted is `open-blocker`. `exclude_lanes` also exempts scenarios
@@ -159,12 +178,20 @@ canon evidence add ... --report junit:target/nextest/default/junit.xml
 canon evidence add ... --report cucumber:reports/cucumber.json
 ```
 
-The case is found by the scenario id in its name, classname, or Cucumber
-tag — dotted (`cart.add.04`) or underscored (`cart_add_04`, the form a
-test function carries) — or named exactly with `--report-case <name>`
-(a Rust test by its function name). No match refuses (exit 2); a
-`faithful` verdict over a failed or skipped case refuses (exit 1). Files
-must be inside the repository and are recorded by relative path.
+A case is bound when the scenario id is its OWN: the first
+scenario-id-shaped token (`<area>.<surface>.<nn>`) in its full name —
+classname (a describe path) first, then name — dotted (`cart.add.04`) or
+underscored (`cart_add_04`, the form a test function carries), equals
+the scenario id; a Cucumber tag equal to it binds too. Start each test
+name with its scenario id: `game.session.04: restarting as in
+game.session.01` binds to `game.session.04` only, never to the id it
+mentions. Each bound case is its own attachment with its name and
+outcome. `--report-case <name>` (repeatable; a Rust test by its
+function name) ADDS cases; it never hides the scenario's own. No match,
+or a `--report-case` naming no case, refuses (exit 2); a `faithful`
+verdict when ANY bound case failed or was skipped refuses (exit 1). Files
+must be inside the repository, are recorded by relative path, and are
+stored (see Bound evidence stays provable).
 
 Strength, weakest first: `attested` (no attachment) < `artifact` (any
 bound file) < `report` (a parsed report whose case passed). The policy
@@ -189,6 +216,49 @@ violation in every mode. Canon still cannot know whether the bound test
 actually exercises the scenario — binding narrows the trust gap, it does
 not close it.
 
+## Bound evidence stays provable (the artifact store)
+
+`canon evidence add --artifact/--report` copies each bound file into
+`.canon/artifacts/sha256/<hex>`, named by its sha256. Writes go through a
+temp file and a rename, and a digest already stored intact is not written
+again. The directory is tracked in git (`canon init` never ignores it):
+commit it with the ledger. A file larger than 25 MiB is refused (exit 2);
+raise the limit with `--max-artifact-mib <N>`.
+
+`canon gate check` re-checks every file bound to a LATEST evidence record
+(the latest per task and per `(project_id, scenario_id)`):
+
+- the stored blob exists and hashes to the recorded digest → clean, even
+  after the working-tree file is rewritten (a smoke script that rewrites
+  `reports/smoke.json` on every run no longer orphans the record);
+- no blob, but the working-tree path still hashes to the recorded digest
+  → clean, with an advisory naming `canon evidence vault` (records from
+  before the store existed):
+
+  ```
+  evidence artifacts: 1 bound file(s) not in the artifact store — not failing the gate; run `canon evidence vault` to store them before the working tree changes:
+    unstored cart.add.01 reports/junit.xml (sha256 b7cb…) is verified against the working tree only
+  ```
+- anything else → `stale-evidence` naming the path, the recorded digest,
+  and what the store and the working tree hold now (`missing` or a
+  digest), ending with why: a stored blob that no longer hashes to its
+  name "does not match its name, so its bytes were altered"; a missing
+  one means "the bound bytes are gone". Re-run the test and re-attest
+  with `canon evidence add`.
+
+The check applies to every latest record, not only subjects in
+`spec_coverage.scope`: a binding is a claim about bytes whatever the
+subject's status, and a repo with no `spec_coverage` would otherwise never
+have its bindings checked. A superseded record is not checked —
+re-attesting is the fix.
+
+`canon evidence vault [--max-artifact-mib <N>]` stores the bytes for
+existing records: every attachment whose working-tree file still matches
+its digest is copied in, and everything else is listed as not stored,
+with both digests. It exits `0` whenever it ran (the gate decides whether
+an unstored file matters), `2` when the ledger cannot be read or a write
+fails.
+
 ## Effect-aware risk approvals (`risk_tiers`)
 
 `risk_tiers` is absent by default and remains a no-op when absent. When it
@@ -229,10 +299,18 @@ 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
+with an appended evidence note ONLY on a clean check. The note
+aggregates every record bound to the task, on one line:
+`— ✅ 3 evidence records (2 faithful, 1 not-applicable); latest: <summary>`
+(the latest `--summary`, or a default naming the latest passing record).
+Every other path — missing evidence, a `Divergent` verdict, a fabricated
+note on any of the task's records — leaves the row byte-unchanged and
+exits `1` with the blocking violation on stderr. After a flip, the plan
+source is re-ingested so the record store's task status agrees with the
+checkbox (`canon query --kind task` reads `done`); a failed re-ingest is
+a stderr warning naming `canon ingest plans`, never a failed flip.
+The success line is `canon gate task: <task_id> flipped — written
+directly; nothing to promote`. An already-`[x]` row is an idempotent no-op (exit `0`). An unknown
 `task_id` is reported (exit `1`).
 
 ```bash
@@ -258,6 +336,15 @@ canon gate promote --repo .            # land every staged candidate
 canon gate promote --repo . --dry-run  # preview only
 ```
 
+Which writes need this step: `evidence add`, `finding add` and `finding
+close` stage, and their success line ends ``— run `canon gate promote`
+to commit it``. `divergence stage` stages for `canon divergence promote`
+and names it. Every other write — `review add`, `divergence
+resolve|defer`, `subject new|adopt|status`, `change new`, `scenario new`, `feature new`,
+`gate task` (it edits the plan document and re-ingests it)
+— is final when it returns, and its success line ends `— written
+directly; nothing to promote`.
+
 ## `canon gate install-hooks [--repo] [--event] [--matcher] [--command] [--timeout]`
 
 Idempotent, diff-only hook-seam installation: merges one

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

@@ -17,6 +17,8 @@ plans:
       root: .              # resolved relative to canon.yaml's directory
 ```
 
+- `canon init` writes exactly this source, plus an empty
+  `openspec/changes/` (so the adapter never scans the repo root itself).
 - 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
@@ -135,8 +137,8 @@ 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.
+  conventions) — `canon change new` scaffolds one and adopts it into a
+  subject (see `canon-subject`); this skill covers IMPORTING that shape.
 - **`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** —

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

@@ -23,6 +23,25 @@ uncovered-cell spec_coverag — `spec_coverag` is not a known top-level policy.y
 The known keys still resolve normally, and `canon context` lists the
 diagnostic and reports `clean: false`.
 
+## The starter policy `canon init` writes
+
+A fresh `canon init` writes `.canon/policy.yaml` (skip it with
+`--no-policy`; an existing file is never overwritten):
+
+```yaml
+spec_coverage:
+  require_evidence: true    # every scenario needs evidence
+  require_cases: [failure]  # every feature surface needs a @case:failure scenario
+  require_review: {}        # verifying/shipped subjects need an independent review
+```
+
+The file carries comments explaining each field. It loads with zero
+diagnostics. It is what `canon gate check` grades the work against, so a
+human should review and approve it, and every later change to it. The
+agent doing the work should not write its own grading policy. Narrow it
+with `scope: [building, verifying]` to check evidence only for subjects
+in those statuses (see `canon-gate`).
+
 ## The closed CEL profile
 
 Every expression is evaluated against exactly one variable, `record` (the

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

@@ -17,15 +17,15 @@ state they are in.
 The order an agent follows to claim a subject done:
 
 1. **Test-run evidence** per owned scenario (`canon evidence add
-   --scenario-id <id> --project-id <root-id> ...`, then `canon gate
-   promote`). See `canon-gate`.
+   --scenario-id <id> --project-id <root-id> ... --session-id <session>`,
+   then `canon gate promote`). See `canon-gate`.
 2. **Independent review** of the change(s) the subject adopted. Record
    each issue the reviewer raises as a Finding, fix it, then close it:
 
    ```bash
    canon finding add --change-id c-demo --round 1 --seq 1 \
      --severity blocker --disposition open --reviewer reviewer-2 \
-     --summary "unbounded subprocess wait"
+     --summary "unbounded subprocess wait" --session-id review-session-1
    canon gate promote
    # ... fix, commit ...
    canon finding close --change-id c-demo --round 1 --seq 1 \
@@ -33,15 +33,18 @@ The order an agent follows to claim a subject done:
    canon gate promote
    ```
 
-3. **One Review per scenario**, by someone other than the evidence actor:
+3. **One Review per scenario**, by someone other than the evidence actor,
+   from a session other than the one that attested the evidence:
 
    ```bash
    canon review add --project-id root --scenario-id world.demo.01 \
      --reviewer reviewer-2 --actor-id reviewer-2 --role reviewer \
+     --session-id review-session-1 \
      --pin "$(git rev-parse HEAD)" --upstream-ref "pr#41"
-   canon gate promote
    ```
 
+   `review add` writes directly; there is nothing to promote.
+
 4. **Move the subject**: `canon subject status <id> verifying`, later
    `shipped`. See `canon-subject`.
 
@@ -57,15 +60,27 @@ work collapsed into one identity.
 canon finding add --change-id <c> --round <n> --seq <n> \
   --severity blocker|should-fix|note --disposition open \
   --reviewer <who> --summary "<one line>" \
-  [--reviewed-sha <sha>] [--file-ref path/to/file.rs:120-134] [--actor-id <id>]
+  [--reviewed-sha <sha>] [--file-ref path/to/file.rs:120-134] [--actor-id <id>] [--session-id <id>]
 canon finding close --change-id <c> --round <n> --seq <n> \
-  --disposition fixed --resolution-sha <sha>     # or rejected / deferred / open
+  --disposition fixed --resolution-sha <sha> [--session-id <id>]   # or rejected / deferred / open
 ```
 
-Both stage a candidate; `canon gate promote` commits it. `finding close`
+Both stage a candidate; `canon gate promote` commits it, and both say so
+(``… — run `canon gate promote` to commit it``). `finding close`
 changes only the disposition (and `resolution_sha` with it); severity,
 reviewer, summary, and refs are copied from the committed record. It
-appends a second version at the same natural key — the first stays.
+appends a second version at the same natural key — the first stays. Its
+`--actor-id` and `--session-id` name who authored the transition; the
+raiser's stay on the first version.
+
+### A defect the author found in its own work
+
+Record it like any other finding, with `--reviewer` and `--actor-id` set
+to the author's own id. Nothing refuses a finding whose reviewer is also
+the implementer, and an open `blocker` the author raised blocks under
+`block_on_findings` exactly like a reviewer's. `--introduced-by` names the
+commit that introduced the defect, not who found it: `--introduced-by self`
+is a usage error (exit 2) that points at `--reviewer`.
 
 ### Severities
 
@@ -98,15 +113,23 @@ fixed finding reopened with `--disposition open` counts as open again.
 ```bash
 canon review add --project-id <root-id> --scenario-id <id> \
   --reviewer <who> --pin <sha-or-ref> --role <role> \
-  (--upstream-ref <ref> | --original-spec-ref <ref>) [--actor-id <id>]
+  (--upstream-ref <ref> | --original-spec-ref <ref>) [--actor-id <id>] [--session-id <id>]
 ```
 
 One attributed Review record for one scenario, joined on
 `(project_id, scenario_id)` — both are required because two spec roots
 may carry the same scenario id. Exactly one provenance ref is required.
-`--actor-id` defaults to `canon`. A Review carries no verdict; the
-`verifying → shipped` ship gate still refuses missing or `Divergent`
-evidence verdicts on its own. Commit with `canon gate promote`.
+`--actor-id` defaults to `canon`; `--session-id` fills `actor.session_id`.
+A Review carries no verdict; the `verifying → shipped` ship gate still
+refuses missing or `Divergent` evidence verdicts on its own. It is
+written directly to the ledger, with no staging step, and says so:
+`canon review add: wrote <path> (new) — written directly; nothing to
+promote`.
+
+`--session-id` (on `evidence add`, `review add`, `finding add` and
+`finding close`) takes one opaque token: non-empty, no surrounding
+whitespace, no control characters. Anything else is a usage error
+(exit 2) and nothing is written.
 
 ## The `require_review` policy (opt-in)
 
@@ -129,8 +152,11 @@ spec_coverage:
   scenarios from review.
 - **`distinct_actor`** — a review only counts when both its `reviewer`
   and its actor (`--actor-id`) differ from every actor on that
-  scenario's evidence records. An agent cannot review its own attested
-  work.
+  scenario's evidence records, and, when the review carries a session,
+  that session differs from every session on those evidence records. An
+  agent cannot review its own attested work, under another id or from
+  the same session. A record with no session never matches one, so
+  records written before sessions were recorded count by actor alone.
 - **`block_on_findings`** — fail on open blocker findings (below).
 
 A malformed `require_review` (an unknown key, an unknown status, `null`,
@@ -138,7 +164,8 @@ a non-mapping) poisons the whole `spec_coverage` section: `canon gate
 check` reports it invalid rather than treating it as off, the same as a
 malformed `require_cases`.
 
-Canon's own `.canon/policy.yaml` does not enable `require_review`.
+Canon's own `.canon/policy.yaml` enables `require_review: {}`, and so does
+the starter policy `canon init` writes.
 
 ## How it meets the gate
 
@@ -156,6 +183,13 @@ or, when the only reviews are self-reviews:
 unreviewed-promotion world.demo.01 — every review of this scenario is by an actor that also attested its evidence (`impl-agent`); spec_coverage.require_review.distinct_actor wants a reviewer other than the evidence actor
 ```
 
+or, when another actor id reviewed from a session that attested the
+evidence:
+
+```
+unreviewed-promotion world.demo.01 — every review of this scenario is by an actor that also attested its evidence (`impl-agent`) or from a session that did (`sess-impl`); spec_coverage.require_review.distinct_actor wants a reviewer other than the evidence actor, in a session other than any evidence session
+```
+
 ### `open-blocker`
 
 With `block_on_findings`, a Finding whose latest version is severity
@@ -188,7 +222,7 @@ prints on stderr which review checks it ran or skipped:
 
 ```
 canon subject status: review guard for building → verifying (spec_coverage.require_review, scope: verifying, shipped)
-  ran unreviewed-promotion — every owned scenario needs a review by an actor other than its evidence actor
+  ran unreviewed-promotion — every owned scenario needs a review by an actor, and from a session, other than its evidence's
   ran open-blocker — 1 adopted change(s) checked for open blocker findings
 ```
 

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

@@ -135,7 +135,8 @@ what brings a scenario into that scope. See `canon-gate`.
 requires that the Subject OWNS at least one scenario (one whose latest
 synced generation carries `@subject:<id>`), and that EVERY owned
 scenario carries a latest, non-`Divergent` verdict in the ledger (the
-same last-wins rule `canon gate check` uses). With
+same last-wins rule `canon gate check` uses; a record keyed by both a
+task and the scenario counts for the scenario). With
 `spec_coverage.require_cases` set, every feature surface the Subject
 owns must also carry a scenario of each required `@case:` (e.g. one
 `@case:failure`) — attested golden-path scenarios alone do not ship. A
@@ -152,7 +153,7 @@ prints on stderr which it ran or skipped:
 
 ```
 canon subject status: review guard for building → verifying (spec_coverage.require_review, scope: verifying, shipped)
-  ran unreviewed-promotion — every owned scenario needs a review by an actor other than its evidence actor
+  ran unreviewed-promotion — every owned scenario needs a review by an actor, and from a session, other than its evidence's
   ran open-blocker — 1 adopted change(s) checked for open blocker findings
 ```
 
@@ -204,7 +205,143 @@ canon subject adopt subject-domain-loop-plan \
 
 `adopt` stamps the change's `subject_id` and adds it to the Subject's
 `change_ids`, so `canon query --kind change --change-id …` and `canon
-query --kind subject` agree on the link from both ends.
+query --kind subject` agree on the link from both ends. It writes only
+the side that lacks the link, so rerunning it on a linked pair writes
+nothing and exits `0`.
+
+The two records cannot be written atomically, so the subject is written
+first: its `change_ids` is what the gate reads a subject's adopted
+changes from (`open-blocker`, the status guard), so a half-done adoption
+still has that change's open blockers counted. If the change write then
+fails, `adopt` exits `2`, names the subject that now lists the change,
+and prints `canon subject adopt <change_id> --subject <id>` to complete
+it.
+
+### Starting a new change: `canon change new`
+
+For a change that does not exist yet, one command scaffolds it and
+records it adopted:
+
+```bash
+canon change new add-login --subject auth --title "Add login"
+```
+
+- **Writes** `openspec/changes/<slug>/proposal.md` (the title is its
+  `## Why`, which imports as the change summary) and `tasks.md` (no rows
+  yet, so the change imports as `proposed`), under the repo's first
+  `openspec` plans source. `canon init` configures that source
+  (`{dialect: openspec, root: .}`), so `canon.yaml` needs no edit.
+- **Reads** the files with the same `openspec` adapter `canon ingest
+  plans` uses, then **records** the change already adopted, through the
+  same write as `canon subject adopt`.
+- **What a failure leaves behind.** The files are staged under `.canon/`
+  and the change dir is moved into place only once they parse. A failure
+  before any record is written (staging, publishing the dir, or the
+  first record write) removes the change dir, the staged files and any
+  directory created for them: nothing is left behind. The two records
+  cannot be written atomically. If the change record fails after the
+  subject record was written, the command exits `2`, keeps the change
+  dir and that one subject record, and prints the repair, `canon ingest
+  plans && canon subject adopt <slug> --subject <id>`, which completes
+  the link and is safe to rerun.
+- **Refuses** with exit `2`, writing nothing, when the subject does not
+  exist, when the slug already has a change dir (active or archived) or a
+  `change` record, or when `canon.yaml` has no `openspec` plans source.
+
+Add task rows to `tasks.md` as `- [ ] <n> <title>`, rerun `canon ingest
+plans`, and flip each with `canon gate task <slug>#<n>` once evidence
+exists.
+
+## Where are we: `canon status`
+
+```bash
+canon status                 # subjects by status, their gaps, next commands
+canon status --json          # the same report, stable shape
+canon status --repo ../other
+```
+
+A read: it always exits 0 and writes nothing (no ledger record, no
+`.canon/audit` line). Every count comes from the joins the gate itself
+uses, so status and the gate cannot disagree about a gap:
+
+- **Header** — the canon version, and the policy in force:
+  `spec_coverage` (with `scope`/`exclude_lanes`), `require_cases` and
+  `require_review`. When `.canon/policy.yaml` is absent, unreadable, has
+  no `spec_coverage` section, or has an invalid one, a `warning:` line
+  says the gate requires no evidence, failure cases or review (or refuses
+  until it is fixed).
+- **Subjects grouped by status** (lifecycle order). Per subject:
+  scenarios it owns through `@subject:` (after `exclude_lanes`, which
+  are counted separately), how many carry a ledger verdict (the
+  `verifying → shipped` gate's reading; divergent ones are counted too),
+  how many carry a review that satisfies `require_review` (any review
+  when it is off; with `distinct_actor`, a self-review does not count),
+  open blocker findings on its adopted changes, and each feature surface
+  missing a `require_cases` case. `(N due)` marks reviews the next
+  transition will require.
+- **Unowned** — scenarios with no `@subject:` tag.
+- **`next:`** — at most five commands, each with a one-line reason; the
+  rest are counted. Rules, in order: no `canon.yaml` → `canon init`; an
+  unreadable one → `canon init --check-config`; a scenario tagged with a
+  subject that has no record → `canon subject new <that id>`; no subject
+  at all → `canon subject new`; subjects but no scenario records →
+  `canon inventory sync`. Then per subject, verifying first, then
+  building, specced, proposed, shipped: no scenario → `canon scenario new
+  … --subject <id>`; a missing case → `canon scenario new <surface>.<next
+  nn> … --case <case>`; (building and later) an unevidenced or divergent
+  scenario → `canon evidence add --scenario-id …`; an open blocker →
+  `canon finding close …`; a due, unreviewed, evidenced scenario →
+  `canon review add …` from another session; none of these →
+  `canon subject status <id> <next status>`. Last, unowned scenarios →
+  tag them and `canon inventory sync`. With more than one `specs.roots[]`
+  entry, every suggested `canon scenario new` carries `--project`: the
+  owning root for a missing case, `<root-id>` (the reason lists the
+  roots) for a subject that owns no scenario yet.
+
+Status fails closed rather than suggest progress the gate would refuse:
+
+- When `scenario`, `subject`, `review` or `finding` routes away from the
+  `local` rung (the only rung status and the gate read), its records
+  would read as empty. The only `next:` step is
+  `canon init --check-config`, with the reason naming the
+  `routing.<kind>: local` setting to restore.
+- When `spec_coverage` is present but unusable, `canon gate check`
+  refuses. The first `next:` step is `canon gate check`, with the reason
+  naming the section to fix, and no subject is suggested to move to its
+  next status until it parses.
+
+`--json` prints one object:
+
+```json
+{
+  "statusVersion": 1,
+  "canonVersion": "0.14.0",
+  "policy": { "present": true, "spec_coverage": { "require_evidence": true, "scope": [], "exclude_lanes": [], "require_cases": ["failure"], "require_review": { "scope": ["verifying", "shipped"], "distinct_actor": true, "block_on_findings": true } } },
+  "warnings": [],
+  "subjects": [
+    { "id": "cart", "title": "Cart", "status": "building", "scenarios": 2, "excluded": 0, "evidenced": 2, "divergent": 0,
+      "reviewed": 1, "reviewDue": true, "openBlockers": 1, "missingCases": [] }
+  ],
+  "unowned": ["cart.promo.01"],
+  "next": [
+    { "command": "canon finding close --change-id c-cart --round 1 --seq 1 --disposition fixed --resolution-sha <sha> --actor-id <unit> --session-id <session>", "why": "cart: 1 open blocker finding(s) (first: …); fix it, commit, then close it" },
+    { "command": "canon review add --project-id root --scenario-id cart.add.02 --reviewer <reviewer> --actor-id <reviewer> --session-id <review-session> --role reviewer --pin <sha> --original-spec-ref \"<feature file>\"", "why": "cart: 1 of 2 scenario(s) lack a qualifying review; …" },
+    { "command": "canon inventory sync", "why": "1 scenario(s) carry no @subject tag (first: cart.promo.01); …" }
+  ],
+  "nextOmitted": 0
+}
+```
+
+Each `missingCases` entry is `{ "projectId", "surface", "case" }`: the
+spec root, the `<area>.<surface>`, and the required case it lacks.
+
+`policy.spec_coverage` has the shape `canon context --json` prints
+(`null` when absent, `{"invalid": …}` when unusable). `statusVersion`
+changes only when a field changes meaning or is removed.
+
+`subject new`, `adopt` and `status` write their records directly; the
+human-readable success line ends `— written directly; nothing to
+promote` (`--json` prints the record and nothing else).
 
 ## Reading the per-domain management view
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@journeykit/canon",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "canon — harness knowledge substrate. JS launcher: platform detection + native binary resolution.",
   "license": "MIT",
   "type": "module",
@@ -30,9 +30,9 @@
   },
   "dependencies": {},
   "optionalDependencies": {
-    "@journeykit/canon-core-darwin-arm64": "0.13.1",
-    "@journeykit/canon-core-linux-x64": "0.13.1",
-    "@journeykit/canon-core-win32-x64": "0.13.1"
+    "@journeykit/canon-core-darwin-arm64": "0.14.0",
+    "@journeykit/canon-core-linux-x64": "0.14.0",
+    "@journeykit/canon-core-win32-x64": "0.14.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",