criteria-review 0.3.0 → 0.3.3

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,26 @@ 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.
+  // `serve` is how a backgrounded server is spawned (see cmdStart), and no args at all is
+  // the foreground UI. Everything else reaching here is unrecognised.
+  //
+  // NAMED EXPLICITLY rather than left to fall through, which is what made the first
+  // version of this guard reject the tool's own subprocess and break `start`, `here` and
+  // `restart` in a published release. A guard that does not know the commands it is
+  // guarding is a guess.
+  if (cmd !== undefined && cmd !== 'serve') {
+    throw new Error(`unknown command "${cmd}". Run: criteria-review help`);
+  }
+  if (args._.some((a) => a.startsWith('-'))) {
+    throw new Error(
+      `unknown option "${args._.find((a) => a.startsWith('-'))}". 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
@@ -65,9 +65,15 @@ The keyboard drives it. The bar along the bottom of the page is the whole cheat
 | `n` | write a note on it |
 | `f` | fullscreen the recording |
 | `r` | reload from disk |
+| `t` | switch between the flat queue and the grouped tree |
 | `/` | jump to the filter box |
 | `s` | switch between the queue and this reading tab |
 
+Two ways to read the list, for two different questions. **Flat** is the queue: one ordered run,
+riskiest first, which is what a review pass wants. **Tree** groups by document and feature, which
+is what "where does this live, and what else is near it" wants. Groups collapse, and moving the
+selection into a collapsed group opens it rather than selecting something you cannot see.
+
 **Every action writes straight into the source markdown**, next to the scenario it is about.
 There is no database. Your notes are sourced intent, which is the one thing that cannot be
 reconstructed from the code later, so they belong in git beside what they annotate.
@@ -112,19 +118,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 +139,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 +158,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.3",
   "private": false,
   "description": "Review acceptance criteria across projects, and generate the scenario clauses your tests cite.",
   "license": "MIT",

package/public/app.js

@@ -35,6 +35,12 @@ const state = {
   tab: 'review',
   docs: [],
   doc: null,
+  // Flat is the queue: one ordered list, riskiest first, which is what a review PASS
+  // wants. Tree is the map: which document holds what, and which feature inside it,
+  // which is what someone answering "where does this live" wants. Different questions,
+  // so both, rather than a compromise that serves neither.
+  tree: false,
+  collapsed: new Set(),
 };
 
 /**
@@ -67,6 +73,8 @@ function saveViewState() {
         selected: scenarioKey(state.view[state.index]),
         tab: state.tab,
         doc: state.doc,
+        tree: state.tree,
+        collapsed: [...state.collapsed],
       })
     );
   } catch {
@@ -93,6 +101,8 @@ function restoreViewState() {
   // document who refreshes should be back on it, not at the top of the queue.
   state.doc = saved.doc ?? null;
   state.savedTab = saved.tab === 'standard' ? 'standard' : 'review';
+  state.tree = saved.tree === true;
+  state.collapsed = new Set(Array.isArray(saved.collapsed) ? saved.collapsed : []);
 }
 
 /**
@@ -237,26 +247,9 @@ function renderCounts() {
     .join('');
 }
 
-function renderList() {
-  // A header whenever the document changes, so the batch boundary is visible.
-  // Without it the grouping is real but invisible, and a reviewer cannot tell
-  // whether the next item continues the current feature or starts a new one.
-  let lastDoc = null;
-  $('#list').innerHTML = state.view
-    .map((s, i) => {
-      const doc = `${s.project} ${s.source}`;
-      let header = '';
-      if (doc !== lastDoc) {
-        lastDoc = doc;
-        const remaining = state.view.filter((x) => `${x.project} ${x.source}` === doc).length;
-        header = `<div class="doc-head">
-            <span class="doc-name">${escapeHtml(s.source.split('/').slice(-1)[0])}</span>
-            <span class="doc-meta">${escapeHtml(s.project)} · ${remaining}</span>
-          </div>`;
-      }
-      return (
-        header +
-        `<button class="row ${i === state.index ? 'active' : ''} ${
+/** One scenario row. Shared by both views so they cannot drift in how a scenario reads. */
+function scenarioRow(s, i, depth = 0) {
+  return `<button class="row depth-${depth} ${i === state.index ? 'active' : ''} ${
           state.highlight.has(s.id) ? 'highlighted' : ''
         }" data-i="${i}">
           <span class="row-top">${flagged(s) ? '<span class="looknow">LOOK</span>' : ''}${
@@ -271,10 +264,90 @@ function renderList() {
                 }">!</span>`
           }</span>
           <span class="row-title">${escapeHtml(s.title)}</span>
-        </button>`
-      );
+        </button>`;
+}
+
+/** The queue: one ordered list, with a header where the document changes. */
+function renderFlat() {
+  // A header whenever the document changes, so the batch boundary is visible. Without
+  // it the grouping is real but invisible, and a reviewer cannot tell whether the next
+  // item continues the current feature or starts a new one.
+  let lastDoc = null;
+  return state.view
+    .map((s, i) => {
+      const doc = `${s.project} ${s.source}`;
+      let header = '';
+      if (doc !== lastDoc) {
+        lastDoc = doc;
+        const remaining = state.view.filter((x) => `${x.project} ${x.source}` === doc).length;
+        header = `<div class="doc-head">
+            <span class="doc-name">${escapeHtml(s.source.split('/').slice(-1)[0])}</span>
+            <span class="doc-meta">${escapeHtml(s.project)} · ${remaining}</span>
+          </div>`;
+      }
+      return header + scenarioRow(s, i);
     })
     .join('');
+}
+
+/**
+ * The map: project, document, feature, scenario.
+ *
+ * Groups keep the order of FIRST APPEARANCE in the queue rather than sorting
+ * alphabetically, so the riskiest document is still at the top and the two views agree
+ * about what matters most. A tree that reordered the queue would quietly disagree with
+ * every other surface about where to start.
+ */
+function renderTree() {
+  const tree = new Map();
+  state.view.forEach((s, i) => {
+    const docKey = `${s.project}|${s.source}`;
+    if (!tree.has(docKey)) tree.set(docKey, { scenario: s, features: new Map() });
+    const featureKey = s.feature ?? '';
+    const features = tree.get(docKey).features;
+    if (!features.has(featureKey)) features.set(featureKey, []);
+    features.get(featureKey).push([s, i]);
+  });
+
+  const caret = (open) => `<span class="caret">${open ? '▾' : '▸'}</span>`;
+  const out = [];
+
+  for (const [docKey, { scenario, features }] of tree) {
+    const docOpen = !state.collapsed.has(docKey);
+    const count = [...features.values()].reduce((n, list) => n + list.length, 0);
+    out.push(
+      `<div class="doc-head tree-head" data-group="${escapeHtml(docKey)}">
+        ${caret(docOpen)}
+        <span class="doc-name">${escapeHtml(scenario.source.split('/').slice(-1)[0])}</span>
+        <span class="doc-meta">${escapeHtml(scenario.project)} · ${count}</span>
+      </div>`
+    );
+    if (!docOpen) continue;
+
+    for (const [featureKey, list] of features) {
+      const featKey = `${docKey}|${featureKey}`;
+      const featOpen = !state.collapsed.has(featKey);
+      // A document with no Feature headings would otherwise grow a nameless level that
+      // costs a click and says nothing.
+      const named = featureKey !== '';
+      if (named) {
+        out.push(
+          `<div class="feature-head" data-group="${escapeHtml(featKey)}">
+            ${caret(featOpen)}
+            <span>${escapeHtml(featureKey)}</span>
+            <span class="doc-meta">${list.length}</span>
+          </div>`
+        );
+        if (!featOpen) continue;
+      }
+      for (const [s, i] of list) out.push(scenarioRow(s, i, named ? 1 : 0));
+    }
+  }
+  return out.join('');
+}
+
+function renderList() {
+  $('#list').innerHTML = state.tree ? renderTree() : renderFlat();
   const active = $('#list .row.active');
   if (active) active.scrollIntoView({ block: 'nearest' });
 }
@@ -467,9 +540,21 @@ function openNoteEditor(s) {
   };
 }
 
