criteria-review 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyley Harris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,299 @@
+# criteria-review
+
+Review acceptance criteria across projects. Surfaces the scenarios that still need a human
+decision, lets you annotate them, and writes the outcome back into the source documents.
+
+## Why
+
+Acceptance criteria written up from delivered software describe what the software *appears* to
+do. Until someone confirms that is what it *should* do, a test citing them proves the test
+runs, not that the requirement is right. The gap between those two states is where defects
+hide, and making it visible is most of the value.
+
+That only pays off if reviewing is cheap. This tool exists so the review is a queue you can
+work through rather than a repo you have to go reading.
+
+## Two roles
+
+The tool assumes two participants and names them throughout:
+
+- **The architect** is the person who decides what the software *should* do. Only they can
+  accept a scenario, and only their own actions clear a request for their attention.
+- **An agent** is a working session, human or AI, that writes criteria up from the software,
+  runs the journeys, and acts on what the architect decides.
+
+The distinction is load-bearing rather than decorative. The two attention flags route an item
+by which side raised it, so it always sits with exactly one of them and neither keeps picking
+up the other's work.
+
+## The standard
+
+**This repository owns the acceptance-criteria standard.** It lives in
+[`docs/standard/`](docs/standard/) and defines how criteria are written, confirmed, cited by
+tests and gated. Consumer projects conform to it and hold pointers rather than restatements; a
+mirror cannot know its original changed, so it rots into a contradiction. See
+[`docs/decisions.md`](docs/decisions.md) D-001.
+
+The test for where a sentence lives: **does it stay true if the product is swapped for a
+different one?** If yes it belongs to the standard; if no it stays with the project.
+
+## The format
+
+````markdown
+```gherkin
+@ONB-ADMIN-001 @status:verified @verified:2026-08-01 @commit:a1b2c3d4 @persona:Administrator
+Scenario: The first administrator must set their own password before using the system
+  Given a freshly installed system with no data beyond the bootstrap administrator
+  When the administrator signs in with the password the system shipped with
+  Then they are required to set a new password before reaching the application
+```
+````
+
+| Tag | Meaning |
+| --- | --- |
+| `@<AREA>-<THING>-<NNN>` | Stable ID. The join between the document, the journey that proves it, and the API tests that cover it. |
+| `@status:proposed` | Written at planning, before the software exists. A proposal, not a description. |
+| `@status:derived` | Written up from delivered software. Describes what it appears to do. |
+| `@status:verified` | A human watched the software do it. Carries `@verified:` and `@commit:`. |
+| `@status:accepted` | Confirmed as what the software *should* do. |
+| `@persona:<actor>` | Whose point of view the scenario is written from. |
+
+An optional provenance comment records where the intent came from, which is what makes a review
+pass affordable - attention goes to the inferred ones instead of spreading evenly:
+
+```markdown
+<!-- intent: docs/pos-architecture.md:214 -->
+<!-- intent: INFERRED from implementation - needs confirmation -->
+```
+
+Scenarios with **no ID or no status still parse** and are reported as `untracked`. They are the
+backlog, and dropping them would hide it.
+
+## Recordings
+
+Reading the criteria tells you the test says what the scenario says. Only watching the software
+tells you the scenario describes something that can actually happen - and that is the failure a
+side-by-side comparison cannot catch, because a scenario and its test can agree perfectly and
+both be wrong.
+
+**The convention: one file per scenario, named for it, in a fixed directory. A new run replaces
+the old file.**
+
+```
+<project>/qa/videos/<SCENARIO-ID>.webm
+<project>/qa/videos/LOCK-UNLOCK-001.webm
+```
+
+The producing side owns this. Playwright's own output is date- and hash-shaped
+(`test-results/<sanitised-title>/video.webm`), which is fine for a CI artefact and wrong for
+something a person opens repeatedly: the path changes every run, old recordings pile up, and
+"the video for this scenario" stops being a question with one answer. A reel step should move
+its recording to the fixed name when it finishes.
+
+The directory sits **inside the project**, which is what ties a recording to its workspace: a
+worktree filming its own branch writes into its own tree, and two worktrees cannot overwrite
+each other's footage. Recordings are large binaries and belong in `.gitignore`.
+
+Override the location per project in the config:
+
+```json
+{ "projects": [{ "name": "storefront", "path": "...", "videoDir": "ui/qa-videos" }] }
+```
+
+If no named file exists, the tool falls back to scanning `test-results/` and friends for a path
+containing the scenario ID, and labels the result **matched, not named**. That keeps it useful
+against suites that have not adopted the convention, while making clear that a fuzzy match is a
+guess rather than evidence.
+
+Filter the queue by `has recording`, `recording (named)`, or `no recording`. The player supports
+seeking and fullscreen (`f`).
+
+## Install
+
+No dependencies and no build step. Node 20+.
+
+```bash
+git clone https://github.com/KyleyHarris/criteria-review.git
+cd criteria-review
+npm link          # puts `criteria-review` on your PATH
+```
+
+## Use
+
+From whatever tree you are working in:
+
+```bash
+criteria-review here
+```
+
+Registers this tree, starts the server if it is down, and shows this project. One
+verb rather than three, and idempotent, so it is safe to run on entering a repo.
+
+```bash
+criteria-review here . playwright-worktree   # name it when the directory is not distinctive
+criteria-review status                        # exits 1 when down
+criteria-review stop | restart
+criteria-review list                          # terminal summary, touches nothing
+criteria-review projects | add | remove
+```
+
+Several trees can be registered at once, **including two checkouts of the same
+repo**. A worktree and its main clone are separate entries with separate counts,
+which is how you see what a branch adds. They share one master video library,
+correctly, because the recordings are of the same product.
+
+### Lifetime
+
+The server exits on its own after `--idle` minutes with no page open (default 120,
+`0` disables). Tying it to an editor or agent session would be worse: several
+sessions and tabs can be open at once, so the first to end would kill a server
+another is using, and reference-counting sessions leaks a count on every abnormal
+exit. Use is the honest signal, and restarting is cheap.
+
+### Driving it from a session
+
+```bash
+criteria-review push --message "..." --filter status=proposed \
+                     --highlight A,B --focus A --in <project>
+criteria-review focus <ID> [project]
+criteria-review refresh
+criteria-review flag <ID> [project] | unflag <ID> [project]
+criteria-review ask <ID> [project] --message "..." [--as name]
+criteria-review notes                         # what the architect has written back
+criteria-review handled <ID> [project]        # acted on it; hand the item back
+```
+
+`ask` writes the question as a note beside the scenario and raises `@looknow`, so the
+architect answers where the thing being asked about is, rather than in a chat window
+somewhere else. `flag` says "look at this" and carries no words; `push` carries words
+and evaporates on reload. Neither can ask a question that is still there an hour later.
+
+Push is transient - it changes what a page shows, never disk. `@looknow` is the
+durable channel, because it lives in the document and survives a reload.
+
+`notes` is the only channel that runs server to session, and it is a pull: push
+reaches a browser, not an agent, so without it a session could discover the
+architect's feedback only by accident. Run it when you enter a repo. It prints every
+outstanding note and every scenario tagged `@review`.
+
+Projects are registered once in `~/.config/criteria-review/config.json`, so the command works
+from any directory. With nothing registered it falls back to the current directory.
+
+Criteria are found by convention: any `.md` file under an `acceptance/` directory (or `ui-qa/`,
+a recognised legacy alias). `README.md` files in those directories are skipped, because they
+document the format and their examples are not real criteria.
+
+### Generating scenarios for a test suite to cite
+
+```bash
+criteria-review generate . --out tests/e2e/support/scenarios.generated.ts
+criteria-review generate . --out tests/e2e/support/scenarios.generated.ts --check
+criteria-review generate . --out build/scenarios.json --format json
+```
+
+A journey's step names must be the scenario's own Given/When/Then wording. Typing those clauses
+into the test achieves that on the day it is written and makes two copies with nothing detecting
+an edit to either. Generating them instead means a reworded clause, a skipped clause, an invented
+step and a renamed id are all **compile errors** on the consumer's side rather than silent
+divergence.
+
+Write and `--check` are separate on purpose: a gate that silently regenerated would hide exactly
+the drift it exists to catch. The generated file is committed, so a consumer builds and tests
+without this tool present.
+
+Full contract: [`docs/standard/emit-contract.md`](docs/standard/emit-contract.md).
+
+### In the UI
+
+`j`/`k` move through the queue, `a` accepts, `v` marks verified, `n` adds a note, `f` fullscreens
+the recording, `r` reloads, `/` filters. Every action writes straight to the source markdown.
+
+Notes open a multi-line editor rather than a one-line box, because the architect is discussing an
+item, not labelling it. They are rendered back in the detail pane with their author and date, and
+"Mark handled" retires them once the discussion is closed. A note that is written and never shown
+again is indistinguishable from no note.
+
+The page updates itself when the documents change on disk. That is not for its own writes, which
+already refresh the page that made them: it is for a DIFFERENT session editing the same files. An
+agent working in a repo can write `@looknow` on a scenario and it appears in the open queue,
+without the reviewer knowing to press reload. A flag nobody sees is the same as no flag.
+
+Server-sent events, watching only the directories that hold criteria. The selection is preserved
+by scenario identity rather than position, because an external edit can reorder the queue and
+restoring by position would move the reviewer onto a different scenario than the one they were
+reading.
+
+### Attention, in both directions
+
+Two flags, because one cannot say *whose* attention is owed and each side would keep picking up
+the other's items:
+
+| Flag | Raised by | Means |
+| --- | --- | --- |
+| `@looknow` | an agent: the tag by hand, `criteria-review flag`, or asking a question | the architect must look at this |
+| `@review` | the architect saving a note | an agent must act on what they wrote |
+
+**A note is a message, and the author decides which way it travels.** The architect's note raises
+`@review` and hands the item to an agent; an agent's note is a question and raises `@looknow`,
+handing it back. Routing on the author rather than on the act of writing is what stops the loop
+stalling: a flag that pointed at the side that wrote it would leave both believing the item was
+with the other.
+
+So the loop closes: an agent asks with `criteria-review ask`, which writes the question and raises
+`@looknow`; the architect answers in the same pane, which raises `@review` and clears `@looknow`;
+the agent reads it with `criteria-review notes`, acts, and runs `criteria-review handled <ID>`,
+which removes the discussion and raises `@looknow` so the item returns for re-review. Each step
+hands the item to exactly one side, and the tag line always says which.
+
+Add a bare `@looknow` to a scenario's tag line:
+
+```gherkin
+@ONB-MEMBER-001 @status:derived @persona:Administrator @looknow
+```
+
+That is the whole mechanism. An agent already editing these documents needs no API. Flagged
+scenarios jump the document grouping and show a LOOK NOW badge, because grouping optimises a
+steady review pass and a flag means someone wants eyes on it before that pass arrives. Filter to
+them with the status dropdown.
+
+**Acting on a flagged scenario clears the flag.** Accepting it, marking it verified, sending it
+back to derived, writing a note or clearing notes all answer the request, because each one is the
+architect looking. A flag that had to be dismissed separately would survive the action that
+answered it, and a queue that keeps presenting items already dealt with teaches you to ignore the
+one badge meant to jump it. The button is still there for a scenario you want to clear without
+otherwise touching. Only the architect's own actions clear it: an agent writing to the same
+scenario cannot retire a flag it raised, which is what lets `handled` hand an item back.
+
+## Writes
+
+Review state lives in the criteria files, not in a sidecar database. Your notes are sourced
+intent, which is the one thing that cannot be reverse-engineered later, so it belongs in git
+next to the scenario it annotates.
+
+Writes are surgical: one tag line, or one inserted comment, and every other byte left alone.
+After writing, the file is re-parsed and the intended change asserted; a write that cannot
+prove it did what it claimed restores the file and reports an error.
+
+The server binds to loopback only. It reads and writes your documents and is not something to
+expose on a network interface.
+
+## Tests
+
+```bash
+npm test
+```
+
+45 tests over the parser, the write path and the clause generator, with no test dependencies
+beyond Node's own runner.
+
+The write path is the risky part, so its tests were proved able to fail rather than merely
+written: mutating the scenario resolver to return the wrong scenario turns two of them red, and
+restoring it returns the suite to green. A test never observed failing is an untested test.
+
+## Licence
+
+MIT. See [`LICENSE`](LICENSE).
+
+The standard in [`docs/standard/`](docs/standard/) is covered by the same licence: use it,
+adapt it, instantiate it for your own domain. What it deliberately does not carry is any
+project's own instance data, which stays with that project.

