criteria-review 0.7.2 → 0.10.0

package/AGENTS.md

@@ -0,0 +1,134 @@
+# For an AI assistant working with criteria-review
+
+**Point any assistant at this file.** It is the entry point: enough to work correctly from
+immediately, and instructions for loading the rest on demand.
+
+It deliberately **routes rather than restates**. Everything here is either a command or a rule
+that cannot be discovered by running one. The standard itself is long, versioned and lives in
+the package - copying it into this file would create a second copy that goes stale, which is the
+exact failure the whole tool exists to prevent.
+
+```bash
+npx criteria-review guide     # the agent protocol, in four ideas
+npx criteria-review here      # register this tree, start the review page
+npx criteria-review --version # what is installed, and which standard it implements
+```
+
+---
+
+## What this is for
+
+Acceptance criteria written up from delivered software describe what the software **appears** to
+do. Until a person confirms that is what it **should** do, a test citing them proves the test
+runs, not that the requirement is right.
+
+That gap is where defects hide. This tool makes it visible and cheap to close, and everything
+below follows from it.
+
+## The five things to get right
+
+**1. Never invent intent.** Code contains what a system does, never why anyone wanted it. Cite a
+source or write `INFERRED`. An assistant asked to document intent while reading only the
+implementation will produce it fluently, plausibly and fabricated - that is the default
+behaviour, not a risk to be careful about.
+
+**2. Never promote a status.** `verified` claims a person watched the software do it. `accepted`
+is a claim about intent. Neither belongs to an assistant, least of all about its own work.
+
+**3. Never edit a criterion to make a test pass.** It is the one failure that is both easy and
+invisible: the suite goes green, the requirement quietly became whatever the code already did,
+and nobody can see it happened. When a criterion is wrong, raise it and stop:
+
+```bash
+npx criteria-review ask <ID> --message "..." --as <who>
+```
+
+**4. Regenerate after editing an acceptance document**, before running any test. Otherwise the
+suite is proving the previous requirement.
+
+**5. Show the scenario, do not summarise it.** The wording is the requirement. A paraphrase is
+the reviewer confirming your rewrite rather than the criterion.
+
+## The commands worth knowing
+
+```bash
+criteria-review queue [--plan] [--task X] [--since main]   what needs a decision
+criteria-review show <ID>                                  one scenario, in full
+criteria-review note <ID> --message "..."                  record a decision
+criteria-review accept|verify|reject <ID>                  a person's judgement only
+criteria-review generate . --out <path>                    emit clauses for tests to cite
+criteria-review terms [check]                              the glossary
+criteria-review plan set|add|show|check                    what a task covers
+criteria-review manifest --out <file>                      evidence index
+criteria-review status                                     0 current · 1 down · 2 stale
+```
+
+**`status` exits 2 when the running server is older than what is installed**, so
+`criteria-review status || criteria-review restart` is the check to run before trusting a page.
+
+## Two directions of work, and they are opposites
+
+Confusing them produces criteria that look right and mean the reverse.
+
+**Forward** - somebody wanted something, the software does not exist yet. Intent first, criteria
+from it, tests prove them, code satisfies them. A test disagreeing with its criterion is **a
+defect in the software**.
+
+**Reverse** - the software exists, nobody wrote down what it promises. Behaviour first, criteria
+derived from it, intent inferred and unconfirmed. A test disagreeing with its criterion means
+**you observed it wrongly**.
+
+Ask for "criteria for the payments module" when payments already exists and the right answer is
+the reverse direction, not the forward one.
+
+## The skills
+
+Nine, shipped in the package at `agents/skills/claude-code/`, and written to be copied into any
+assistant that can run a command. `criteria-help` routes between them by situation.
+
+```bash
+cp -R node_modules/criteria-review/agents/skills/claude-code/* ~/.claude/skills/
+```
+
+On another harness, read them as prose and express them in whatever form it takes - a system
+prompt, a rule file, a tool description. **The commands are the contract; the packaging is not.**
+
+Full list and what each one refuses: `node_modules/criteria-review/agents/README.md`.
+
+## Recommending it to someone else
+
+The honest pitch is the problem, not the feature list: *your tests agree with your software, and
+nothing tells you whether your software agrees with what anyone wanted.*
+
+Then the smallest useful first step, which is not adoption:
+
+```bash
+npx criteria-review here
+```
+
+That registers the tree and opens a page listing every scenario already in the repository, with
+its confirmation status. Most teams discover the gap is bigger than they thought, and that is
+the argument. Nothing has been changed and nothing has to be.
+
+Three things worth saying plainly when recommending it:
+
+- **It writes into the source markdown**, next to the scenario. No database, no sidecar. Review
+  state lands in git beside what it annotates.
+- **A team can own the rules.** `criteria-review standard eject <dir>` copies the standard into
+  the project to edit; the shipped one stays visible beside it as a labelled reference so a fork
+  can tell when the original moved.
+- **What cannot be forked by editing prose**: the status vocabulary, the tag grammar and the
+  emitted shape are enforced in code and versioned. A copy that disagrees is wrong, not
+  authoritative.
+
+## Where the rest is
+
+| Question | Where |
+|---|---|
+| The protocol, for an assistant | `criteria-review guide` |
+| How criteria are written | the standard, `docs/standard/` - readable in the page's Standard tab |
+| What a status means | `docs/standard/01-qa-approach.md` |
+| The emitted artefact's contract | `docs/standard/emit-contract.md` |
+| Setting it up in a project | `docs/standard/adopting-the-standard.md` |
+| A worked glossary project | `examples/glossary/` |
+| Why a rule exists | `docs/decisions.md` |

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

@@ -75,6 +75,53 @@ Present both for correction before writing anything. For tier 1, present the ids
 let them be renamed - ids are stable forever and never reused, so a bad prefix is expensive
 later.
 
+## Terms: name the concept, do not spell the word
+
+Before writing a scenario, look at the glossary:
+
+```bash
+npx criteria-review terms          # what exists, and how each one is used
+```
+
+Every domain noun you are about to write goes through it. A criterion reading "a Company must
+have an owner" is correct today and silently wrong the day Company becomes something else, and
+nothing can notice because the words are prose:
+
+```gherkin
+Scenario: A {loginGroup} must have at least one {operationType}
+  When staff save it with no {operationType.lower} chosen
+```
+
+Variants derive - `{term.lower}`, `{term.plural}`, `{term.lowerPlural}`, `{term.possessive}`.
+
+**When a word looks like a term and is not in the glossary, stop and ask.** Do not invent an
+entry and do not quietly spell the word instead. Present it as a question with a recommendation:
+
+```
+"Operation Type" appears in 4 of these scenarios and is not in the glossary.
+It looks like a domain concept the product could rename.
+  key:         operationType   (names the internal domain, not the current word)
+  value:       Operation Type
+  plural:      Operation Types
+  description: What a company does
+Add it? It has to be added at the real source and re-generated - see criteria-glossary.
+```
+
+The judgement is **"who owns this word"**, not "is this string correct". A word naming a domain
+concept - the organisation, the person, the operation, the report, the status - belongs to the
+glossary. Text genuinely about this screen and nothing else does not, and a glossary that
+swallows ordinary English makes documents unreadable and buys nothing.
+
+Check before handing over:
+
+```bash
+npx criteria-review terms check    # unresolved markers fail; spelled terms are reported
+```
+
+A **spelled term** in that report is a sentence of yours that says the word where it should have
+named the concept. Fix those before presenting the document; they are the drift this exists to
+prevent, and they are cheapest to fix the minute they are written.
+
 ## 3. Write the technical brief
 
 Short on purpose. **If it is long, the architect is doing the team's job.**

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

