@journeykit/canon 0.9.1 → 0.11.0

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

@@ -51,6 +51,36 @@ diagnostic, at `canon inventory sync`.
 attest it. If you can't, it is a `process` rule, or it is a gap — record
 the gap, do not write the scenario.
 
+## Cases: which path of the behavior is this?
+
+A second, independent axis, tagged `@case:<value>`:
+
+| Case | The scenario specifies |
+|---|---|
+| `happy` | The expected path: valid input, the outcome the user wants. |
+| `failure` | A refusal, an error, a denied or blocked action — what happens when the input is wrong, missing, unauthorized, or stale. |
+| `edge` | A boundary that is neither: empty sets, limits, duplicates, re-runs, ordering. |
+
+A spec can be fully attested and still describe only its golden path.
+Evidence presence cannot see that gap; `require_cases` can:
+
+```yaml
+# .canon/policy.yaml
+spec_coverage:
+  require_evidence: true
+  scope: [building, verifying]
+  require_cases: [failure]
+```
+
+Every feature surface (`<area>.<surface>`) with in-scope scenarios must
+then carry at least one scenario of each listed case, or `canon gate
+check` reports it as `uncovered-cell`, and `canon subject status <id>
+shipped` refuses for a subject that owns such a surface. An untagged
+scenario counts toward its surface but satisfies no case, so an
+untagged corpus reports every surface instead of passing silently. The
+base set comes from `canon.core`; a repo replaces it with its own `case`
+enum, like `lane`.
+
 ## Subject pinning
 
 Every scenario belongs to a Subject (the durable product unit, see
@@ -64,7 +94,9 @@ a scoped gate.
 ```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
+  --subject checkout-core --lane behavior --case happy               # once per behavior
+canon scenario new checkout.cart.04 --title "Adding an out-of-stock item is refused" \
+  --subject checkout-core --lane behavior --case failure             # and its failure path
 canon format specs                                                   # clean?
 canon inventory sync                                                 # index it
 ```
@@ -78,6 +110,7 @@ canon inventory sync                                                 # index it
     # canon: {"schema":1,"at":"2026-09-16T10:02:11Z","actor":{"agent_id":"Main"}}
     @subject:checkout-core
     @lane:behavior
+    @case:happy
     @checkout.cart.01
     Scenario: Adding an item raises the count
       Given an empty cart
@@ -107,9 +140,13 @@ canon inventory sync                                                 # index it
 - **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.
+  invisible to canon — they index nothing. Only `@lane:`, `@case:`, and
+  `@subject:` are read; any other `@name:value` namespace is counted as a
+  diagnostic at sync so you can see it was dropped.
+- **The golden-path-only surface.** Five scenarios, all of the form
+  "doing X works". Nothing says what happens on a missing field, a
+  denied user, a duplicate submit. Write the refusal as its own
+  `@case:failure` scenario; `require_cases` makes the gap a gate failure.
 
 ## Worked example
 

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

@@ -21,7 +21,7 @@ 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. The detail string distinguishes them. Coverage means "a test exists", not "a test passed": even a `Divergent` verdict satisfies the role-cell form. |
+| `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. |
 | `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. |
@@ -63,6 +63,8 @@ an unimplemented or mismatched spec becomes a reported violation.
 spec_coverage:
   require_evidence: true
   scope: [building, verifying]   # optional; omit for the whole corpus
+  exclude_lanes: [process]       # optional
+  require_cases: [failure]       # optional; see Golden-path only below
 ```
 
 - **Unimplemented** — no `EvidenceRecord` carries the scenario's
@@ -78,6 +80,15 @@ spec_coverage:
   set, an untagged scenario is out of scope; with `scope` omitted, every
   scenario is in scope. A tag naming no Subject record is reported as a
   dangling link, never silently skipped.
+- **Golden-path only** (`require_cases`) — every feature surface
+  (`<area>.<surface>`) among the in-scope scenarios must carry at least
+  one scenario tagged `@case:<v>` for each listed value, or the SURFACE
+  is reported (subject `<area>.<surface>`, detail naming the missing
+  case). This is the gap evidence presence cannot see: every scenario
+  attested, none of them specifying a refusal. Untagged scenarios satisfy
+  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.
 
 Two refusals rather than a silent pass, both surfacing as
 `uncovered-cell` on the subject `spec_coverage`:
@@ -93,6 +104,54 @@ 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.
 
+## Experimental: evidence binding (`experimental.evidence_binding`, off by default)
+
+An evidence record is an attestation: canon never runs `--ref`, and it
+never will — it cannot run every language and every agent-driven QA
+tool a team uses. Binding lets a record point at files the team's own
+runner or agent ALREADY produced, so a reviewer (and the gate) can check
+what backed the claim:
+
+```bash
+# any file: a Playwright trace, screenshots, an agent QA log — by sha256
+canon evidence add --scenario-id cart.add.04 --project-id root \
+  --kind agent-qa --ref "stagehand run 7" --role implementer \
+  --artifact test-results/cart-trace.zip
+# a JUnit XML or Cucumber JSON report: also records the matched case + outcome
+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.
+
+Strength, weakest first: `attested` (no attachment) < `artifact` (any
+bound file) < `report` (a parsed report whose case passed). The policy
+decides whether the gate cares:
+
+```yaml
+experimental:
+  evidence_binding:
+    mode: warn          # off (default) | warn | require
+    strength: artifact  # artifact (default) | report
+    case: [failure]     # optional filters — only these scenarios are held
+    lane: [behavior]
+    scope: [verifying]  # subject statuses
+```
+
+`off` checks nothing. `warn` prints the distribution and lists each
+scenario below `strength` as `warn <id>` after the gate result, never
+failing it. `require` reports each as `uncovered-cell`. The latest
+evidence record per scenario decides; scenarios with no evidence are
+`spec_coverage`'s finding, not this one's. A malformed section is a
+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.
+
 ## Effect-aware risk approvals (`risk_tiers`)
 
 `risk_tiers` is absent by default and remains a no-op when absent. When it
@@ -110,11 +169,14 @@ binding. This is still attestation input, not proof of the changed paths;
 run/diff metadata is authoritative when available, and an unavailable
 binding is a gate violation rather than a clean result.
 
-Approval identity is separate from attestation text. `--approval-by` is
-accepted as a verified approval only when it equals a non-empty
-`CANON_ACTOR` environment identity and `--approval-role human` is supplied.
-The record persists that verification bit for replay; arbitrary caller
-strings, empty identities, and `agent` roles never satisfy a risk tier.
+Approval identity is separate from attestation text. An approval counts
+only when it carries a detached SSH signature (`ssh-keygen -Y sign -n
+canon-approval-v1` over `canon evidence approval-payload`'s bytes) that
+verifies against the signers pinned by policy `approval.allowed_signers`,
+with `--approval-role human`. `CANON_ACTOR`, caller-supplied strings, and
+`agent` roles never satisfy a risk tier, and canon never signs on a
+user's behalf.
+
 Malformed `risk_tiers` sections produce a stable `uncovered-cell` policy
 violation (`risk_tiers policy-invalid: ...`) instead of degrading to an
 empty clean map.

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

@@ -42,9 +42,9 @@ Per configured root, in order:
 2. **Scan** — walks `<root>/features/**/*.feature`, pairing each
    `@<area>.<surface>.<nn>` tag with its header label as `title` and a
    `source_digest` (sha256 over the raw `.feature` bytes). `@subject:<id>`
-   → `subject_id`, `@lane:<v>` → `lane` (first tag wins; a second, a
-   malformed value, or a value outside a declared `lane` enum is dropped
-   with a counted, non-fatal diagnostic). Any other `@name:value`
+   → `subject_id`, `@lane:<v>` → `lane`, `@case:<v>` → `case` (first tag
+   wins; a second, a malformed value, or a value outside a declared
+   `lane`/`case` enum is dropped with a counted, non-fatal diagnostic). Any other `@name:value`
    namespace is counted as a diagnostic so a dropped classification is
    visible; plain tags (`@p2`) are ignored. The index derives from the
    `.feature` corpus alone. See `canon-authoring` for the organizing rule.

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

@@ -113,7 +113,16 @@ 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.
+An approval counts only with a detached SSH signature that verifies
+against the signers pinned by `approval.allowed_signers`, and
+`--approval-role human`. `CANON_ACTOR`, arbitrary caller strings, and
+agent roles do not count.
+
+## Experimental: `experimental.evidence_binding`
+
+Off by default. Holds scenario evidence to a minimum strength —
+`artifact` (a file bound by `canon evidence add --artifact`) or `report`
+(a JUnit/Cucumber report whose matched case passed, `--report`) — in
+`mode: warn` (advisories only) or `mode: require` (gate violations),
+optionally narrowed by `case`, `lane`, and subject-status `scope`. See
+`canon-gate` for the full contract.

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

@@ -132,11 +132,14 @@ 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). A Subject with no tagged
-scenario is refused rather than shipped on an 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.
+same last-wins rule `canon gate check` uses). 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
+Subject with no tagged scenario is refused rather than shipped on an
+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.
 
 ## Adopt flow
 

package/package.json

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