@journeykit/canon 0.11.0 → 0.12.0

package/dist/skills/SKILL.src.md

@@ -36,6 +36,7 @@ installed explicitly with `--source canon/skills-dev`.
 - **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`.
 - **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.

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

@@ -5,7 +5,9 @@ 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
+authoring vocabulary, the review vocabulary (`review`: finding severities
+and dispositions, Review fields, the active `require_review`; see
+`canon-review`), and the CEL binding surface — folded into one
 deterministic authoring surface.
 
 ## `canon context [--repo <dir>] [--json]`

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

@@ -15,20 +15,21 @@ release-scoped check (below) enforces it. A human-only `flagged` overlay
 overrides the ladder — a flagged artifact is never green regardless of
 evidence. (Author `policy.yaml`'s trust/staleness fields via `canon-policy`.)
 
-## The eight failure classes
+## The nine failure classes
 
 Every violation carries one of these stable, grep-able strings:
 
 | Class | Meaning |
 |---|---|
 | `uncovered-cell` | Either a policy-required evidence cell (role × artifact) with no matching record, or — with `spec_coverage` enabled — a spec scenario that is unimplemented or mismatched, 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. |
+| `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. |
 | `malformed-evidence` | A candidate record doesn't parse, is misfiled, or carries an unparseable interim tag. Malformed evidence is no evidence. |
 | `flagged` | The human-only `flagged` overlay is set — never green regardless of passing evidence. |
 | `unevidenced-flip` | `canon gate task <task_id>` was asked to flip a checkbox with no matching, non-`Divergent` evidence record. |
 | `fabricated-evidence` | An evidence note contains a blocklisted marker (`"would pass"`, `"TBD"`, `"n/a"`) or a bare `verified` claim with no attached command result. |
+| `open-blocker` | With `spec_coverage.require_review` set (and `block_on_findings`, the default), a Finding whose latest version is severity `blocker`, disposition `open`, on a change an in-scope subject adopted. Subject string `<change_id>#<round>.<seq>`. See `canon-review`. |
 
 ## `canon gate check [--repo <dir>] [--release]`
 
@@ -65,6 +66,7 @@ spec_coverage:
   scope: [building, verifying]   # optional; omit for the whole corpus
   exclude_lanes: [process]       # optional
   require_cases: [failure]       # optional; see Golden-path only below
+  require_review: {}             # optional; see Independent review below
 ```
 
 - **Unimplemented** — no `EvidenceRecord` carries the scenario's
@@ -89,13 +91,32 @@ spec_coverage:
   no case, so an unclassified corpus is reported, not passed. Works with
   `require_evidence: false` too. `canon subject status <id> shipped`
   applies the same rule to the scenarios the subject owns.
+- **Independent review** (`require_review`) — scenarios whose subject is
+  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`);
+  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
+  from review. Full contract: `canon-review`.
+
+  ```yaml
+  spec_coverage:
+    require_evidence: true
+    require_review:                 # absent = nothing changes
+      scope: [verifying, shipped]   # default
+      distinct_actor: true          # default
+      block_on_findings: true       # default
+  ```
 
 Two refusals rather than a silent pass, both surfacing as
 `uncovered-cell` on the subject `spec_coverage`:
 
-- A **malformed section** (unknown key, unknown `scope` status) refuses
-  at check time. It is never treated as absent — a typo must not be
-  silently equivalent to not opting in.
+- A **malformed section** (unknown key, unknown `scope` status, or a
+  malformed `require_cases`/`require_review` — unknown key, bad status,
+  `null`, non-mapping) refuses at check time. It is never treated as
+  absent — a typo must not be silently equivalent to not opting in.
 - A **corpus kind routed off the gate's rung** (`scenario`,
   `divergence`, or `subject` sent anywhere but `local`) refuses, because
   the gate reads one tier and would otherwise pass by seeing nothing.
@@ -104,6 +125,22 @@ Malformed rows in those three kinds do NOT surface as
 `malformed-evidence`; they are kept off the evidence violation set on
 purpose, so enabling nothing changes no existing verdict.
 
