criteria-review 0.3.0 → 0.3.2

package/agents/README.md

@@ -15,14 +15,14 @@ The whole protocol is four ideas. Everything in `skills/` is these, spelled out
 
 ### 1. The queue is ordered, and the order is not yours to change
 
-`criteria-review queue` returns what still needs a human decision, most important first: flagged
+`npx criteria-review queue` returns what still needs a human decision, most important first: flagged
 items, then grouped by document with the riskiest documents leading. The page uses the same
 ordering from the same module. Reordering it in conversation leaves the architect looking at two
 different "most important" and unable to tell which is right.
 
 ### 2. Show the scenario, do not summarise it
 
-`criteria-review show <ID>` prints the title, status, persona, flags, intent, the Given/When/Then
+`npx criteria-review show <ID>` prints the title, status, persona, flags, intent, the Given/When/Then
 clauses, and every note. Present all of it, including **an intent line that says it is missing**.
 A scenario whose intent was never sourced is the most dangerous kind, because a test citing it can
 never disagree with the software, and omitting the line makes it look fine.
@@ -35,15 +35,15 @@ requirement.
 Prose in reply to a presented scenario is a note, written verbatim:
 
 ```bash
-criteria-review note <ID> --message "<their words>"
+npx criteria-review note <ID> --message "<their words>"
 ```
 
 Status moves are separate, named, and never taken unasked:
 
 ```bash
-criteria-review accept <ID>                    # what the software SHOULD do
-criteria-review verify <ID> --commit <sha>     # a person watched it happen
-criteria-review reject <ID>                    # back to derived
+npx criteria-review accept <ID>                    # what the software SHOULD do
+npx criteria-review verify <ID> --commit <sha>     # a person watched it happen
+npx criteria-review reject <ID>                    # back to derived
 ```
 
 `verify` resolves the commit from the project under review and reports which one it recorded, so a
@@ -77,14 +77,24 @@ not in a session that can end.
 | `@looknow` | an agent, via `ask` or `flag` | the architect must look at this |
 | `@review` | the architect writing a note | an agent must act on what they wrote |
 
-An agent asks with `criteria-review ask <ID> --message "..."`, which puts the question beside the
+An agent asks with `npx criteria-review ask <ID> --message "..."`, which puts the question beside the
 scenario rather than in a transcript that scrolls away. It reads replies with
-`criteria-review notes`, acts, then runs `criteria-review handled <ID>`, which clears the
+`npx criteria-review notes`, acts, then runs `npx criteria-review handled <ID>`, which clears the
 discussion and hands the item back for re-review.
 
 **Never clear `@review` by hand.** It is the architect's request, and `handled` is the only thing
 entitled to retire it.
 
+### A note on invoking it
+
+Commands here use `npx criteria-review`, which resolves a project's pinned copy first and works
+when there is no package context at all - the situation an agent is usually in.
+
+**A GATE must not use `npx`.** It fetches from the registry when the package is absent, which puts
+a network download inside the check and lets a missing dependency read as a pass. A gate resolves
+`node_modules/.bin/criteria-review`, falls back to `PATH`, and fails when neither exists. See
+`docs/standard/emit-contract.md`.
+
 ### And one standing rule
 
 **A session that edits an acceptance document regenerates before running tests.** Otherwise the

package/agents/skills/claude-code/criteria-lookup/SKILL.md

@@ -17,7 +17,7 @@ open page updates itself, because the server watches the criteria directories.
 ## Looking one thing up
 
 ```bash
-criteria-review show <ID> [project]
+npx criteria-review show <ID> [project]
 ```
 
 Present what it prints, in full, as prose the architect can read without decoding:
@@ -55,7 +55,7 @@ every time, and the whole point is that it does not.
 When the architect answers with prose rather than a command, that prose is the note. Write it:
 
 ```bash
-criteria-review note <ID> [project] --message "<their words>"
+npx criteria-review note <ID> [project] --message "<their words>"
 ```
 
 **Use their words, not a summary.** The note is sourced intent, which is the one thing that cannot
