@journeykit/canon 0.26.0 → 0.27.0

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

@@ -58,21 +58,19 @@ bytes no longer match the approved digest, or the approval cannot be read,
 the gate fails closed: the violation is reported and the exit is `1` (see
 `canon-policy`).
 
-Before it reads the scenario index, the gate rebuilds any stale part of
-it from the changed `.feature` files (the same code `canon inventory
-sync` runs) and says so in one stderr line, silent when the index is
-fresh:
-
-```
-canon gate check: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
-```
-
-A root that fails to sync (format violations, a duplicate id) is named
-instead, ending ``NOT refreshed: root `x` (N format violation(s), 0 sync
-error(s)) — `canon inventory sync` lists them``, and the gate fails
-closed: it adds `uncovered-cell <root> — the scenario index for spec root
-`<root>` is stale and could not be refreshed (…); `canon inventory sync`
-lists the problems to fix` and exits 1, since the index it would grade
+The gate is a read command: it writes nothing. A scenario index that is
+stale (a `.feature` file added, edited or deleted since the last sync) is
+graded as the refresh would leave it, built in memory from the changed
+files with the code `canon inventory sync` runs; the index on disk is
+brought up to date by the next command that writes (`canon evidence add`,
+`canon review add`, `canon subject status`) or by `canon inventory sync`.
+It prints no refresh line.
+
+A root that fails to sync (format violations, a duplicate id) cannot be
+graded in memory either, and the gate fails closed: it adds
+`uncovered-cell <root> — the scenario index for spec root `<root>` is
+stale and could not be refreshed (…); `canon inventory sync` lists the
+problems to fix` and exits 1, since the index it would grade
 does not hold the edits. The `verifying → shipped` guard refuses with
 the same violation, and `canon status` lists the sync as its only step.
 Fix what the sync lists and run the gate again. See `canon-storage`

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

@@ -6,21 +6,25 @@ records every downstream stage joins against.
 
 ## You rarely run it yourself
 
-Since 0.16 the commands that read the index refresh it first:
-`canon status`, `canon gate check`, `canon evidence add`,
-`canon review add` and `canon subject status` index added, edited and
-deleted `.feature` files themselves, with the same code this command runs,
-scoped to the changed files, and say so in one stderr line:
+Since 0.16 the commands that read the index see added, edited and deleted
+`.feature` files without a sync step. `canon evidence add`, `canon review
+add` and `canon subject status` refresh the index on disk first, with the
+same code this command runs, scoped to the changed files, and say so in one
+stderr line:
 
 ```
-canon status: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
+canon evidence add: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
 ```
 
+`canon status` and `canon gate check` are read commands and write nothing:
+they grade the index as that refresh would leave it, built in memory, and
+print no line.
+
 So the working loop has no sync step and no `canon format` step: write the
 scenario (`canon scenario new` writes it format-clean) and run the next
 command. Run `canon inventory sync` when:
 
-- a reader prints `NOT refreshed` — a root has a format violation (a
+- a command prints `NOT refreshed` — a root has a format violation (a
   hand-written `Feature:`/`Scenario:` header with no `# canon:` provenance
   comment, an emptied file, …) or a duplicate id, so its files were not
   indexed. `canon gate check` then fails (`uncovered-cell <root>`),
@@ -57,7 +61,7 @@ and the openspec source `canon init` wrote is removed only after every
 pointer brief is written and nothing unread is left under
 `openspec/changes/` (each unread directory is named).
 
-The reader's refresh treats a file as stale when its latest index
+The refresh treats a file as stale when its latest index
 generation has another `source_digest` or `scenario_digest`. A
 generation written before 0.15 has no `scenario_digest`, so a repo that
 kept an old index gets it rewritten on the first read.
@@ -68,7 +72,7 @@ kept an old index gets it rewritten on the first read.
 author .feature corpus (canon scenario new)
         │
         ▼
-scenario index                  # refreshed by every reader; `canon inventory sync` rebuilds it
+scenario index                  # refreshed by the writers; `canon inventory sync` rebuilds it
         │
         ▼
 canon review add                # attests a review — see canon-inventory downstream / canon-gate

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

@@ -272,21 +272,27 @@ fails those commands (exit `1`), and `canon init --check-config` reports
 
 `canon inventory sync` materializes one `Scenario` record per
 `(project_id, scenario_id)` under `.canon/ledger/kind=scenario/`. The
-index is derived — a pure function of the `.feature` files — so the
-commands that read it rebuild it first: `canon gate check`, `canon
-status`, `canon subject status`, `canon review add` and `canon evidence
-add`. The index is stale when a `.feature` file holds a scenario with no
-live index record, or one whose recorded source digest differs from the
-file's current bytes, or when the index holds a scenario of a spec root
-that no `.feature` file of it declares any more. The reader then runs
-`canon inventory sync`'s code on the changed files (validation still
-covers the whole root) and prints one stderr line:
+index is derived — a pure function of the `.feature` files. The index is
+stale when a `.feature` file holds a scenario with no live index record,
+or one whose recorded source digest differs from the file's current bytes,
+or when the index holds a scenario of a spec root that no `.feature` file
+of it declares any more.
+
+The commands that write records (`canon subject status`, `canon review
+add` and `canon evidence add`) rebuild a stale index on disk first: they
+run `canon inventory sync`'s code on the changed files (validation still
+covers the whole root) and print one stderr line:
 
 ```
-canon status: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
+canon evidence add: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
 ```
 