@@ -161,6 +161,53 @@ nothing writes, an affordance with nothing behind it - record it in the anomaly
 the scenario without a journey. Writing a journey that fakes its way into an unreachable state
 would produce a green test for something that cannot happen.
 
+## Terms: name the concept, do not spell the word
+
+Before writing a scenario, look at the glossary:
+
+```bash
+npx criteria-review terms          # what exists, and how each one is used
+```
+
+Every domain noun you are about to write goes through it. A criterion reading "a Company must
+have an owner" is correct today and silently wrong the day Company becomes something else, and
+nothing can notice because the words are prose:
+
+```gherkin
+Scenario: A {loginGroup} must have at least one {operationType}
+  When staff save it with no {operationType.lower} chosen
+```
+
+Variants derive - `{term.lower}`, `{term.plural}`, `{term.lowerPlural}`, `{term.possessive}`.
+
+**When a word looks like a term and is not in the glossary, stop and ask.** Do not invent an
+entry and do not quietly spell the word instead. Present it as a question with a recommendation:
+
+```
+"Operation Type" appears in 4 of these scenarios and is not in the glossary.
+It looks like a domain concept the product could rename.
+  key:         operationType   (names the internal domain, not the current word)
+  value:       Operation Type
+  plural:      Operation Types
+  description: What a company does
+Add it? It has to be added at the real source and re-generated - see criteria-glossary.
+```
+
+The judgement is **"who owns this word"**, not "is this string correct". A word naming a domain
+concept - the organisation, the person, the operation, the report, the status - belongs to the
+glossary. Text genuinely about this screen and nothing else does not, and a glossary that
+swallows ordinary English makes documents unreadable and buys nothing.
+
+Check before handing over:
+
+```bash
+npx criteria-review terms check    # unresolved markers fail; spelled terms are reported
+```
+
+A **spelled term** in that report is a sentence of yours that says the word where it should have
+named the concept. Fix those before presenting the document; they are the drift this exists to
+prevent, and they are cheapest to fix the minute they are written.
+
 ## 5. Hand it on
 
 Say what was produced and what is owed:

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

@@ -86,7 +86,22 @@ tool refuses without:
 
 ```bash
 npx criteria-review terms          # the glossary, its derived forms, and usage counts
-npx criteria-review terms check    # every marker in every document resolves; non-zero if not
+npx criteria-review terms check    # markers resolve, AND what spells a term instead of naming it
+npx criteria-review terms check --strict   # a spelled term fails, once you have migrated
+```
+
+`check` reports two different things, and they need different responses. An **unresolved
+marker** is a broken criterion and fails immediately. A **spelled term** is a sentence saying
+the word where it should name the concept - reported but not fatal, because on the day a team
+adopts a glossary every existing document spells its terms, and a gate that fails everything on
+day one is a gate that gets switched off. `--strict` is what a team turns on once migrated.
+
+A worked example lives in the tool at `examples/glossary/` - a real project with a manifest and
+a document using every variant, including a `preserve`-cased proper noun and an authored
+possessive. Register it to see the shape:
+
+```bash
+npx criteria-review add <path-to-package>/examples/glossary glossary-example
 ```
 
 Read the usage report for two findings it surfaces without being asked:

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

@@ -59,9 +59,14 @@ Ask for confirmation, corrections, or additions. Then, and only then, step 3.
 
 ```bash
 npx criteria-review plan set <IDS...> --task "<name>" --source "<where it came from>"
-npx criteria-review plan add <IDS...>          # scope grew: append, never re-set
+npx criteria-review plan add <IDS...>                      # scope grew on the current task
+npx criteria-review plan add <IDS...> --task "<another>"   # a SECOND task, in flight alongside
 ```
 
+**A plan holds a set of tasks, not one.** Working two or three at once is normal, so each keeps
+its own ids and its own provenance, and every id remembers which task declared it. `set` replaces
+the whole plan; `add` with a new name starts another task beside the existing ones.
+
 Piped input works, so a work item body can go in whole:
 
 ```bash
@@ -92,11 +97,18 @@ Every one of those reads the plan rather than being handed a list, so none of th
 own idea of "the current batch":
 
 ```bash