+function revealSelected() {
+  if (!state.tree) return;
+  const s = state.view[state.index];
+  if (!s) return;
+  const docKey = `${s.project}|${s.source}`;
+  state.collapsed.delete(docKey);
+  state.collapsed.delete(`${docKey}|${s.feature ?? ''}`);
+}
+
 function move(delta) {
   if (!state.view.length) return;
   state.index = Math.min(Math.max(state.index + delta, 0), state.view.length - 1);
+  // Before painting, not after: a selection inside a collapsed group would be real and
+  // invisible, and the reviewer would answer whatever they could see instead.
+  revealSelected();
   renderList();
   renderDetail();
   saveViewState();
@@ -601,7 +686,11 @@ async function showTab(tab) {
   $('#review-pane').hidden = tab !== 'review';
   $('#standard-pane').hidden = tab !== 'standard';
   for (const b of document.querySelectorAll('#tabs button')) {
-    b.classList.toggle('active', b.dataset.tab === tab);
+    const on = b.dataset.tab === tab;
+    b.classList.toggle('active', on);
+    // The class is what a sighted reader sees; this is what everything else reads. Setting
+    // one without the other makes the tab strip a lie to half its audience.
+    b.setAttribute('aria-selected', String(on));
   }
   // The queue's filters steer the queue and mean nothing while reading, so they go
   // rather than sit there implying they apply to what is on screen. Same for the
@@ -636,6 +725,17 @@ function moveDoc(delta) {
   openDoc(state.docs[next].name);
 }
 
+function setListMode(tree) {
+  state.tree = tree;
+  $('#view-mode').textContent = tree ? 'flat' : 'tree';
+  $('#view-mode').setAttribute('aria-pressed', String(tree));
+  revealSelected();
+  renderList();
+  saveViewState();
+}
+
+$('#view-mode').addEventListener('click', () => setListMode(!state.tree));
+
 $('#tabs').addEventListener('click', (e) => {
   const b = e.target.closest('button[data-tab]');
   if (b) showTab(b.dataset.tab);
@@ -673,7 +773,8 @@ document.addEventListener('keydown', (e) => {
     return;
   }
 
-  if (e.key === 'j') move(1);
+  if (e.key === 't') setListMode(!state.tree);
+  else if (e.key === 'j') move(1);
   else if (e.key === 'k') move(-1);
   else if (e.key === 'a') act('accepted');
   else if (e.key === 'v') act('verified');
@@ -690,6 +791,15 @@ document.addEventListener('keydown', (e) => {
 });
 
 $('#list').addEventListener('click', (e) => {
+  const group = e.target.closest('[data-group]');
+  if (group) {
+    const key = group.dataset.group;
+    if (state.collapsed.has(key)) state.collapsed.delete(key);
+    else state.collapsed.add(key);
+    renderList();
+    saveViewState();
+    return;
+  }
   const row = e.target.closest('.row');
   if (!row) return;
   state.index = Number(row.dataset.i);
@@ -781,6 +891,7 @@ function listen() {
 }
 
 restoreViewState();
+setListMode(state.tree);
 load()
   .then(listen)
   .then(() => {

package/public/index.html

@@ -9,9 +9,11 @@
   <body>
     <header class="bar">
       <h1>Criteria review</h1>
-      <nav class="tabs" id="tabs">
-        <button data-tab="review" class="active">Review</button>
-        <button data-tab="standard">Standard</button>
+      <nav class="tabs" id="tabs" role="tablist" aria-label="Views">
+        <button id="tab-review" data-tab="review" class="active"
+                role="tab" aria-selected="true" aria-controls="review-pane">Review</button>
+        <button id="tab-standard" data-tab="standard"
+                role="tab" aria-selected="false" aria-controls="standard-pane">Standard</button>
       </nav>
       <div class="counts" id="counts"></div>
       <div class="spacer"></div>
@@ -35,12 +37,14 @@
           <option value="none">no recording</option>
         </select>
         <input id="search" type="search" placeholder="filter text" />
+        <button id="view-mode" type="button" title="Flat queue or grouped tree (t)">tree</button>
       </div>
     </header>
 
     <div id="banner" class="banner" hidden title="click to dismiss"></div>
 
-    <main id="review-pane">
+    <div class="panes">
+      <main id="review-pane" role="tabpanel" aria-labelledby="tab-review">
       <aside id="list" class="list" aria-label="Scenario queue"></aside>
 
       <section id="detail" class="detail">
@@ -53,12 +57,13 @@
       deciding whether a scenario is written correctly should not have to leave the
       page and go find a repository to read the rule.
     -->
-    <main id="standard-pane" hidden>
+      <main id="standard-pane" role="tabpanel" aria-labelledby="tab-standard" hidden>
       <aside id="doc-list" class="list" aria-label="Standard documents"></aside>
       <section id="doc" class="detail md">
         <p class="empty">Select a document.</p>
       </section>
-    </main>
+      </main>
+    </div>
 
     <footer class="help">
       <!--
@@ -73,6 +78,7 @@
         <span><kbd>n</kbd> note</span>
         <span><kbd>f</kbd> fullscreen</span>
         <span><kbd>r</kbd> reload</span>
+        <span><kbd>t</kbd> tree / flat</span>
         <span><kbd>/</kbd> search</span>
       </span>
       <span id="keys-standard" class="keys" hidden>

package/public/styles.css

@@ -25,15 +25,35 @@
 
 * { box-sizing: border-box; }
 
+/*
+ * Flex column, NOT a four-row grid template.
+ *
+ * The grid version assigned rows by POSITION, so it was only correct while every child
+ * was in flow. The banner is `hidden` most of the time, which shifted each remaining
+ * child up a row: the pane took the banner's `auto` row and collapsed to its content,
+ * and the footer took the `1fr` and grew to fill the window. Adding a second view made
+ * it worse again, five children for four rows.
+ *
+ * A flex column has no positional assumption to break: the bars size to content and the
+ * pane area takes the rest, whatever is hidden.
+ */
 body {
   margin: 0;
   height: 100vh;
-  display: grid;
-  grid-template-rows: auto auto 1fr auto;
+  display: flex;
+  flex-direction: column;
   background: var(--bg);
   color: var(--text);
 }
 
+body > header,
+body > footer,
+body > .banner { flex: 0 0 auto; }
+
+/* min-height:0 is load bearing: without it a flex item refuses to shrink below its
+   content, and the scrolling panes push the footer off the bottom of the window. */
+.panes { flex: 1 1 auto; min-height: 0; }
+
 .bar {
   display: flex;
   align-items: center;
@@ -307,6 +327,41 @@ 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); }
 
+/* ---- Tree view ---- */
+
+.tree-head, .feature-head { cursor: pointer; user-select: none; }
+.tree-head:hover, .feature-head:hover { background: var(--panel-2); }
+.caret { display: inline-block; width: 12px; color: var(--muted); font-size: 10px; }
+
+.feature-head {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 5px 12px 5px 18px;
+  font-size: 12px;
+  color: var(--muted);
+  border-bottom: 1px solid var(--line);
+}
+.feature-head span:nth-child(2) { color: var(--text); }
+.feature-head .doc-meta { margin-left: auto; }
+
+/* Indent nests the row under its feature without moving the status pills, which are
+   what the eye scans down. */
+.row.depth-1 { padding-left: 26px; }
+
+#view-mode {
+  background: var(--panel);
+  border: 1px solid var(--line);
+  color: var(--muted);
+  font: inherit;
+  font-size: 12px;
+  padding: 3px 10px;
+  border-radius: 6px;
+  cursor: pointer;
+}
+#view-mode:hover { color: var(--text); }
+#view-mode[aria-pressed='true'] { color: var(--text); border-color: var(--accent); }
+
 /* ---- Reading tab: the standard and the walkthrough, beside the queue ---- */
 
 .tabs { display: flex; gap: 2px; }
@@ -327,13 +382,23 @@ kbd {
   border-color: var(--line);
 }
 
-/* The two panes share the queue's grid, so switching does not move the furniture. */
+/* Both panes occupy ONE row of the body grid, so adding a second view cannot change the
+   page's row template. Before this they were siblings of header and footer, and the body's
+   four-row template had five children to place. */
+.panes { min-height: 0; display: grid; }
+.panes > main { grid-area: 1 / 1; min-height: 0; }
+
 #standard-pane { display: grid; grid-template-columns: 320px 1fr; min-height: 0; }
 
 /* `display` set on an element or class BEATS the hidden attribute's UA rule, so a
    pane given a display here stays on screen while claiming to be hidden. Both panes
    then render stacked. Needs the same specificity to win, not !important. */
-main[hidden], .filters[hidden], .counts[hidden] { display: none; }
+/* ID + attribute, because `#standard-pane { display: grid }` is an ID selector and beats a
+   plain `main[hidden]`. That mismatch shipped: the pane reported hidden === true while
+   computing display:grid, and rendered under the other one. */
+#review-pane[hidden], #standard-pane[hidden], .filters[hidden], .counts[hidden] {
+  display: none;
+}
 
 /* The two key-hint rows swap; the hidden one must actually go. */
 .keys { display: contents; }