@@ -119,7 +119,7 @@ If the finding is worth keeping - a real contradiction, or a clause nobody can t
 record it. It is the agent's finding, so it goes in as the agent:
 
 ```bash
-criteria-review ask <ID> [project] --message "DRIFT: <clause> is contradicted by <file:line>: <what the code does>" --as <who>
+npx criteria-review ask <ID> [project] --message "DRIFT: <clause> is contradicted by <file:line>: <what the code does>" --as <who>
 ```
 
 That raises `@looknow` rather than `@review`, which is correct: the finding is a question for the
@@ -138,7 +138,7 @@ up. Accepting it is correct even though the software fails it, because `accepted
 intent, not about the implementation:
 
 ```bash
-criteria-review accept <ID> --message "WRITE THE CODE TO MATCH: <what the software does instead, in their words>"
+npx criteria-review accept <ID> --message "WRITE THE CODE TO MATCH: <what the software does instead, in their words>"
 ```
 
 Then say plainly how the gap stays visible: a journey citing this scenario now goes **red**, which
@@ -151,7 +151,7 @@ inferred, or it describes an intention nobody holds. Send it back to `derived`,
 what that status means - written up from the delivered software, describing what it appears to do:
 
 ```bash
-criteria-review reject <ID> --message "WRITE THE TEST TO MATCH THE CODE: <what the software actually does, in their words>"
+npx criteria-review reject <ID> --message "WRITE THE TEST TO MATCH THE CODE: <what the software actually does, in their words>"
 ```
 
 Both raise `@review`, which hands the item to an agent. Report which one was recorded and what
@@ -173,7 +173,7 @@ mid-pass is how a review of seventy-five scenarios becomes an afternoon on the f
 ## Walking the queue
 
 ```bash
-criteria-review queue --limit 10
+npx criteria-review queue --limit 10
 ```
 
 Ordered exactly as the page orders it: flagged items first, then grouped by document with the
@@ -215,11 +215,11 @@ If **you** need the architect's ruling on something and they are not in the conv
 question belongs beside the scenario rather than in a transcript that scrolls away:
 
 ```bash