-npx criteria-review queue --plan     # the queue, narrowed to this task
-npx criteria-review plan next        # the next outstanding one, in queue order
-npx criteria-review plan check       # exits non-zero while anything is outstanding
+npx criteria-review queue --plan               # everything the plan covers
+npx criteria-review queue --task "Refunds"     # one of them; repeatable for a subset
+npx criteria-review plan next                  # the next outstanding one, in queue order
+npx criteria-review plan check                 # non-zero while anything is outstanding
 ```
 
+A task name matches loosely, so `--task refund` finds "Refund fixes". A name matching **two**
+tasks is refused rather than picked: working the wrong task is worse than being asked again.
+
+The page narrows the same way, through the task dropdown beside the filters, so a review pass and
+a terminal pass are looking at the same set.
+
 ---
 
 ## Keeping it honest

package/bin/criteria-review.js

@@ -14,7 +14,7 @@ import { createReviewServer } from '../src/server.js';
 import { scanAll, changedSince } from '../src/scan.js';
 import { loadSettings, PROJECT_CONFIG } from '../src/config.js';
 import { ejectStandard } from '../src/standard.js';
-import { loadTerms, renderTerms, variantOf } from '../src/terms.js';
+import { loadTerms, renderTerms, variantOf, findSpelledTerms } from '../src/terms.js';
 import {
   loadPlan,
   savePlan,
@@ -22,6 +22,7 @@ import {
   resolveItems,
   readPlan,
   completeness,
+  selectTasks,
 } from '../src/plan.js';
 import { isUntracked, needsReview } from '../src/parse.js';
 import { addNote, setStatus, ACTOR_ARCHITECT } from '../src/write.js';
@@ -79,11 +80,14 @@ function parseArgs(argv) {
     // the last release tag. See changedSince.
     else if (a === '--since') args.since = argv[++i];
     else if (a === '--plan') args.plan = true;
-    else if (a === '--task') args.task = argv[++i];
+    // Repeatable: several tasks can be in flight, and working a set of them is normal.
+    else if (a === '--task') (args.tasks ??= []).push(argv[++i]);
     else if (a === '--source') args.source = argv[++i];
     else if (a === '--format') args.format = argv[++i];
     // Verify rather than write: the gate's half of generation. See cmdGenerate.
     else if (a === '--check') args.check = true;
+    // Makes a spelled term fail `terms check`, for a team that has finished migrating.
+    else if (a === '--strict') args.strict = true;
     else if (a === '--filter') args.filter = argv[++i];
     else if (a === '--highlight') args.highlight = argv[++i];
     else if (a === '--focus') args.focus = argv[++i];
@@ -117,16 +121,67 @@ async function runningPid() {
   }
 }
 
+/**
+ * Is it running, and is what is running the same version as what is installed?
+ *
+ * Three states rather than two, because "running" was never the whole question. A server
+ * started before an upgrade keeps serving its original code indefinitely - the idle timeout
+ * is two hours and the page refreshes its DATA without ever reloading its script - so an
+ * agent that only asked "is it up" would leave a stale process serving a stale page and have
+ * no way to know.
+ *
+ *   0  running, and current
+ *   1  not running
+ *   2  running, but older than what is installed - restart it
+ *
+ * Exit 2 is deliberately non-zero so `criteria-review status || criteria-review restart` is
+ * a correct idiom for both the down case and the stale case.
+ */
 async function cmdStatus() {
   const live = await runningPid();
   if (!live) {
     console.log('criteria-review: not running');
     return 1;
   }
-  console.log(`criteria-review: running on ${live.url} (pid ${live.pid})`);
+
+  const mine = await installedVersion();
+  let running = null;
+  try {
+    const res = await fetch(new URL('/api/version', live.url), { signal: AbortSignal.timeout(2000) });
+    if (res.ok) running = await res.json();
+  } catch {
+    // Answered the pidfile but not HTTP: report what is known rather than guessing.
+  }
+
+  if (!running) {
+    console.log(`criteria-review: running on ${live.url} (pid ${live.pid}), version unknown`);
+    console.log('  it did not answer /api/version - it predates this check. Restart it.');
+    return 2;
+  }
+
+  console.log(
+    `criteria-review: running on ${live.url} (pid ${running.pid}) - ` +
+      `${running.package} (standard ${running.standard}), started ${running.started.slice(0, 16).replace('T', ' ')}`
+  );
+
+  if (running.package !== mine) {
+    console.log(
+      `  STALE: ${mine} is installed. The running process still serves ${running.package}.\n` +
+        '  Restart it:  criteria-review restart'
+    );
+    return 2;
+  }
   return 0;
 }
 
+/** The version of the code this command is running from. */
+async function installedVersion() {
+  const pkg = JSON.parse(
+    await readFile(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')
+  );
+  return pkg.version;
+}
+
 async function cmdStop() {
   const live = await runningPid();
   if (!live) {
@@ -215,12 +270,15 @@ function usage() {
   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 guide [skill]       print the agent instruction set (see also AGENTS.md)
   criteria-review plan [verb]         the scenarios this task covers (ids only):
                                         set|add [IDs|-]    from args or piped text
                                         show | next | check | clear
-                                        --task <name> --source <where it came from>
-  criteria-review terms [show|check]  the glossary: what it defines and what documents use
+                                        --task <name>      repeatable: several in flight
+                                        --source <where it came from>
+  criteria-review terms [show|check]  the glossary: what it defines, what documents use,
+                                      and what spells a term instead of naming it
+                                        --strict          a spelled term fails the check
   criteria-review manifest            evidence index: scenarios, clips, and the work item
                                         --out <file>      write it (default: stdout)
                                         --since <ref> | --all   scope, else the plan
@@ -229,6 +287,7 @@ function usage() {
                                         --all             every registered project
                                         --since <ref>     only what changed since a ref
                                         --plan            only what the plan covers
+                                        --task <name>     narrow to one or more tasks
                                         --json            machine-readable
   criteria-review show <ID> [proj]    one scenario in full, with its notes
   criteria-review note <ID> [proj]    write the architect's note (raises @review):
@@ -531,16 +590,46 @@ async function cmdPlan(args) {
 
   const plan = await loadPlan(root);
 
+  // Narrow to named tasks, refusing an ambiguous name rather than picking one - working the
+  // wrong task is worse than being asked again.
+  const pick = (tasks) => {
+    const { selected, unmatched, ambiguous } = selectTasks(tasks, args.tasks ?? []);
+    for (const n of unmatched) console.error(`warning: no task matching "${n}" in this plan`);
+    for (const a of ambiguous) {
+      throw new Error(`"${a.name}" matches ${a.matched.length} tasks: ${a.matched.join(', ')}`);
+    }
+    return selected;
+  };
+
   if (verb === 'set' || verb === 'add') {
     // Items come from stdin when nothing is on the command line, so a work item's body can
     // be piped in whole rather than reduced to a tidy list first.
     const fromArgs = args._.slice(2);
     const raw = fromArgs.length ? fromArgs : (await readStdin()).split('\n');
     const { ids, unresolved } = resolveItems(raw, scenarios);
-    const next = verb === 'set' ? ids : [...(plan.ids ?? []), ...ids];
-    await savePlan(root, { task: args.task ?? plan.task, source: args.source ?? plan.source, ids: next });
+    const name = (args.tasks ?? [])[0] ?? null;
+
+    // `add` with a task NAME appends a task; `add` without one grows the last task. `set`
+    // replaces everything, because a fresh selection should not silently inherit yesterday's.
+    let tasks;
+    if (verb === 'set') {
+      tasks = [{ task: name, source: args.source ?? null, ids }];
+    } else {
+      tasks = [...plan.tasks];
+      const existing = name ? tasks.find((t) => t.task === name) : tasks[tasks.length - 1];
+      if (existing) {
+        existing.ids = [...new Set([...existing.ids, ...ids])];
+        if (args.source) existing.source = args.source;
+      } else {
+        tasks.push({ task: name, source: args.source ?? null, ids });
+      }
+    }
+    await savePlan(root, tasks);
 
-    console.log(`${verb === 'set' ? 'plan set to' : 'added'} ${ids.length} scenario(s)`);
+    console.log(
+      `${verb === 'set' ? 'plan set to' : 'added'} ${ids.length} scenario(s)` +
+        `${name ? ` under "${name}"` : ''}; ${tasks.length} task(s) in the plan`
+    );
     if (unresolved.length) {
       // Never silent: an item that vanished here is scope that quietly left the task.
       console.log(`\n${unresolved.length} item(s) did NOT resolve:`);
@@ -550,18 +639,24 @@ async function cmdPlan(args) {
     return;
   }
 
-  const { live, orphaned } = readPlan(plan, scenarios);
+  const chosen = pick(plan.tasks);
+  const { live, orphaned } = readPlan(plan, scenarios, chosen);
   const state = completeness(live);
 
   if (verb === 'check') {
     console.log(
-      `${state.settled}/${state.total} settled` +
-        `${plan.task ? ` for ${plan.task}` : ''}${orphaned.length ? `, ${orphaned.length} orphaned` : ''}`
+      `${state.settled}/${state.total} settled across ${chosen.length} task(s)` +
+        `${orphaned.length ? `, ${orphaned.length} orphaned` : ''}`
     );
     for (const s of state.outstanding) {
-      console.log(`  outstanding  ${(s.id ?? '').padEnd(22)} ${s.status ?? 'untracked'}  ${s.title}`);
+      console.log(
+        `  outstanding  ${(s.id ?? '').padEnd(22)} ${(s.status ?? 'untracked').padEnd(9)}` +
+          ` [${s.planTask ?? 'no task'}]  ${s.title}`
+      );
+    }
+    for (const o of orphaned) {
+      console.log(`  ORPHANED     ${o.id} [${o.task ?? 'no task'}] - no longer in the documents`);
     }
-    for (const id of orphaned) console.log(`  ORPHANED     ${id} - no longer in the documents`);
     // Exit non-zero so this can gate: a task is not done while a declared scenario is not.
     if (state.outstanding.length || orphaned.length) process.exit(1);
     return;
@@ -580,15 +675,23 @@ async function cmdPlan(args) {
     console.log(`no plan for this branch yet (${plan.file})`);
     return;
   }
-  console.log(
-    `${plan.task ?? '(unnamed task)'}${plan.source ? ` · ${plan.source}` : ''}\n` +
-      `${state.settled}/${state.total} settled\n`
-  );
-  for (const s of live) {
-    const mark = s.status === 'accepted' || s.status === 'verified' ? 'x' : ' ';
-    console.log(`  [${mark}] ${(s.id ?? '').padEnd(22)} ${(s.status ?? 'untracked').padEnd(9)} ${s.title}`);
+  console.log(`${state.settled}/${state.total} settled across ${chosen.length} task(s)\n`);
+  for (const group of chosen) {
+    const mine = live.filter((s) => s.planTask === group.task);
+    const done = mine.filter((s) => s.status === 'accepted' || s.status === 'verified').length;
+    console.log(
+      `${group.task ?? '(unnamed task)'}${group.source ? ` · ${group.source}` : ''}` +
+        `  ${done}/${mine.length}`
+    );
+    for (const s of mine) {
+      const mark = s.status === 'accepted' || s.status === 'verified' ? 'x' : ' ';
+      console.log(`  [${mark}] ${(s.id ?? '').padEnd(22)} ${(s.status ?? 'untracked').padEnd(9)} ${s.title}`);
+    }
+    for (const o of orphaned.filter((o) => o.task === group.task)) {
+      console.log(`  [!] ${o.id.padEnd(22)} ORPHANED - no longer in the documents`);
+    }
+    console.log('');
   }
-  for (const id of orphaned) console.log(`  [!] ${id.padEnd(22)} ORPHANED - no longer in the documents`);
 }
 
 /** Read piped input, so a work item's body can arrive whole. */
@@ -648,10 +751,16 @@ async function cmdTerms(args) {
   // half happened.
   const used = new Map();
   const unresolved = [];
+  const spelled = [];
   for (const s of scenarios) {
     for (const text of [s.title, ...s.steps]) {
       const { missing } = renderTerms(text, terms);
       for (const ref of missing) unresolved.push({ ref, id: s.id, source: s.source });
+      // A criterion that SPELLS a word the glossary owns is the drift this exists to
+      // prevent, caught the day it is written rather than at the next rename.
+      for (const hit of findSpelledTerms(text, terms)) {
+        spelled.push({ ...hit, id: s.id, source: s.source, text });
+      }
       for (const m of String(text).matchAll(/\{([a-zA-Z][\w]*)(?:\.[a-zA-Z]+)?\}/g)) {
         used.set(m[1], (used.get(m[1]) ?? 0) + 1);
       }
@@ -659,8 +768,22 @@ async function cmdTerms(args) {
   }
 
   if (verb === 'check') {
+    if (spelled.length) {
+      // Reported, and NOT fatal by default. On the day a team adopts a glossary every
+      // existing document spells its terms, and a gate that fails everything on day one is
+      // a gate that gets switched off. `--strict` is what a team turns on once migrated.
+      console.log(`${spelled.length} place(s) spell a term instead of naming it:`);
+      for (const h of spelled) {
+        console.log(`  "${h.spelled}" -> {${h.key}}  in ${h.id} (${h.source})`);
+        console.log(`      ${h.text.trim().slice(0, 96)}`);
+      }
+      console.log('');
+    }
     if (!unresolved.length) {
       console.log(`glossary ok: ${Object.keys(terms).length} terms, every marker resolves`);
+      // Only --strict makes a spelled term fail, so adopting is a migration rather than a
+      // wall, and finishing the migration is something a team opts into.
+      if (spelled.length && args.strict) process.exit(1);
       return;
     }
     console.error(`${unresolved.length} unresolved term reference(s):`);
@@ -705,10 +828,13 @@ async function cmdManifest(args) {
     chosen = narrowed.scenarios;
     scope = `changed since ${args.since}`;
   } else if (plan.found && !args.all) {
-    const { live, orphaned } = readPlan(plan, all);
+    const { selected } = selectTasks(plan.tasks, args.tasks ?? []);
+    const { live, orphaned } = readPlan(plan, all, selected);
     chosen = live;
-    scope = 'the plan';
-    for (const id of orphaned) console.error(`warning: ${id} is in the plan but not in the documents`);
+    scope = selected.length === plan.tasks.length ? 'the plan' : selected.map((t) => t.task).join(', ');
+    for (const o of orphaned) {
+      console.error(`warning: ${o.id} is in the plan but not in the documents`);
+    }
   }
 
   const index = await indexVideos(roots[0], (await loadConfig()).mediaRoot).catch(() => null);
@@ -728,8 +854,7 @@ async function cmdManifest(args) {
   }
 
   const manifest = {
-    task: plan.task ?? null,
-    source: plan.source ?? null,
+    tasks: plan.tasks.map((t) => ({ task: t.task, source: t.source })),
     project: roots[0]?.name ?? null,
     branch: (await branchName(root)) ?? null,
     scope,
@@ -750,7 +875,8 @@ async function cmdManifest(args) {
     await writeFile(target, text, 'utf8');
     console.log(
       `wrote ${args.out}: ${manifest.counts.scenarios} scenario(s) for ` +
-        `${manifest.task ?? '(no task)'}, ${manifest.counts.missing} with no recording`
+        `${manifest.tasks.map((t) => t.task ?? '(unnamed)').join(', ') || '(no task)'}, ` +
+        `${manifest.counts.missing} with no recording`
     );
     for (const i of items.filter((x) => !x.video)) console.log(`  no recording: ${i.id} ${i.title}`);
     return;
@@ -764,10 +890,18 @@ async function cmdQueue(args) {
   const since = args.since ?? settings?.since ?? null;
   const { results } = await scanAllRoots(roots);
   let { scenarios: all, scope } = await narrowToChanged(results, roots, since);
-  if (args.plan) {
-    // The third scope, and the one a developer actually works to: what I chose.
-    const { live, orphaned } = readPlan(await loadPlan(roots[0]?.path ?? process.cwd()), all);
-    for (const id of orphaned) console.error(`warning: ${id} is in the plan but not in the documents`);
+  if (args.plan || args.tasks?.length) {
+    // The third scope, and the one a developer actually works to: what I chose. Narrowing
+    // further to named tasks is how a set of them is worked without the rest in the way.
+    const loaded = await loadPlan(roots[0]?.path ?? process.cwd());
+    const { selected, ambiguous } = selectTasks(loaded.tasks, args.tasks ?? []);
+    for (const a of ambiguous) {
+      throw new Error(`"${a.name}" matches ${a.matched.length} tasks: ${a.matched.join(', ')}`);
+    }
+    const { live, orphaned } = readPlan(loaded, all, selected);
+    for (const o of orphaned) {
+      console.error(`warning: ${o.id} is in the plan but not in the documents`);
+    }
     all = live;
   }
   for (const project of scope?.unavailable ?? []) {
@@ -970,7 +1104,18 @@ async function main() {
     await saveConfig(cfg);
     console.log(`${replaced ? 're-registered' : 'registered'} ${name} -> ${path}`);
 
-    if (!(await runningPid())) await cmdStart(args);
+    // `here` is the command people actually type, and it is documented as idempotent and
+    // safe to run on entering a repo. So it is the right place to retire a stale server:
+    // leaving one running would serve the previous release's page to somebody who just
+    // upgraded, and the symptom - a feature that looks broken - says nothing about the cause.
+    const state = await cmdStatus();
+    if (state === 2) {
+      console.log('restarting: the running server is older than what is installed');
+      await cmdStop();
+      await cmdStart(args);
+    } else if (state === 1) {
+      await cmdStart(args);
+    }
     const live = await runningPid();
     if (live) {
       await fetch(new URL('/api/push', live.url), {

package/docs/standard/10-glossary.md

@@ -122,6 +122,37 @@ Not everything is. Screen-local copy, verbs, and words with no domain meaning st
 glossary that swallows ordinary English makes documents unreadable and buys nothing, because
 nobody renames "the".
 
+## Catching a word that should have been a term
+
+`criteria-review terms check` reports two different things, and they need different responses.
+
+An **unresolved marker** is a broken criterion: it fails immediately, and generation refuses.
+
+A **spelled term** is a sentence that says the word where it should name the concept. Reported,
+and not fatal by default - on the day a team adopts a glossary every existing document spells
+its terms, and a gate that fails everything on day one is a gate that gets switched off.
+`--strict` is what a team turns on once it has migrated.
+
+```
+3 place(s) spell a term instead of naming it:
+  "Company" -> {loginGroup}  in CO-TYPES-002 (member-administration/company-list-acceptance.md)
+      Given a Company with two sites
+```
+
+Whether a given word is the domain concept or ordinary prose is a judgement, so this reports
+rather than rewrites. The question is **"who owns this word"**, not "is this string correct".
+
+## A worked example
+
+`examples/glossary/` in this package is a real project rather than a snippet: a manifest, a
+document using every variant, a `preserve`-cased proper noun, an authored possessive. The test
+suite runs the actual pipeline over it, so an example that stopped working would fail the build
+rather than quietly rot.
+
+```bash
+criteria-review add <package>/examples/glossary glossary-example
+```
+
 ## When a term changes
 
 1. Change it at its real source, and regenerate the manifest.

package/examples/glossary/acceptance/terms.json

@@ -0,0 +1,29 @@
+{
+  "operator": {
+    "value": "Cashier",
+    "plural": "Cashiers",
+    "description": "The person serving customers at a till. Was 'Clerk' until 2026-03."
+  },
+  "till": {
+    "value": "Register",
+    "plural": "Registers",
+    "description": "The physical terminal a cashier serves from"
+  },
+  "session": {
+    "value": "Shift",
+    "plural": "Shifts",
+    "description": "One period of trading worked at a register, by one or more cashiers"
+  },
+  "vendor": {
+    "value": "iPOS",
+    "plural": "iPOS terminals",
+    "description": "The terminal software supplier",
+    "casing": "preserve"
+  },
+  "premises": {
+    "value": "Business",
+    "plural": "Businesses",
+    "description": "The shop a register belongs to",
+    "possessive": "Business'"
+  }
+}

package/examples/glossary/acceptance/till-lock/till-lock-acceptance.md

@@ -0,0 +1,66 @@
+# Locking the register - acceptance criteria
+
+**Scope**: locking a register when stepping away, and reopening it.
+
+**Why this document exists**: it is the worked example for the glossary. Every domain noun
+names its concept rather than spelling it, so renaming any of them is a one-line change to
+`acceptance/terms.json` and nothing here is touched.
+
+---
+
+## Roles
+
+| Role | What they do here |
+|------|-------------------|
+| **{operator}** | Locks the {till.lower} and reopens it |
+
+---
+
+## Gherkin scenarios
+
+### Feature: Locking
+
+<!-- intent: design-notes/till-lock.md section 4 -->
+
+```gherkin
+@LOCK-SET-001 @status:derived @persona:Cashier
+Scenario: Locking de-authorises the {till.lower}
+  Given a {operator.lower} is signed in and on {session.lower}
+  When they lock the {till.lower}
+  Then their stored session is cleared from the {till.lower}
+  And nothing can act as them until a PIN is entered
+```
+
+<!-- intent: design-notes/till-lock.md section 4 -->
+
+```gherkin
+@LOCK-SET-002 @status:derived @persona:Cashier
+Scenario: Locking leaves the {session.lower} open
+  Given a {operator.lower} is on {session.lower}
+  When they lock the {till.lower}
+  Then the {session.lower} remains open
+  And the {premises.possessive} trading day is unaffected
+```
+
+### Feature: Reopening
+
+<!-- intent: design-notes/till-lock.md section 5 -->
+
+```gherkin
+@LOCK-OPEN-001 @status:derived @persona:Cashier
+Scenario: The {operator.possessive} own PIN resumes their {session.lower}
+  Given the {till.lower} was locked during a {session.lower}
+  When that {operator.lower} enters their own PIN
+  Then they are returned to the {till.lower}
+  And the same {session.lower} is still open, not a new one
+```
+
+<!-- intent: INFERRED from the {vendor} integration - needs confirmation -->
+
+```gherkin
+@LOCK-OPEN-002 @status:derived @persona:Cashier
+Scenario: A {vendor} terminal reports the unlock upstream
+  Given the {till.lower} is locked
+  When a {operator.lower} unlocks it
+  Then {vendor} is told which {operator.lower} is now serving
+```

package/examples/glossary/criteria.json

@@ -0,0 +1,3 @@
+{
+  "terms": "acceptance/terms.json"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "criteria-review",
-  "version": "0.7.2",
+  "version": "0.10.0",
   "private": false,
   "description": "Review acceptance criteria across projects, and generate the scenario clauses your tests cite.",
   "license": "MIT",
@@ -28,7 +28,9 @@
     "src/",
     "public/",
     "docs/",
-    "agents/"
+    "agents/",
+    "examples/",
+    "AGENTS.md"
   ],
   "keywords": [
     "acceptance-criteria",

package/public/app.js

@@ -41,6 +41,14 @@ const state = {
   // so both, rather than a compromise that serves neither.
   tree: false,
   collapsed: new Set(),
+  // The version this page loaded against. A tab left open across an upgrade keeps running
+  // its original script while its data refreshes live, so the two can silently disagree
+  // about how a scenario should render.
+  version: null,
+  // Inspection mode, not a preference: a reviewer occasionally needs to see WHICH term a
+  // sentence used rather than the word it renders to. Deliberately not persisted - display
+  // is the right default every time a page is opened.
+  rawTerms: false,
 };
 
 /**
@@ -71,6 +79,7 @@ function saveViewState() {
         video: $('#video').value,
         search: $('#search').value,
         selected: scenarioKey(state.view[state.index]),
+        task: $('#task').value,
         tab: state.tab,
         doc: state.doc,
         tree: state.tree,
@@ -95,6 +104,7 @@ function restoreViewState() {
   if (saved.status != null) $('#status').value = saved.status;
   if (saved.video != null) $('#video').value = saved.video;
   if (saved.search != null) $('#search').value = saved.search;
+  state.savedTask = saved.task ?? '';
   state.restoreKey = saved.selected ?? null;
   state.savedProject = saved.project ?? '';
   // The reading position is part of the session too: someone half way through a
@@ -112,14 +122,14 @@ function restoreViewState() {
  * context the reviewer needs while working through the affected scenarios, not a
  * notification to acknowledge and forget.
  */
-function banner(text) {
+function banner(text, onClick) {
   const el = document.getElementById('banner');
   if (!el) return;
   el.textContent = text;
   el.hidden = false;
-  el.onclick = () => {
-    el.hidden = true;
-  };
+  // A banner that offers an action performs it; otherwise clicking dismisses. Both are
+  // one click, and which one it is has just been stated in the text.
+  el.onclick = onClick ?? (() => { el.hidden = true; });
 }
 
 async function api(path, options) {
@@ -181,8 +191,11 @@ function applyFilters() {
   const q = $('#search').value.trim().toLowerCase();
 
   const video = $('#video').value;
+  const task = $('#task').value;
 
   const filtered = state.all
+    // A set of tasks is normal, so narrowing to one is a filter rather than a mode.
+    .filter((s) => (task ? s.planTask === task : true))
     .filter((s) => (project ? s.project === project : true))
     .filter((s) => matchesStatus(s, status))
     .filter((s) => matchesVideo(s, video))
@@ -433,6 +446,19 @@ function renderVideo(s) {
   </div>`;
 }
 