+### Review-waiver advisories
+
+A subject moved into a review-scoped status with `canon subject status
+--override-reason` (see `canon-subject`) keeps the `unreviewed-promotion`
+and `open-blocker` gaps its waiver recorded visible without failing the
+gate. Only those exact `(class, subject)` pairs are waived; a gap that
+appears later is a violation. The waived ones print after the
+violations:
+
+```
+review waivers: 1 advisory(ies) — not failing the gate:
+  waived unreviewed-promotion world.demo.01 — no review record ... [waiver: subject `demo-subject` moved to verifying by `lead`: reviewer out until Monday]
+```
+
+The waiver lasts only until the subject's next status write.
+
 ## Experimental: evidence binding (`experimental.evidence_binding`, off by default)
 
 An evidence record is an attestation: canon never runs `--ref`, and it
@@ -243,7 +280,8 @@ Prefer this over hand-editing `settings.json`/`hooks.json`.
 
 ## `canon gate selftest`
 
-Runs the shipped fixture corpus — one fixture per failure class, each a
+Runs the shipped fixture corpus — one fixture per failure class (nine,
+including `open-blocker`), each a
 deliberately broken corpus proving that class fires and ONLY that class
 (both under-detection and over-triggering fail the run). Takes no
 `--repo`; self-contained. Run it before trusting any other `canon gate

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

@@ -0,0 +1,223 @@
+# canon-review
+
+Evidence says a test exists and what verdict it recorded. It does not say
+that anyone other than the author looked at the work. Canon records that
+second look as two ledger kinds — a **Finding** per issue a reviewer
+raises, and a **Review** per scenario a reviewer signs off — and the
+opt-in `spec_coverage.require_review` policy makes `canon gate check` and
+`canon subject status` hold a subject until both are in order.
+
+Both records are attestations: canon never checks a finding's summary
+against the code, or that a reviewer actually read the scenario. What the
+gate can check is that the records exist, who authored them, and what
+state they are in.
+
+## Finish a subject
+
+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`.
+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"
+   canon gate promote
+   # ... fix, commit ...
+   canon finding close --change-id c-demo --round 1 --seq 1 \
+     --disposition fixed --resolution-sha "$(git rev-parse HEAD)"
+   canon gate promote
+   ```
+
+3. **One Review per scenario**, by someone other than the evidence actor:
+
+   ```bash
+   canon review add --project-id root --scenario-id world.demo.01 \
+     --reviewer reviewer-2 --actor-id reviewer-2 --role reviewer \
+     --pin "$(git rev-parse HEAD)" --upstream-ref "pr#41"
+   canon gate promote
+   ```
+
+4. **Move the subject**: `canon subject status <id> verifying`, later
+   `shipped`. See `canon-subject`.
+
+## `canon finding add` / `canon finding close`
+
+A Finding's natural key is `(change_id, round, seq)`: the change under
+review, the 1-based review round, and the 1-based index within that
+round. `seq` is never auto-assigned; `finding add` refuses an occupied
+key, because two different findings under one key are two reviewers'
+work collapsed into one identity.
+
+```bash
+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>]
+canon finding close --change-id <c> --round <n> --seq <n> \
+  --disposition fixed --resolution-sha <sha>     # or rejected / deferred / open
+```
+
+Both stage a candidate; `canon gate promote` commits 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.
+
+### Severities
+
+| Severity | Meaning |
+|---|---|
+| `blocker` | Must be resolved before the work is claimed done. With `require_review`, an open blocker on an adopted change fails the gate (`open-blocker`). |
+| `should-fix` | Worth fixing; may be scheduled for later. Never blocks the gate. |
+| `note` | An observation; no obligation. |
+
+Severity is the reviewer's own judgement, never a score canon derives.
+
+### Dispositions
+
+| Disposition | Meaning |
+|---|---|
+| `open` | Raised and not yet dealt with. The default on `finding add`; `finding close --disposition open` reopens. |
+| `fixed` | Fixed by a commit. Requires `--resolution-sha <sha>` naming a commit this repo holds; only `fixed` may carry one. |
+| `rejected` | The reviewer's point was considered and declined. |
+| `deferred` | Accepted, but postponed to later work. |
+
+### How findings fold
+
+Every reader takes the **latest version per natural key**
+`(change_id, round, seq)` — the same fold the report's finding panel
+uses. A blocker raised `open` and later closed `fixed` counts as fixed; a
+fixed finding reopened with `--disposition open` counts as open again.
+
+## `canon review add`
+
+```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>]
+```
+
+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`.
+
+## The `require_review` policy (opt-in)
+
+```yaml
+# .canon/policy.yaml
+spec_coverage:
+  require_evidence: true
+  require_review:                 # absent = nothing changes, byte for byte
+    scope: [verifying, shipped]   # default; [] = every scenario
+    distinct_actor: true          # default
+    block_on_findings: true       # default
+```
+
+`require_review: {}` takes every default.
+
+- **`scope`** — the subject statuses whose scenarios need a review. A
+  scenario is in scope when its `@subject:<id>` subject is in one of
+  them; `[]` means every scenario. It is independent of
+  `spec_coverage.scope`. `spec_coverage.exclude_lanes` also exempts
+  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.
+- **`block_on_findings`** — fail on open blocker findings (below).
+
+A malformed `require_review` (an unknown key, an unknown status, `null`,
+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`.
+
+## How it meets the gate
+
+### `unreviewed-promotion`
+
+An in-scope scenario with no qualifying review:
+
+```
+unreviewed-promotion world.demo.01 — no review record for this scenario; spec_coverage.require_review wants an independent review (`canon review add`) once its subject is claimed done
+```
+
+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
+```
+
+### `open-blocker`
+
+With `block_on_findings`, a Finding whose latest version is severity
+`blocker` and disposition `open`, on a change listed in an in-scope
+subject's `change_ids` (`canon subject adopt`). The subject string is
+`<change_id>#<round>.<seq>`:
+
+```
+open-blocker c-demo#1.1 — open blocker finding by `reviewer-2` on change `c-demo` (subject `demo-subject`): unbounded subprocess wait; fix it and `canon finding close --disposition fixed --resolution-sha <sha>`, or close it as rejected or deferred
+```
+
+Findings on changes no in-scope subject has adopted do not block.
+
+### Review-waiver advisories
+
+A subject moved with `--override-reason` (below) has the exact gaps its
+waiver recorded printed after the violations as advisories; the gate
+stays green for those. A gap the waiver did not record (a blocker raised
+later, a scenario tagged to the subject later) is a violation as usual:
+
+```
+review waivers: 1 advisory(ies) — not failing the gate:
+  waived unreviewed-promotion world.demo.01 — no review record ... [waiver: subject `demo-subject` moved to verifying by `lead`: reviewer out until Monday]
+```
+
+## The status guard
+
+With `require_review` present, `canon subject status <id> <state>`
+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 open-blocker — 1 adopted change(s) checked for open blocker findings
+```
+
+A target status outside the scope prints `skipped unreviewed-promotion —
+`specced` is not in require_review.scope`. A transition into an in-scope
+status with gaps prints the violations, exits 1, leaves the record
+unchanged, and names `--override-reason`.
+
+`--override-reason "<one line>"` waives ONLY `unreviewed-promotion` and
+`open-blocker` — never ship-gate verdict or case gaps, never unreadable
+routing. The new Subject record lists exactly the violations it let
+through:
+`status_override: {to, reason, waived: [{class, subject}], actor: {agent_id}}`
+(`subject` is the scenario id, or `<change_id>#<round>.<seq>` for a
+blocker; actor from `--actor-id`, default `canon`). The command prints
+the `waived ...` lines and `override recorded by `lead` for the N
+violation(s) above: <reason>`. A blank or multi-line reason exits 2. The
+waiver covers only what it recorded, and clears on the subject's next
+status write, so it never outlives the status it was granted for.
+
+Without `require_review`, the guard prints nothing and changes nothing.
+
+## Vocabulary in `canon context`
+
+`canon context` (text and `--json`) carries a top-level `review` section:
+`findingSeverities` (`blocker`, `should-fix`, `note`),
+`findingDispositions` (`open`, `fixed`, `rejected`, `deferred`),
+`reviewFields` (the Review kind's fields), and `requireReview` (the
+active policy summary, or absent). The `spec_coverage` summary appends
+` require_review=(scope=... distinct_actor=... block_on_findings=...)`
+when set. Read it before authoring findings or reviews rather than
+guessing the enums.

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