-criteria-review ask <ID> [project] --message "the question" --as <who>
+npx criteria-review ask <ID> [project] --message "the question" --as <who>
 ```
 
 That raises `@looknow` and puts the question in their queue. Read what came back with
-`criteria-review notes`, act, then `criteria-review handled <ID>` to hand the item back for
+`npx criteria-review notes`, act, then `npx criteria-review handled <ID>` to hand the item back for
 re-review.
 
 ## Ambiguity
@@ -230,7 +230,7 @@ exists to prevent.
 
 ## Related
 
-- `criteria-review guide` and the standard in `docs/standard/` for what the statuses mean and how
+- `npx criteria-review guide` and the standard in `docs/standard/` for what the statuses mean and how
   criteria are written.
-- The visual tool (`criteria-review here`) for a long pass beside the recordings, which is still
+- The visual tool (`npx criteria-review here`) for a long pass beside the recordings, which is still
   the better surface when there is video to watch.

package/bin/criteria-review.js

@@ -17,6 +17,7 @@ import { ejectStandard } from '../src/standard.js';
 import { isUntracked, needsReview } from '../src/parse.js';
 import { addNote, setStatus, ACTOR_ARCHITECT } from '../src/write.js';
 import { orderQueue } from '../public/queue-order.js';
+import { STANDARD_VERSION } from '../src/version.js';
 import { buildModel, RENDERERS } from '../src/emit.js';
 import { scanAll as scanAllRoots } from '../src/scan.js';
 import {
@@ -200,6 +201,7 @@ function usage() {
   criteria-review flag <ID>           mark it LOOK NOW
   criteria-review unflag <ID>         clear LOOK NOW
   criteria-review standard eject <dir> copy the standard into this project to own it
+  criteria-review version             package and standard version (also --version)
   criteria-review guide [skill]       print the agent instruction set
   criteria-review queue               what needs a decision here, most important first
                                         --limit <n>       how many to list (default 10)
@@ -561,6 +563,19 @@ async function main() {
 
   if (cmd === 'help' || args._.includes('--help') || args._.includes('-h')) return usage();
 
+  // A gate pins an exact version, so it must be able to report which version ran. Without
+  // this an unrecognised flag fell through to STARTING THE REVIEW SERVER and died on
+  // EADDRINUSE - a version query that boots a web server is the wrong answer twice over.
+  if (cmd === 'version' || args._.includes('--version') || args._.includes('-v')) {
+    const pkg = JSON.parse(
+      await readFile(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')
+    );
+    // Both numbers, because they answer different questions: the package is what you
+    // pinned and downloaded, the standard is what your criteria conform to.
+    console.log(`criteria-review ${pkg.version} (standard ${STANDARD_VERSION})`);
+    return;
+  }
+
   if (cmd === 'add') {
     const path = resolve(args._[1] ?? process.cwd());
     const name = args._[2] ?? basename(path);
@@ -829,6 +844,15 @@ async function main() {
 
   if (cmd === 'list') return cmdList(roots);
 
+  // Anything that looks like a command or a flag but was not recognised is an error, not
+  // an instruction to open the review UI. The old fallthrough turned a typo - or a flag a
+  // newer version understands - into a server start, which in a pipeline is a hang and on
+  // a desk is EADDRINUSE from the server already running.
+  if (cmd !== undefined || args._.some((a) => a.startsWith('-'))) {
+    const what = cmd ?? args._.find((a) => a.startsWith('-'));
+    throw new Error(`unknown command "${what}". Run: criteria-review help`);
+  }
+
   const cfg = await loadConfig();
   const mediaRoot = await resolveMediaRoot(cfg.mediaRoot);
   // Re-read the config per request so `here` takes effect without a restart.

package/docs/help/01-getting-started.md

@@ -33,7 +33,7 @@ Everything else in the tool exists to make one of those three steps cheaper.
 From inside any working tree:
 
 ```bash
-criteria-review here
+npx criteria-review here
 ```
 
 That registers the tree, starts the server if it is down, and opens the page on this project.
@@ -43,7 +43,7 @@ repository without checking anything first.
 Give it a name when the directory name is not distinctive:
 
 ```bash
-criteria-review here . playwright-worktree
+npx criteria-review here . playwright-worktree
 ```
 
 Several trees can be registered at once, **including two checkouts of the same repository**. A
@@ -112,19 +112,19 @@ The loop closes like this, and each step hands the item to exactly one side:
 
 1. A session asks a question beside the scenario it is about:
    ```bash
-   criteria-review ask CO-TYPES-006 myproject --message "Blank cell, or the word none?" --as claude
+   npx criteria-review ask CO-TYPES-006 myproject --message "Blank cell, or the word none?" --as claude
    ```
    That writes the question as a note and raises `@looknow`.
 2. You answer in the same pane by writing a note. That raises `@review` and clears `@looknow`.
-3. The session reads it with `criteria-review notes`, acts, and runs
-   `criteria-review handled CO-TYPES-006`, which removes the discussion and raises `@looknow` so
+3. The session reads it with `npx criteria-review notes`, acts, and runs
+   `npx criteria-review handled CO-TYPES-006`, which removes the discussion and raises `@looknow` so
    the item comes back to you for re-review.
 
 **Acting on a flagged scenario clears the flag.** Accepting it, marking it verified, sending it
 back, writing a note - each one is you looking, so none of them leaves a badge behind demanding
 attention you have already given.
 
-There is also `criteria-review push`, which changes what an open page is showing and never
+There is also `npx criteria-review push`, which changes what an open page is showing and never
 touches disk. Use it when someone is at the screen; use a flag when the finding should wait for
 the next review pass.
 
@@ -133,8 +133,8 @@ the next review pass.
 The last step, and the one that stops the criteria and the tests drifting apart:
 
 ```bash