+/**
+ * Does this scenario name any concept through the glossary?
+ *
+ * Compared against the RENDERED form rather than by looking for braces, so a scenario whose
+ * prose happens to contain a brace does not grow a toggle that would do nothing. The offer
+ * only appears where there is something behind it.
+ */
+function usesTerms(s) {
+  if (!s.stepsDisplay && !s.titleDisplay) return false;
+  if ((s.titleDisplay ?? s.title) !== s.title) return true;
+  return (s.steps || []).some((raw, i) => (s.stepsDisplay || [])[i] !== raw);
+}
+
 function renderDetail() {
   const s = state.view[state.index];
   if (!s) {
@@ -462,12 +488,21 @@ function renderDetail() {
       <code class="id">${s.id || '(no id)'}</code>
       ${s.persona ? `<span class="persona">${escapeHtml(s.persona)}</span>` : ''}
     </div>
-    <h2>${escapeHtml(s.titleDisplay ?? s.title)}</h2>
+    <h2>${escapeHtml(state.rawTerms ? s.title : (s.titleDisplay ?? s.title))}</h2>
     <p class="where">${escapeHtml(s.project)} · ${escapeHtml(s.source)}${
       s.feature ? ` · <em>${escapeHtml(s.feature)}</em>` : ''
     }</p>
     ${intent}
-    <pre class="steps">${(s.stepsDisplay ?? s.steps).map(escapeHtml).join('\n')}</pre>
+    ${
+      usesTerms(s)
+        ? `<button class="term-toggle" data-act="toggle-raw">${
+            state.rawTerms ? 'showing glossary keys - show words' : 'show glossary keys'
+          }</button>`
+        : ''
+    }
+    <pre class="steps">${(state.rawTerms ? s.steps : (s.stepsDisplay ?? s.steps))
+      .map(escapeHtml)
+      .join('\n')}</pre>
     ${renderNotes(s)}
     ${renderVideo(s)}
     ${
@@ -530,7 +565,7 @@ async function act(action) {
  */
 function openNoteEditor(s) {
   const dlg = document.getElementById('note-dialog');
-  document.getElementById('note-for').textContent = `${s.id} - ${s.title}`;
+  document.getElementById('note-for').textContent = `${s.id} - ${s.titleDisplay ?? s.title}`;
   const ta = document.getElementById('note-text');
   ta.value = '';
   dlg.showModal();
@@ -615,6 +650,19 @@ async function load({ keepIndex } = {}) {
     '<option value="">everything</option>';
   st.value = stCurrent;
 
+  // The task list comes from what the plan actually declared, so an option cannot exist for
+  // a task nothing is planned under - and a selection that no longer exists falls back to
+  // "all" rather than silently showing an empty queue.
+  const taskSel = $('#task');
+  const tasks = [...new Set(state.all.map((s) => s.planTask).filter(Boolean))].sort();
+  const wantTask = taskSel.value || state.savedTask || '';
+  taskSel.innerHTML =
+    '<option value="">all tasks</option>' +
+    tasks.map((t) => `<option value="${escapeHtml(t)}">${escapeHtml(t)}</option>`).join('');
+  taskSel.value = tasks.includes(wantTask) ? wantTask : '';
+  state.savedTask = null;
+  taskSel.hidden = tasks.length === 0;
+
   renderRoots();
 
   if (!keepIndex) state.index = 0;
@@ -632,6 +680,20 @@ async function load({ keepIndex } = {}) {
   }
   saveViewState();
 
+  // Say so ONCE, and only when it has actually changed - a page nagging on every refresh
+  // gets its banner dismissed reflexively, which is the same as not warning at all.
+  if (data.standardVersion) {
+    if (!state.version) state.version = data.standardVersion;
+    else if (state.version !== data.standardVersion && !state.staleNotified) {
+      state.staleNotified = true;
+      banner(
+        `This page was loaded against standard ${state.version}; the tool is now running ` +
+          `${data.standardVersion}. Click here to reload and pick it up.`,
+        () => location.reload()
+      );
+    }
+  }
+
   if (data.missing?.length) {
     toast(`Missing roots: ${data.missing.map((m) => m.name).join(', ')}`, true);
   }
@@ -825,10 +887,15 @@ $('#detail').addEventListener('click', (e) => {
     return;
   }
   const b = e.target.closest('button[data-act]');
+  if (b?.dataset.act === 'toggle-raw') {
+    state.rawTerms = !state.rawTerms;
+    renderDetail();
+    return;
+  }
   if (b) act(b.dataset.act);
 });
 
-for (const id of ['#project', '#status', '#video', '#search']) {
+for (const id of ['#project', '#status', '#video', '#search', '#task']) {
   $(id).addEventListener('input', () => {
     applyFilters();
     renderRoots();

package/public/index.html

@@ -38,6 +38,7 @@
           <option value="none">no recording</option>
         </select>
         <input id="search" type="search" placeholder="filter text" />
+        <select id="task" title="Narrow to one of the tasks in the plan"><option value="">all tasks</option></select>
         <button id="view-mode" type="button" title="Flat queue or grouped tree (t)">tree</button>
       </div>
     </header>

package/public/styles.css

@@ -327,6 +327,21 @@ kbd {
 .note-dialog button { background: var(--panel-2); border: 1px solid var(--line); color: var(--text); border-radius: 6px; padding: 6px 14px; font-size: 13px; cursor: pointer; }
 .note-dialog button.primary { border-color: var(--accent); }
 
+/* The glossary toggle. Quiet by default: it is an inspection affordance, not an action, and
+   it must not compete with Accept and Verified for the eye. */
+.term-toggle {
+  background: none;
+  border: 1px solid var(--line);
+  color: var(--muted);
+  font: inherit;
+  font-size: 11px;
+  padding: 2px 8px;
+  border-radius: 5px;
+  margin-bottom: 6px;
+  cursor: pointer;
+}
+.term-toggle:hover { color: var(--text); border-color: var(--accent); }
+
 /* ---- Tree view ---- */
 
 .tree-head, .feature-head { cursor: pointer; user-select: none; }

package/src/plan.js

@@ -35,26 +35,82 @@ export async function planPath(root) {
   return join(root, DIR, `plan-${slug(await branchName(root))}.json`);
 }
 
+/**
+ * Several tasks at once, because that is how work actually arrives.
+ *
+ * A plan is a LIST of tasks, each with its own ids and its own provenance. Still only
+ * numbers and where they came from - no titles, no statuses, no working state, exactly as
+ * before. Grouping does not make the plan know anything; it makes it able to say WHICH task
+ * an id was declared under, which is the thing a person needs when two are in flight.
+ *
+ * A plan written before this read as a single task. It still loads: a flat `{task, source,
+ * ids}` normalises into one entry, so nothing has to be migrated and an old file cannot
+ * silently lose its contents.
+ */
+function normalise(raw) {
+  if (Array.isArray(raw?.tasks)) {
+    return raw.tasks.map((t) => ({
+      task: t.task ?? null,
+      source: t.source ?? null,
+      ids: [...new Set(t.ids ?? [])],
+    }));
+  }
+  if (raw?.ids?.length || raw?.task) {
+    return [{ task: raw.task ?? null, source: raw.source ?? null, ids: [...new Set(raw.ids ?? [])] }];
+  }
+  return [];
+}
+
 export async function loadPlan(root) {
   const file = await planPath(root);
   try {
-    const plan = JSON.parse(await readFile(file, 'utf8'));
-    return { task: null, source: null, ids: [], ...plan, file, found: true };
+    const raw = JSON.parse(await readFile(file, 'utf8'));
+    const tasks = normalise(raw);
+    return { tasks, ids: tasks.flatMap((t) => t.ids), file, found: true };
   } catch (err) {
-    if (err.code === 'ENOENT') return { task: null, source: null, ids: [], file, found: false };
+    if (err.code === 'ENOENT') return { tasks: [], ids: [], file, found: false };
     throw new Error(`${file}: ${err.message}`);
   }
 }
 
-export async function savePlan(root, { task, source, ids }) {
+export async function savePlan(root, tasks) {
   const file = await planPath(root);
   await mkdir(join(root, DIR), { recursive: true });
-  // Exactly three fields. A field added here is a field that can contradict a document.
-  const body = { task: task ?? null, source: source ?? null, ids: [...new Set(ids)] };
+  // Three fields per task and nothing else. A field added here is a field that can
+  // contradict a document.
+  const body = {
+    tasks: tasks.map((t) => ({
+      task: t.task ?? null,
+      source: t.source ?? null,
+      ids: [...new Set(t.ids)],
+    })),
+  };
   await writeFile(file, JSON.stringify(body, null, 2) + '\n', 'utf8');
   return file;
 }
 
+/**
+ * Which tasks a name selects.
+ *
+ * Matches loosely on purpose - a person typing `--task till` should not have to reproduce
+ * "Till hardening" exactly - but reports an ambiguous match rather than picking, because
+ * working the wrong task is worse than being asked again.
+ */
+export function selectTasks(tasks, names = []) {
+  if (!names.length) return { selected: tasks, unmatched: [], ambiguous: [] };
+  const selected = [];
+  const unmatched = [];
+  const ambiguous = [];
+  for (const name of names) {
+    const needle = String(name).toLowerCase();
+    const hits = tasks.filter((t) => (t.task ?? '').toLowerCase().includes(needle));
+    if (!hits.length) unmatched.push(name);
+    else if (hits.length > 1) ambiguous.push({ name, matched: hits.map((h) => h.task) });
+    else if (!selected.includes(hits[0])) selected.push(hits[0]);
+  }
+  return { selected, unmatched, ambiguous };
+}
+
 export async function clearPlan(root) {
   await rm(await planPath(root), { force: true });
 }
@@ -114,14 +170,27 @@ export function resolveItems(inputs, scenarios) {
  * deleted is stale, and that failure is silent by nature - a missing item simply does not
  * appear anywhere.
  */
-export function readPlan(plan, scenarios) {
+export function readPlan(plan, scenarios, tasks = null) {
   const byId = new Map(scenarios.filter((s) => s.id).map((s) => [s.id, s]));
+  // Tolerates the flat shape here as well as at load, so the compatibility claim holds for
+  // any caller rather than only for a file read off disk.
+  const groups = tasks ?? (plan.tasks ? plan.tasks : normalise(plan));
   const live = [];
   const orphaned = [];
-  for (const id of plan.ids ?? []) {
-    const hit = byId.get(id);
-    if (hit) live.push(hit);
-    else orphaned.push(id);
+  const seen = new Set();
+  for (const group of groups) {
+    for (const id of group.ids) {
+      const hit = byId.get(id);
+      if (!hit) {
+        orphaned.push({ id, task: group.task });
+        continue;
+      }
+      if (seen.has(id)) continue;
+      seen.add(id);
+      // The task an id was declared under travels with it, because with two in flight the
+      // useful question is not "is this planned" but "which of these am I looking at".
+      live.push({ ...hit, planTask: group.task, planSource: group.source });
+    }
   }
   return { live, orphaned };
 }

package/src/server.js

@@ -20,11 +20,18 @@ import { setStatus, addNote, setFlag, clearNotes } from './write.js';
 import { indexVideos, videoFor, expectedPath } from './videos.js';
 import { listStandardDocs, readStandardDoc } from './standard.js';
 import { loadPlan } from './plan.js';
+import { STANDARD_VERSION } from './version.js';
 import { loadSettings } from './config.js';
 import { loadTerms, renderTerms } from './terms.js';
 import { branchName, repoName } from './media.js';
 
 const PUBLIC_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'public');
+const PKG = JSON.parse(
+  await readFile(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')
+);
+
+/** When this process started, so a stale server can be reported with its age. */
+const STARTED = new Date().toISOString();
 
 const MIME = {
   '.html': 'text/html; charset=utf-8',
@@ -197,6 +204,19 @@ export function createReviewServer(rootsOrLoader, opts = {}) {
       const roots = await getRoots();
       const url = new URL(req.url ?? '/', 'http://localhost');
 
+      // What is ACTUALLY running, asked of the process rather than inferred from a pidfile
+      // the CLI wrote. A long-lived server keeps serving the code it started with, so after
+      // an upgrade the binary on PATH and the process answering the browser are different
+      // versions - and nothing said so.
+      if (req.method === 'GET' && url.pathname === '/api/version') {
+        return json(res, 200, {
+          package: PKG.version,
+          standard: STANDARD_VERSION,
+          pid: process.pid,
+          started: STARTED,
+        });
+      }
+
       if (req.method === 'GET' && url.pathname === '/api/events') {
         res.writeHead(200, {
           'content-type': 'text/event-stream',
@@ -279,6 +299,8 @@ export function createReviewServer(rootsOrLoader, opts = {}) {
         // globally because each worktree is its own registered entry with its own branch
         // and its own plan - which is what lets several people work at once without their
         // batches bleeding into each other's page.
+        // Which task each id was declared under, so the page can narrow to a set of them
+        // the same way the command line does.
         const planned = new Map();
         // The glossary, per project. The page is where a person READS criteria, so it shows
         // the words the product uses; the raw markers stay in the payload because that is
@@ -287,9 +309,11 @@ export function createReviewServer(rootsOrLoader, opts = {}) {
         for (const root of roots) {
           try {
             const plan = await loadPlan(root.path);
-            planned.set(root.name, new Set(plan.ids ?? []));
+            const byId = new Map();
+            for (const t of plan.tasks ?? []) for (const id of t.ids) byId.set(id, t.task);
+            planned.set(root.name, byId);
           } catch {
-            planned.set(root.name, new Set());
+            planned.set(root.name, new Map());
           }
           try {
             const settings = await loadSettings(root.path);
@@ -326,6 +350,7 @@ export function createReviewServer(rootsOrLoader, opts = {}) {
             // should read the same whoever is looking at it. Display only, unlike
             // `source`, which reaches a committed artefact.
             inPlan: planned.get(s.project)?.has(s.id) ?? false,
+            planTask: planned.get(s.project)?.get(s.id) ?? null,
             titleDisplay: renderTerms(s.title, glossaries.get(s.project) ?? {}).rendered,
             stepsDisplay: (s.steps ?? []).map(
               (t) => renderTerms(t, glossaries.get(s.project) ?? {}).rendered
@@ -346,6 +371,10 @@ export function createReviewServer(rootsOrLoader, opts = {}) {
           }
         }
         return json(res, 200, {
+          // Stamped so a page can tell it is older than the server it is talking to. An open
+          // tab keeps updating its DATA over SSE while running the JS it loaded hours ago, so
+          // without this an upgrade looks like a broken feature rather than a stale page.
+          standardVersion: STANDARD_VERSION,
           scenarios,
           projects: results.map((r) => ({
             name: r.project,
@@ -444,7 +473,15 @@ export function createReviewServer(rootsOrLoader, opts = {}) {
         if (name.includes('..')) return json(res, 400, { error: 'Bad path' });
         try {
           const buf = await readFile(join(PUBLIC_DIR, name));
-          res.writeHead(200, { 'content-type': MIME[extname(name)] ?? 'text/plain' });
+          res.writeHead(200, {
+            'content-type': MIME[extname(name)] ?? 'text/plain',
+            // Always revalidate. This tool is designed to be left open for hours and to
+            // upgrade underneath itself, and a cached script keeps rendering by the
+            // previous release's rules while its DATA updates live - which looks like the
+            // new feature is broken rather than like the page is old. The files are local,
+            // so revalidating costs nothing.
+            'cache-control': 'no-cache',
+          });
           return res.end(buf);
         } catch {
           return json(res, 404, { error: 'Not found' });

package/src/terms.js

@@ -85,6 +85,38 @@ export function renderTerms(text, terms = {}) {
   return { rendered, missing };
 }
 
+/**
+ * Text that SPELLS a word the glossary owns, instead of naming the concept.
+ *
+ * This is the drift the glossary exists to prevent, caught at the moment it is introduced
+ * rather than at the next rename. A criterion reading "a Company must have an owner" looks
+ * perfectly correct today and is silently wrong the day Company becomes something else.
+ *
+ * Matched case-insensitively on whole words against `value` and `plural`, because a
+ * criterion writing "company" mid-sentence means the term just as much as one writing it
+ * capitalised. Reported rather than corrected: whether a word names the domain concept or is
+ * ordinary prose is a judgement, and a glossary that swallows ordinary English makes
+ * documents unreadable.
+ *
+ * Text already inside a marker cannot match, because markers hold KEYS and keys name the
+ * internal domain rather than the visible word.
+ */
+export function findSpelledTerms(text, terms = {}) {
+  const bare = String(text ?? '').replace(MARKER, ' ');
+  const hits = [];
+  for (const [key, term] of Object.entries(terms)) {
+    for (const form of [term.value, term.plural]) {
+      if (!form) continue;
+      const pattern = new RegExp(`\\b${form.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'gi');
+      if (pattern.test(bare)) {
+        hits.push({ key, spelled: form });
+        break;
+      }
+    }
+  }
+  return hits;
+}
+
 /** Every problem in a manifest, reported together rather than one run at a time. */
 export function validateTerms(terms) {
   const problems = [];