criteria-review 0.7.2 → 0.8.0

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

@@ -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,7 +80,8 @@ 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.
@@ -219,7 +221,8 @@ function usage() {
   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>
+                                        --task <name>      repeatable: several in flight
+                                        --source <where it came from>
   criteria-review terms [show|check]  the glossary: what it defines and what documents use
   criteria-review manifest            evidence index: scenarios, clips, and the work item
                                         --out <file>      write it (default: stdout)
@@ -229,6 +232,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 +535,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 +584,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 +620,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. */
@@ -705,10 +753,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 +779,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 +800,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 +815,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 ?? []) {

package/package.json

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

package/public/app.js

@@ -71,6 +71,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 +96,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
@@ -181,8 +183,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))
@@ -615,6 +620,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;
@@ -828,7 +846,7 @@ $('#detail').addEventListener('click', (e) => {
   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/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

@@ -279,6 +279,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 +289,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 +330,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