@journeykit/canon 0.9.1 → 0.10.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`:

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-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.10.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.10.0",
+    "@journeykit/canon-core-linux-x64": "0.10.0",
+    "@journeykit/canon-core-win32-x64": "0.10.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",