@@ -87,8 +87,10 @@ canon retrieve --role dev --domain dev --subject subject-domain-loop --k 5
 - **Changes**: adopt imported plan changes under the Subject (see
   [Adopt flow](#adopt-flow)).
 - **Reviews / evidence / divergences**: authored as usual (`canon review
-  add`, `canon gate`, `canon divergence …`) against the Subject's
-  scenarios — the join spine carries them back through `scenario_id`.
+  add`, `canon finding add`, `canon gate`, `canon divergence …`) against
+  the Subject's scenarios and adopted changes — the join spine carries
+  them back through `scenario_id` and `change_id`. See `canon-review`
+  for the finish-a-subject order.
 
 ### 4. Verdicts / trajectories → learn (knowledge out)
 
@@ -98,7 +100,8 @@ this subject and domain — the exact memory step 2 retrieves next time.
 
 ## Status lifecycle + the shipped evidence gate
 
-`canon subject status <id> <state>` performs a policy-gated transition.
+`canon subject status <id> <state> [--override-reason <text>] [--actor-id <id>]`
+performs a policy-gated transition.
 The legal chain:
 
 ```
@@ -141,6 +144,52 @@ empty set; so is one whose `scenario` records route away from the
 gate's rung. Each refusal prints by failure class (`uncovered-cell`),
 exits 1, and the status stays `verifying`. `retired` is not gated.
 
+### The review guard (`spec_coverage.require_review`, opt-in)
+
+When `.canon/policy.yaml` sets `spec_coverage.require_review` (see
+`canon-review`), every status write also runs the review checks and
+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 open-blocker — 1 adopted change(s) checked for open blocker findings
+```
+
+A target outside `require_review.scope` prints `skipped
+unreviewed-promotion — `specced` is not in require_review.scope`. A
+transition INTO an in-scope status with gaps — an owned scenario with no
+qualifying review (`unreviewed-promotion`), or an open blocker finding
+on an adopted change (`open-blocker`) — prints the violations, exits 1,
+leaves the record unchanged, and names `--override-reason`.
+
+```bash
+canon subject status demo-subject verifying \
+  --override-reason "reviewer out until Monday" --actor-id lead
+```
+
+`--override-reason "<one line>"` waives ONLY `unreviewed-promotion` and
+`open-blocker` — never a ship-gate verdict or case gap, never unreadable
+routing. It prints the `waived ...` lines and `override recorded by
+`lead` for the N violation(s) above: <reason>`, and records on the new
+Subject record exactly the violations it let through:
+
+```yaml
+status_override:
+  to: verifying
+  reason: reviewer out until Monday
+  waived:
+    - { class: unreviewed-promotion, subject: world.demo.01 }
+  actor: { agent_id: lead }   # from --actor-id, default `canon`
+```
+
+A blank or multi-line reason exits 2. The waiver is cleared on the
+subject's next status write, so it never outlives the status it was
+granted for. While it stands, `canon gate check` lists the recorded gaps
+as advisories instead of failing; a gap it did not record (a blocker
+raised later, a scenario tagged later) still fails the gate. Without
+`require_review`, nothing is printed and nothing changes.
+
 ## Adopt flow
 
 Planning docs become change/task records via `canon ingest plans` (see

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@journeykit/canon",
-  "version": "0.11.0",
+  "version": "0.12.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.11.0",
-    "@journeykit/canon-core-linux-x64": "0.11.0",
-    "@journeykit/canon-core-win32-x64": "0.11.0"
+    "@journeykit/canon-core-darwin-arm64": "0.12.0",
+    "@journeykit/canon-core-linux-x64": "0.12.0",
+    "@journeykit/canon-core-win32-x64": "0.12.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",