-A deleted scenario is not erased: `canon inventory sync` — and a reader's
+The commands that only read (`canon gate check`, `canon status`) write
+nothing: they grade a stale index as the refresh would leave it, built in
+memory, and print no refresh line. `canon query --kind scenario` and the
+report panels read the index on disk as it is.
+
+A deleted scenario is not erased: `canon inventory sync` — and a writer's
 refresh, identically — appends a tombstone, a new generation of its
 record with `removed: true`. The gate, `canon status`, `canon query` and
 the report panels then treat it as absent; re-adding the scenario writes
@@ -294,7 +300,7 @@ a live generation that supersedes the tombstone. A root that fails to
 sync writes no tombstone either.
 
 ```
-canon status: refreshed the scenario index from 1 scenario(s) no longer in any feature file (cart.pay.01): 1 record(s) written
+canon evidence add: refreshed the scenario index from 1 scenario(s) no longer in any feature file (cart.pay.01): 1 record(s) written
 ```
 
 `canon inventory sync` and every refresh hold an OS file lock on
@@ -303,17 +309,16 @@ index one change twice; a refresh that waited checks staleness again and
 is silent if another run already did the work. The lock is released when
 its holder exits, however it exits, so it never goes stale; a writer
 gives up after 30 s with a message naming the file (`canon inventory
-sync` exits `2`; a reader skips the refresh and still runs).
+sync` exits `2`; a writer's refresh is skipped and the command still runs).
 
 A fresh index prints nothing. A root that fails to sync (format
 violations, a duplicate id) is named and left as it was, and the command
 still runs; `canon gate check` then fails with `uncovered-cell <root>`,
 the `verifying → shipped` guard refuses, and `canon status` lists only
-`canon inventory sync`, while the reporting readers (`query`, `context`)
-keep only this line:
+`canon inventory sync`:
 
 ```
-canon gate check: found the scenario index stale for 1 changed feature file(s) (…): 0 record(s) written; NOT refreshed: root `root` (2 format violation(s), 0 sync error(s)) — `canon inventory sync` lists them
+canon evidence add: found the scenario index stale for 1 changed feature file(s) (…): 0 record(s) written; NOT refreshed: root `root` (2 format violation(s), 0 sync error(s)) — `canon inventory sync` lists them
 ```
 
 Nothing is written in a directory without `canon.yaml`. `canon inventory

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

@@ -21,11 +21,13 @@ authored in one place:
   adopt`.
 - **Scenarios**: the `@subject:<id>` tag on each Gherkin scenario,
   indexed onto `Scenario.subject_id` by the scenario index (rebuilt by
-  `canon inventory sync`, and refreshed by every command that reads it).
+  `canon inventory sync`, and refreshed on disk by the commands that write
+  records; `canon status` and `canon gate check` read it as the refresh
+  would leave it, without writing).
   The Subject record carries no scenario list — the spec corpus is the
   only source, and the Subjects report panel, `spec_coverage.scope`, and
   the shipped gate all read it from there. To link a scenario, tag it;
-  the next `canon status` or `canon gate check` indexes the tag. There is
+  the next `canon status` or `canon gate check` reads the tag. There is
   no subject-side command for it.
 
 ## The 4-step loop
@@ -609,9 +611,9 @@ uses, so status and the gate cannot disagree about a gap:
   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 and `.feature` scenarios but no
-  scenario records → `canon inventory sync` (status refreshes the index
-  itself first, so this means the refresh refused on a format violation
-  or a duplicate id, which the sync names). Then per subject, verifying
+  scenario records → `canon inventory sync` (status reads the index as a
+  refresh would leave it, so this means the refresh would be refused on a
+  format violation or a duplicate id, which the sync names). Then per subject, verifying
   first, then building, specced, proposed, shipped: an unapproved brief
   (building and later, and proposed once its change has a brief)
   → the human step below, which is then the subject's

package/package.json

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