-criteria-review generate . --out tests/e2e/support/scenarios.generated.ts
-criteria-review generate . --out tests/e2e/support/scenarios.generated.ts --check
+npx criteria-review generate . --out tests/e2e/support/scenarios.generated.ts
+npx criteria-review generate . --out tests/e2e/support/scenarios.generated.ts --check
 ```
 
 A journey's step names are supposed to be the scenario's own Given/When/Then wording. Typing
@@ -152,10 +152,10 @@ Full detail in **The emit contract**, and the step-by-step in **Adopting the sta
 ## Housekeeping
 
 ```bash
-criteria-review status      # exits 1 when down, 0 when up
-criteria-review list        # a summary in the terminal, touches nothing
-criteria-review projects    # what is registered, and where
-criteria-review stop | restart
+npx criteria-review status      # exits 1 when down, 0 when up
+npx criteria-review list        # a summary in the terminal, touches nothing
+npx criteria-review projects    # what is registered, and where
+npx criteria-review stop | restart
 ```
 
 The server exits on its own after two hours with no page open, so there is nothing to remember to

package/docs/standard/emit-contract.md

@@ -11,13 +11,13 @@ bump rather than quietly. See `../decisions.md` D-003, D-004, D-005.
 ```bash
 # Write the artefact. The consumer's package script is where this lives, so it travels
 # with the repository and works on a machine that has never registered anything.
-criteria-review generate . --out tests/e2e/support/scenarios.generated.ts
+npx criteria-review generate . --out tests/e2e/support/scenarios.generated.ts
 
 # Verify it matches the documents, change nothing, exit non-zero if it does not.
-criteria-review generate . --out tests/e2e/support/scenarios.generated.ts --check
+npx criteria-review generate . --out tests/e2e/support/scenarios.generated.ts --check
 
 # The neutral artefact, for a consumer that is not TypeScript.
-criteria-review generate . --out build/scenarios.json --format json
+npx criteria-review generate . --out build/scenarios.json --format json
 ```
 
 `--format` defaults from the output extension.
@@ -46,6 +46,33 @@ Three places, each doing a different job:
 tool is needed to regenerate and to verify, never to compile. A build that could not run without
 a locally-installed personal tool would be an unacceptable dependency for a project.
 
+### Resolving the binary in a gate, which is NOT `npx`
+
+A gate must resolve the project's own pinned copy, fall back to whatever is on `PATH`, and
+**fail loudly when neither exists**:
+
+```sh
+BIN="$(git rev-parse --show-toplevel)/<pkg-dir>/node_modules/.bin/criteria-review"
+[ -x "$BIN" ] || BIN="$(command -v criteria-review || true)"
+[ -n "$BIN" ] || { echo "criteria-review not installed; the criteria gate cannot run" >&2; exit 1; }
+"$BIN" generate . --out ... --check
+```
+
+**Do not use `npx` here.** It fetches from the registry when the package is absent, which puts a
+network download inside the gate and lets a missing devDependency read as a pass - the check
+appears to run, against a version nobody pinned. `npx` is right for ad-hoc use and for an agent
+that may have no package context at all; it is wrong for anything whose job is to fail.
+
+The same reason rules out a bare `command -v criteria-review` guard: a project that pinned the
+tool as a devDependency has no such binary on `PATH`, so the guard skips the gate on exactly the
+machine that configured it correctly.
+
+**Report the version the gate ran**, so a failure names it:
+
+```sh
+"$BIN" --version    # criteria-review 0.3.2 (standard 1.1.2)
+```
+
 ## What is emitted
 
 Only scenarios that can be cited. A scenario with no id or no status is excluded, because

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "criteria-review",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "private": false,
   "description": "Review acceptance criteria across projects, and generate the scenario clauses your tests cite.",
   "license": "MIT",