package/agents/README.md

@@ -0,0 +1,123 @@
+# Agent instructions
+
+Instruction sets for an AI assistant working with this tool, and ready-made packaging for the
+harnesses that can load them directly.
+
+**Take these into your own system.** They are written to be copied, not depended on: nothing here
+imports anything, and an assistant that has read the protocol below can drive the tool from any
+harness that can run a command.
+
+---
+
+## What an assistant needs to know
+
+The whole protocol is four ideas. Everything in `skills/` is these, spelled out for one harness.
+
+### 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
+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
+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.
+
+A paraphrase is the reviewer confirming your rewrite rather than the criterion. The wording is the
+requirement.
+
+### 3. Their words are the note; their decision is the status
+
+Prose in reply to a presented scenario is a note, written verbatim:
+
+```bash
+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
+```
+
+`verify` resolves the commit from the project under review and reports which one it recorded, so a
+verification is a word rather than a hash hunt. Never take it because a scenario looks plausible:
+it asserts something about a person's own actions.
+
+**When a scenario and the software disagree, the reviewer says which side is wrong.** That is the
+case the standard exists to surface, and neither answer is a rejection. Put it to them as the WORK rather than as a verdict: **write the code to match this criterion**, or
+**write the test to match the existing code**. The first keeps the criterion and `accept`s it -
+`accepted` is a claim about intent, not implementation, so a journey citing it then goes red and
+the defect surfaces in CI rather than in a list somebody has to remember. The second `reject`s it
+back to `derived`, which is precisely what that status means: written up from the delivered
+software. Both carry a note naming the work. Never pick between those two on their behalf; both artefacts are
+self-consistent, so nothing you can read settles it.
+
+**Checking a scenario against the source is evidence, not a verdict.** Report each `Then` clause as
+supported, contradicted, or untraceable, with `file:line`, and say "read, not run" in those words -
+citing a line proves a line was read, and only running the software proves the system does it.
+Never promote a status off a code read: not `verified`, which claims a person watched it, and not
+`accepted`, which is a claim about intent that the implementation has no standing to settle. A
+finding worth keeping goes in as the agent's, via `ask`, which raises `@looknow` - it is a question
+for the architect, not an instruction for an agent.
+
+Write each answer **immediately**, not in a batch at the end. Review state lives in the documents,
+not in a session that can end.
+
+### 4. Two flags, and each hands the item to exactly one side
+
+| Flag | Raised by | Means |
+|---|---|---|
+| `@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
+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
+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.
+
+### And one standing rule
+
+**A session that edits an acceptance document regenerates before running tests.** Otherwise the
+suite is proving the previous requirement. See `docs/standard/emit-contract.md`.
+
+---
+
+## Absorbing the packaged skills
+
+`skills/claude-code/` holds ready-made skills. Two ways in, and the difference matters:
+
+```bash
+# Copy: portable, and yours to edit. Updates to this repo do not reach it.
+cp -R agents/skills/claude-code/criteria-lookup ~/.claude/skills/
+
+# Link: stays current with the tool. Machine-specific, so it is not something to commit
+# into a config repo that has to work on another machine.
+ln -s "$PWD/agents/skills/claude-code/criteria-lookup" ~/.claude/skills/criteria-lookup
+```
+
+On a different harness, read the skill as prose and express it in whatever form that harness takes
+- a system prompt, a tool description, a rule file. The commands are the contract; the packaging is
+not.
+
+## What is here
+
+| Skill | For |
+|---|---|
+| [`skills/claude-code/criteria-lookup`](skills/claude-code/criteria-lookup/SKILL.md) | Looking a scenario up and answering it in conversation, and walking the queue one at a time |
+
+## What deliberately is not here
+
+**Anything about how a particular person likes to work.** When to interrupt them, how large a
+review batch they want, which projects they have registered, where their repositories live. That
+belongs in their own configuration, not in a tool other people use, or it reads as normative for
+everyone who adopts this.

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

@@ -0,0 +1,236 @@
+---
+name: criteria-lookup
+description: Look up an acceptance scenario and answer it in conversation, without opening the review tool's page. Presents the scenario, its intent and any notes, takes your reply as the note, and offers accept / verify / send back. Also walks the whole queue one at a time, most important first, with continue or stop between each. Use when the architect says "look up <ID>", "what do the criteria say about X", "show me that scenario", "let's do a review pass", "walk the queue", "what needs my decision", or replies to a presented scenario with prose rather than a command.
+---
+
+# Look up and answer criteria in conversation
+
+The visual tool is the right surface for a long review pass beside the recordings. This is the
+other one: a single question mid-task, or a walk through the queue by voice, where opening a page
+and finding the scenario costs more than the answer is worth.
+
+**Everything here writes straight into the source document.** No browser, no running server. An
+open page updates itself, because the server watches the criteria directories.
+
+---
+
+## Looking one thing up
+
+```bash
+criteria-review show <ID> [project]
+```
+
+Present what it prints, in full, as prose the architect can read without decoding:
+
+- the id, title and where it lives
+- the status, persona and any flags
+- **the intent line, always, including when it is missing** - print "not sourced" rather than
+  omitting it. An unsourced scenario is the most dangerous kind, and silence reads as fine
+- the Given / When / Then clauses verbatim
+- every note, with its author and date
+
+Then offer the choices as a **numbered menu**, always in the same order, so answering is a
+keypress rather than a sentence:
+
+```
+1  accept        - this is what the software should do
+2  verify        - you watched it happen
+3  reject        - send it back to derived
+4  code to match - write the code to match this criterion
+5  test to match - write the test to match the existing code
+6  check drift   - read the implementation and report whether it matches
+7  skip          - leave it, move on
+8  stop          - end the pass
+
+...or just type what is wrong, and that becomes the note.
+```
+
+Keep the numbers stable between items. A menu whose options move is a menu that has to be read
+every time, and the whole point is that it does not.
+
+`1` may be combined with prose - "1, but the wording is loose" accepts it and writes the note.
+
+## Their reply IS the note
+
+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>"
+```
+
+**Use their words, not a summary.** The note is sourced intent, which is the one thing that cannot
+be reconstructed from the code later. Tidy obvious dictation artefacts and nothing else; if their
+meaning is unclear, ask rather than paraphrase a guess into the document.
+
+A note written this way raises `@review`, which says an agent must act on it. That is correct even
+when you are about to act immediately: the flag is what survives the session ending.
+
+## The three status moves
+
+Offer them by name, and never take one without being told to.
+
+| They say | Command | What it claims |
+|---|---|---|
+| `1`, accept, that is right | `criteria-review accept <ID>` | This is what the software SHOULD do |
+| `2`, verify, I watched that | `criteria-review verify <ID>` | A person watched the software do it |
+| `3`, reject, not right | `criteria-review reject <ID>` | Back to derived |
+
+**Verify claims a person watched the software do this, at a named build.** The commit is resolved
+automatically from the project being reviewed, so nobody has to go and find a hash - **say which
+commit was recorded** when you report it back, and say so plainly if the tree was dirty, because
+then the commit does not contain what was watched.
+
+Never take verify because a scenario looks plausible. It is the one status that asserts something
+about a person's own actions, and only they can say it happened.
+
+Accepting and noting are independent: `--message` may be passed alongside a status move, and both
+are recorded.
+
+## 6, checking for drift against the source
+
+Reading the implementation before deciding. Cheap, often decisive, and **evidence rather than a
+verdict** - it is the one option here that produces a finding instead of a record.
+
+Work clause by clause, not scenario by scenario. Each `Then` is an assertion, and the useful answer
+is which of them the code supports:
+
+1. Find the code that would produce the behaviour. Start from the actor's entry point, not from a
+   symbol whose name matches a word in the scenario.
+2. For every `Then` and trailing `And`, report one of three things, with `file:line`:
+   - **supported** - the code does this, and here is where
+   - **contradicted** - the code does something else, and here is what
+   - **cannot tell from reading** - the path is dynamic, config-driven, or spread across services
+3. Say plainly which it is. Do not average three supported and one contradicted into "mostly fine";
+   the contradicted clause is the finding.
+
+Then re-present the menu, because the drift check informs the decision and does not make it.
+
+**State what the evidence is worth, every time.** Citing `file:line` proves a line was read. Only
+running the software proves the system does it. A clause that looks supported can still fail on a
+guard three layers up, and a clause that looks contradicted can be handled somewhere you did not
+read. Say "read, not run" in those words, so nobody mistakes it for verification.
+
+**Never promote a status off a code read.** Not `verified`, which claims a person watched it, and
+not `accepted`, which is a claim about intent that the implementation has no standing to settle.
+The implementation is not a source of intent: it contains what the system does, never why anyone
+wanted it.
+
+If the finding is worth keeping - a real contradiction, or a clause nobody can trace - offer to
+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>
+```
+
+That raises `@looknow` rather than `@review`, which is correct: the finding is a question for the
+architect, not an instruction for an agent.
+
+## When the scenario and the software disagree
+
+This is the case the whole standard exists to surface, and the reviewer has to say **which side is
+wrong**. Neither answer is "reject": one of them keeps the criterion exactly as written.
+
+Say it as the WORK, not as a verdict. "Which artefact is wrong" is an argument; "write the code to
+match this" is an instruction somebody can pick up.
+
+**4, write the code to match this criterion.** The criterion stands, and the build has not caught
+up. Accepting it is correct even though the software fails it, because `accepted` is a claim about
+intent, not about the implementation:
+
+```bash
+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
+is the defect surfacing in CI rather than in a list somebody has to remember. If no journey cites
+it yet, say so - the note and `@review` are the only thing carrying it, and writing the journey is
+the work that makes it self-reporting.
+
+**5, write the test to match the existing code.** The software is the truth here: the criterion was
+inferred, or it describes an intention nobody holds. Send it back to `derived`, which is exactly
+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>"
+```
+
+Both raise `@review`, which hands the item to an agent. Report which one was recorded and what
+happens next, in one line.
+
+A drift check (6) is the natural thing to run first when you cannot tell which way it should go.
+It settles what the code does; it never settles what the code should do.
+
+**Do not decide this for them.** Which way a disagreement resolves is the only question in the
+system that cannot be answered by reading either artefact, because both are self-consistent. The
+code cannot tell you it was meant to be different, and the document cannot tell you it was
+aspirational. Present the disagreement and ask.
+
+**Neither option does the work now.** Both record it as a work order and hand the item on. Doing it
+mid-pass is how a review of seventy-five scenarios becomes an afternoon on the first one.
+
+---
+
+## Walking the queue
+
+```bash
+criteria-review queue --limit 10
+```
+
+Ordered exactly as the page orders it: flagged items first, then grouped by document with the
+riskiest documents leading. Do not reorder it yourself - the architect sees the same order on
+screen, and two orderings would leave them unable to tell which is right.
+
+Then, **one at a time**:
+
+1. Present the scenario in full, as above.
+2. Take their reply. Prose becomes the note; a status word becomes the status move.
+3. **Apply it immediately**, before presenting the next one.
+4. Say in one line what was recorded, then present the next.
+
+Keep going until they stop you. Between items, "next", "continue" or a bare reply means carry on;
+"stop", "that's enough" or "cancel" ends the pass. Offer that explicitly at the start, not after
+they have already answered six.
+
+**Write as you go, do not batch.** A pass that collected ten answers and wrote them at the end
+loses all ten if the session ends, and the whole design puts review state in the documents rather
+than in a session that can evaporate. Writing each one also means an open page updates as they go.
+
+At the end, summarise: how many were answered, what each became, and how many remain in the queue.
+
+## While walking, do not
+
+- **Do not accept in bulk.** Every promotion is a person deciding one scenario. "Accept the rest"
+  is a request to stop and confirm what "the rest" contains, not an instruction to loop.
+- **Do not skip an item silently.** If something cannot be presented, say which and why.
+- **Do not summarise a scenario instead of showing it.** The wording is the requirement; a
+  paraphrase is the reviewer confirming your rewrite rather than the criterion.
+- **Do not fix the software mid-pass.** A note recording what is wrong is the output. Acting on it
+  is separate work, after the pass, with the note in front of you.
+
+---
+
+## The other direction
+
+If **you** need the architect's ruling on something and they are not in the conversation, the
+question belongs beside the scenario rather than in a transcript that scrolls away:
+
+```bash
+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
+re-review.
+
+## Ambiguity
+
+An id that exists in two registered projects is refused rather than guessed, naming both. Ask which
+one. Writing an answer against a scenario the architect did not read is the failure that refusal
+exists to prevent.
+
+## Related
+
+- `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 better surface when there is video to watch.