@marcomigozzi/trailhead 0.15.0 → 0.16.1

package/plugins/trailhead/hooks/lib/needs-you.test.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-needs-you.js. Run: node needs-you.test.js
+// No framework: plain asserts, same style as uat-followup.test.js.
+//
+// Layers covered:
+//   1. main() (park, clear) against a fake tracker behind an injected `gh` and guard.
+//   2. End-to-end: the script itself with a fake `gh` on PATH.
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const scriptPath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-needs-you.js');
+const { main } = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const fakeGuard = { scan: (text) => (/ghp_[A-Za-z0-9]{20,}/.test(text) ? 'github token' : null) };
+
+// --- fake tracker ------------------------------------------------------------
+// One issue: labels [names], assignees [logins], comments [bodies]. failOn names the
+// gh step that fails: ensure | view | comment | unassign | label | remove.
+function makeTracker(init = {}) {
+  const t = { labels: init.labels || [], assignees: init.assignees || [], comments: init.comments || [], failOn: init.failOn || null, badJson: !!init.badJson, calls: [], ensured: false };
+  const res = (stdout, status = 0) => ({ status, stdout, stderr: status ? 'forced failure' : '' });
+  const step = (name, fn) => (t.failOn === name ? res('', 1) : fn());
+  t.gh = (args) => {
+    t.calls.push(args.join(' '));
+    const [a, b] = args;
+    if (a === 'label' && b === 'create') return step('ensure', () => { t.ensured = true; return res(''); });
+    if (a === 'issue' && b === 'view') {
+      return step('view', () => (t.badJson ? res('not json') : res(JSON.stringify({
+        labels: t.labels.map((name) => ({ name })),
+        assignees: t.assignees.map((login) => ({ login })),
+        comments: t.comments.map((body) => ({ body })),
+      }))));
+    }
+    if (a === 'issue' && b === 'comment') return step('comment', () => { t.comments.push(args[args.indexOf('--body') + 1]); return res(''); });
+    if (a === 'issue' && b === 'edit') {
+      if (args.includes('--remove-assignee')) return step('unassign', () => { t.assignees = []; return res(''); });
+      if (args.includes('--add-label')) return step('label', () => { t.labels.push(args[args.indexOf('--add-label') + 1]); return res(''); });
+      if (args.includes('--remove-label')) return step('remove', () => { const l = args[args.indexOf('--remove-label') + 1]; t.labels = t.labels.filter((x) => x !== l); return res(''); });
+    }
+    return res('', 1);
+  };
+  return t;
+}
+
+function run(t, argv, extra = {}) {
+  let out = '';
+  let errOut = '';
+  const code = main(argv, { gh: t.gh, guard: fakeGuard, stdout: { write: (s) => { out += s; } }, stderr: { write: (s) => { errOut += s; } }, ...extra });
+  let json = null;
+  try { json = JSON.parse(out.trim()); } catch { /* not json */ }
+  return { code, out, json, errOut };
+}
+
+const park = (reason = 'Decide between A and B') => ['park', '--issue', '7', '--reason', reason, '--repo', 'o/r'];
+const clear = ['clear', '--issue', '7', '--repo', 'o/r'];
+const idx = (t, re) => t.calls.findIndex((c) => re.test(c));
+
+// --- park: order and output ----------------------------------------------------
+{
+  const t = makeTracker({ assignees: ['me'], labels: ['trailhead:ticket'] });
+  const r = run(t, park());
+  ok('park ok, one JSON line', r.code === 0 && r.json.status === 'ok' && r.out.trim().split('\n').length === 1);
+  ok('park output fields', r.json.issue === 7 && r.json.commented === true && r.json.unassigned === true && r.json.labelled === true);
+  ok('comment body is NEEDS YOU, a blank line, then the reason', t.comments[0] === 'NEEDS YOU\n\nDecide between A and B');
+  const iE = idx(t, /^label create trailhead:needs-you .*--force/);
+  const iV = idx(t, /^issue view 7 --json labels,assignees,comments/);
+  const iC = idx(t, /^issue comment 7/);
+  const iU = idx(t, /--remove-assignee @me/);
+  const iL = idx(t, /--add-label trailhead:needs-you/);
+  ok('call order: ensure, view, comment, unassign, label', iE >= 0 && iE < iV && iV < iC && iC < iU && iU < iL);
+  ok('label ensured with the color and description', t.calls[iE].includes('--color D93F0B') && t.calls[iE].includes('--description'));
+  ok('-R passed on every call', t.calls.every((c) => c.includes('-R o/r')));
+  ok('final state: unassigned and labelled', t.assignees.length === 0 && t.labels.includes('trailhead:needs-you'));
+}
+
+// --- park: idempotence ---------------------------------------------------------
+{
+  const t = makeTracker({ assignees: ['me'] });
+  run(t, park());
+  const before = t.comments.length;
+  const r = run(t, park('  Decide   between A\nand B '));
+  ok('same reason (whitespace-normalised) posts no second comment', t.comments.length === before && r.json.commented === false);
+  ok('re-park on an already-labelled unassigned ticket is ok', r.code === 0 && r.json.unassigned === false && r.json.labelled === false && t.labels.filter((l) => l === 'trailhead:needs-you').length === 1);
+  const r2 = run(t, park('A different reason'));
+  ok('a different reason posts a new comment', r2.json.commented === true && t.comments.length === before + 1);
+  const r3 = run(t, park('Decide between A and B'));
+  ok('only the latest NEEDS YOU comment is compared', r3.json.commented === true);
+  const t2 = makeTracker({ comments: ['NEEDS YOUR attention\n\nx', 'unrelated'] });
+  ok('a non NEEDS YOU comment does not dedup', run(t2, park('x')).json.commented === true);
+}
+
+// --- park: guards and failures --------------------------------------------------
+{
+  const t = makeTracker({ assignees: ['me'] });
+  const r = run(t, park('token ghp_abcdefghijklmnopqrstuvwxyz0123'));
+  ok('a secret in the reason writes nothing', r.code === 1 && r.json.status === 'error' && /secret/.test(r.json.reason) && t.calls.length === 0);
+  const t2 = makeTracker();
+  const r2 = run(t2, park(), { guard: null });
+  ok('a missing guard fails closed', r2.code === 1 && r2.json.status === 'error' && t2.calls.length === 0);
+}
+for (const [failOn, later] of [['ensure', ['view', 'comment', 'unassign', 'label']], ['view', ['comment', 'unassign', 'label']], ['comment', ['unassign', 'label']], ['unassign', ['label']], ['label', []]]) {
+  const t = makeTracker({ assignees: ['me'], failOn });
+  const r = run(t, park());
+  ok(`failing ${failOn} is status error, exit 1`, r.code === 1 && r.json.status === 'error' && r.json.reason.length > 0);
+  ok(`after ${failOn} fails, later steps do not run`, later.every((s) => !t.calls.some((c) => ({ view: /issue view/, comment: /issue comment/, unassign: /--remove-assignee/, label: /--add-label/ })[s].test(c))));
+}
+{
+  const t = makeTracker({ assignees: ['me'], failOn: 'unassign' });
+  run(t, park());
+  ok('a failed unassign leaves no label', !t.labels.includes('trailhead:needs-you'));
+  const tb = makeTracker({ badJson: true });
+  const r = run(tb, park());
+  ok('unparseable view JSON is an error, nothing written', r.code === 1 && r.json.status === 'error' && tb.comments.length === 0);
+}
+
+// --- clear ----------------------------------------------------------------------
+{
+  const t = makeTracker({ labels: ['trailhead:ticket', 'trailhead:needs-you'] });
+  const r = run(t, clear);
+  ok('clear removes the label when present', r.code === 0 && r.json.status === 'ok' && r.json.issue === 7 && r.json.cleared === true && !t.labels.includes('trailhead:needs-you'));
+  const r2 = run(t, clear);
+  ok('clear is a no-op when absent', r2.code === 0 && r2.json.cleared === false && t.calls.filter((c) => /--remove-label/.test(c)).length === 1);
+  const tf = makeTracker({ labels: ['trailhead:needs-you'], failOn: 'remove' });
+  ok('clear errors on a failed removal', run(tf, clear).code === 1);
+  const tv = makeTracker({ failOn: 'view' });
+  const rv = run(tv, clear);
+  ok('clear errors on a failed read', rv.code === 1 && rv.json.status === 'error');
+  ok('clear errors on unparseable JSON', run(makeTracker({ badJson: true }), clear).code === 1);
+}
+
+// --- usage ----------------------------------------------------------------------
+for (const argv of [[], ['bogus'], ['park'], ['park', '--issue', '7', '--repo', 'o/r'], ['park', '--issue', 'x', '--reason', 'r', '--repo', 'o/r'],
+  ['park', '--issue', '7', '--reason', '  ', '--repo', 'o/r'], ['park', '--issue', '7', '--reason', 'r'], ['clear', '--issue', '7'], ['clear', '--repo', 'o/r'],
+  ['clear', '--issue', '7', '--repo', 'nope'], ['clear', '--issue', '7', '--repo', 'o/r', '--reason', 'r'], ['clear', '--issue']]) {
+  const t = makeTracker();
+  const r = run(t, argv);
+  ok(`usage error exit 2: ${argv.join(' ')}`, r.code === 2 && t.calls.length === 0 && r.errOut.length > 0);
+}
+
+// --- end-to-end with a fake gh on PATH --------------------------------------------
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'needs-you-'));
+  const binDir = path.join(tmp, 'bin');
+  fs.mkdirSync(binDir);
+  const log = path.join(tmp, 'calls.log');
+  const script = `#!/bin/sh
+echo "$*" >> "${log}"
+case "$*" in
+  "issue view"*)
+    if grep -q -- '--add-label' "${log}"; then L='{"name":"trailhead:needs-you"}'; else L=''; fi
+    echo "{\\"labels\\":[$L],\\"assignees\\":[{\\"login\\":\\"me\\"}],\\"comments\\":[]}" ;;
+  *) exit 0 ;;
+esac
+`;
+  fs.writeFileSync(path.join(binDir, 'gh'), script, { mode: 0o755 });
+  const env = { ...process.env, PATH: binDir + path.delimiter + process.env.PATH };
+  const res = spawnSync('node', [scriptPath, ...park('Needs a human call')], { encoding: 'utf8', env });
+  const j = JSON.parse(res.stdout.trim());
+  ok('e2e: park prints one ok JSON line', res.status === 0 && j.status === 'ok' && j.commented === true && j.unassigned === true);
+  const calls = fs.readFileSync(log, 'utf8');
+  ok('e2e: comment before unassign before label', calls.indexOf('issue comment') < calls.indexOf('--remove-assignee') && calls.indexOf('--remove-assignee') < calls.indexOf('--add-label'));
+  const cl = spawnSync('node', [scriptPath, ...clear], { encoding: 'utf8', env });
+  ok('e2e: clear removes the present label', cl.status === 0 && JSON.parse(cl.stdout.trim()).cleared === true && fs.readFileSync(log, 'utf8').includes('--remove-label trailhead:needs-you'));
+  fs.writeFileSync(path.join(binDir, 'gh'), '#!/bin/sh\nexit 1\n', { mode: 0o755 });
+  const bad = spawnSync('node', [scriptPath, ...clear], { encoding: 'utf8', env });
+  ok('e2e: gh failing exits 1 with an error line', bad.status === 1 && JSON.parse(bad.stdout.trim()).status === 'error');
+  ok('e2e: usage error exits 2', spawnSync('node', [scriptPath, '--bogus'], { encoding: 'utf8' }).status === 2);
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+console.log(`needs-you.test.js: ${passed} checks passed`);

package/plugins/trailhead/hooks/lib/plan-review-rounds.test.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-plan-review-rounds.js. Run: node plan-review-rounds.test.js
+// No framework: plain asserts, same style as auto-slot.test.js.
+//
+// Layers covered:
+//   1. ask: config lookup, roster resolution, host drop, unknown names, options menu.
+//   2. round: converged / continue / exhausted / no-progress / ceiling and their precedence.
+//   3. Usage errors (exit 2).
+//   4. End-to-end: the script itself through spawnSync.
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const scriptPath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-plan-review-rounds.js');
+const { main } = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+function run(argv, deps = {}) {
+  let out = '';
+  let errOut = '';
+  const code = main(argv, { stdout: { write: (s) => { out += s; } }, stderr: { write: (s) => { errOut += s; } }, ...deps });
+  let json = null;
+  try { json = JSON.parse(out.trim()); } catch { /* not json */ }
+  return { code, out, json, errOut };
+}
+
+const tmp = () => fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'plan-review-rounds-')));
+const rm = (d) => fs.rmSync(d, { recursive: true, force: true });
+
+// A project root and a global config dir holding the given config objects (null = no file).
+function setup(project, global) {
+  const root = tmp();
+  const gdir = tmp();
+  if (project !== null && project !== undefined) {
+    fs.mkdirSync(path.join(root, '.trailhead'), { recursive: true });
+    fs.writeFileSync(path.join(root, '.trailhead', 'config.json'), typeof project === 'string' ? project : JSON.stringify(project));
+  }
+  if (global !== null && global !== undefined) {
+    fs.mkdirSync(path.join(gdir, 'trailhead'), { recursive: true });
+    fs.writeFileSync(path.join(gdir, 'trailhead', 'config.json'), typeof global === 'string' ? global : JSON.stringify(global));
+  }
+  return { root, gdir, done: () => { rm(root); rm(gdir); } };
+}
+
+// Deps with a fixed set of binaries "on PATH" and a canned kimi --help.
+const deps = (gdir, installed, kimiHelp = '--output-format json') => ({
+  env: { CLAUDE_CONFIG_DIR: gdir, PATH: '/nowhere' },
+  which: (name) => installed.includes(name),
+  kimiHelp: () => kimiHelp,
+});
+
+const ask = (s, installed, extra = [], kimiHelp) => run(['ask', '--repo', s.root, ...extra], deps(s.gdir, installed, kimiHelp));
+const values = (r) => r.json.options.map((o) => o.value);
+
+// --- ask: skip ---------------------------------------------------------------
+{
+  const s = setup({}, null);
+  const r = ask(s, ['codex', 'gemini']);
+  ok('ask: plan_review unset is skip off', r.code === 0 && r.json.status === 'skip' && r.json.reason === 'off' && r.json.configured === 2);
+  s.done();
+}
+{
+  const s = setup({ plan_review: 'off', 'plan_review.rounds': 4 }, null);
+  const r = ask(s, ['codex']);
+  ok('ask: plan_review off is skip off with the configured rounds', r.json.status === 'skip' && r.json.reason === 'off' && r.json.configured === 4);
+  s.done();
+}
+{
+  const s = setup({ plan_review: 'on' }, null);
+  const r = ask(s, []);
+  ok('ask: on with nothing installed is skip no-reviewer', r.code === 0 && r.json.status === 'skip' && r.json.reason === 'no-reviewer');
+  const own = ask(s, ['claude']);
+  ok('ask: only the host CLI installed is skip no-reviewer', own.json.status === 'skip' && own.json.reason === 'no-reviewer');
+  const codexHost = ask(s, ['codex'], ['--host', 'codex']);
+  ok('ask: --host codex drops codex', codexHost.json.status === 'skip' && codexHost.json.reason === 'no-reviewer');
+  const claudeOnCodex = ask(s, ['claude'], ['--host', 'codex']);
+  ok('ask: --host codex keeps claude as an independent reviewer', claudeOnCodex.json.status === 'ask' && JSON.stringify(claudeOnCodex.json.reviewers) === '["claude"]');
+  s.done();
+}
+
+// --- ask: roster resolution --------------------------------------------------
+{
+  const s = setup({ plan_review: 'on' }, null);
+  const r = ask(s, ['claude', 'codex', 'gemini', 'agy', 'cursor-agent', 'not-in-roster']);
+  ok('ask: on resolves the whole roster minus the host, in roster order', r.json.status === 'ask' && JSON.stringify(r.json.reviewers) === JSON.stringify(['gemini', 'codex', 'agy', 'cursor-agent']));
+  ok('ask: on ignores binaries outside the roster', !r.json.reviewers.includes('not-in-roster') && r.json.unknown.length === 0);
+  ok('ask: reports the configured count', r.json.configured === 2);
+  s.done();
+}
+{
+  const s = setup({ plan_review: 'codex, gemini' }, null);
+  const r = ask(s, ['codex', 'gemini', 'qwen']);
+  ok('ask: a comma list restricts the candidates', JSON.stringify(r.json.reviewers) === JSON.stringify(['codex', 'gemini']));
+  const only = ask(s, ['gemini']);
+  ok('ask: a listed CLI that is not installed is not counted', JSON.stringify(only.json.reviewers) === '["gemini"]' && only.json.unknown.length === 0);
+  s.done();
+}
+
+// --- ask: kimi probe ---------------------------------------------------------
+{
+  const s = setup({ plan_review: 'kimi' }, null);
+  ok('ask: kimi counts when --help mentions --output-format', ask(s, ['kimi'], [], 'usage: kimi --output-format').json.status === 'ask');
+  const legacy = ask(s, ['kimi'], [], 'usage: kimi [--print]');
+  ok('ask: legacy kimi (no --output-format) does not count', legacy.json.status === 'skip' && legacy.json.reason === 'no-reviewer');
+  const noHelp = ask(s, ['kimi'], [], null);
+  ok('ask: a failing kimi --help does not count', noHelp.json.status === 'skip');
+  let probes = 0;
+  const o = run(['ask', '--repo', s.root], { ...deps(s.gdir, []), kimiHelp: () => { probes++; return '--output-format'; } });
+  ok('ask: kimi is not probed when its binary is absent', probes === 0 && o.json.status === 'skip');
+  s.done();
+}
+
+// --- ask: unknown names ------------------------------------------------------
+{
+  const s = setup({ plan_review: 'codex,my-local,tpyo' }, null);
+  const r = ask(s, ['codex', 'my-local']);
+  ok('ask: a custom reviewer counts when its binary is on PATH', JSON.stringify(r.json.reviewers) === JSON.stringify(['codex', 'my-local']));
+  ok('ask: a custom reviewer on PATH is not unknown', !r.json.unknown.includes('my-local'));
+  ok('ask: an unknown name with no binary is listed, not counted, and warned', JSON.stringify(r.json.unknown) === '["tpyo"]' && !r.json.reviewers.includes('tpyo') && r.json.warnings.some((w) => w.includes('tpyo')));
+  const typoOnly = setup({ plan_review: 'tpyo' }, null);
+  const t = ask(typoOnly, ['codex']);
+  ok('ask: a list of only unknown absent names is skip no-reviewer, still reporting unknown', t.json.status === 'skip' && t.json.reason === 'no-reviewer' && JSON.stringify(t.json.unknown) === '["tpyo"]');
+  typoOnly.done();
+  s.done();
+}
+
+// --- ask: options menu -------------------------------------------------------
+{
+  const mk = (rounds) => {
+    const s = setup({ plan_review: 'codex', 'plan_review.rounds': rounds }, null);
+    const r = ask(s, ['codex']);
+    s.done();
+    return r;
+  };
+  const r2 = mk(2);
+  ok('options: n=2 is config(2) Recommended first, then 1, 3, until', JSON.stringify(values(r2)) === JSON.stringify(['config', '1', '3', 'until']) && r2.json.options[0].recommended === true && r2.json.options[0].label === 'As in config (2)');
+  ok('options: only the first entry is recommended', r2.json.options.slice(1).every((o) => !o.recommended));
+  ok('options: every entry has a human label', r2.json.options.every((o) => typeof o.label === 'string' && o.label.length > 0));
+  ok('options: n=1 is config, 2, 3, until', JSON.stringify(values(mk(1))) === JSON.stringify(['config', '2', '3', 'until']));
+  ok('options: n=3 is config, 1, 2, until', JSON.stringify(values(mk(3))) === JSON.stringify(['config', '1', '2', 'until']));
+  const r5 = mk(5);
+  ok('options: n=5 is config(5), 1, 2, until', JSON.stringify(values(r5)) === JSON.stringify(['config', '1', '2', 'until']) && r5.json.options[0].label === 'As in config (5)');
+  ok('options: never more than four entries', [1, 2, 3, 4, 7, 12].every((n) => mk(n).json.options.length <= 4));
+  ok('options: the numbered-list fallback lists all five', JSON.stringify(r2.json.fallback.map((o) => o.value)) === JSON.stringify(['config', '1', '2', '3', 'until']));
+}
+
+// --- ask: rounds fallback ----------------------------------------------------
+{
+  for (const bad of [0, -1, 1.5, 'two', null]) {
+    const s = setup({ plan_review: 'codex', 'plan_review.rounds': bad }, null);
+    const r = ask(s, ['codex']);
+    ok(`rounds: ${JSON.stringify(bad)} falls back to 2 with a warning`, r.code === 0 && r.json.configured === 2 && r.json.warnings.some((w) => w.includes('plan_review.rounds')));
+    s.done();
+  }
+  const s = setup({ plan_review: 'codex' }, null);
+  const r = ask(s, ['codex']);
+  ok('rounds: unset is 2 without a warning', r.json.configured === 2 && r.json.warnings.length === 0);
+  s.done();
+}
+
+// --- ask: config lookup ------------------------------------------------------
+{
+  const s = setup({ 'plan_review.rounds': 3 }, { plan_review: 'codex', 'plan_review.rounds': 5 });
+  const r = ask(s, ['codex']);
+  ok('config: keys resolve one by one, nearest wins (global plan_review, project rounds)', r.json.status === 'ask' && r.json.configured === 3 && JSON.stringify(r.json.reviewers) === '["codex"]');
+  s.done();
+}
+{
+  const s = setup({ plan_review: 'off' }, { plan_review: 'on' });
+  ok('config: the project value beats the global one', ask(s, ['codex']).json.reason === 'off');
+  s.done();
+}
+{
+  const s = setup(null, { plan_review: 'on' });
+  ok('config: a global-only config applies', ask(s, ['codex']).json.status === 'ask');
+  s.done();
+}
+{
+  const s = setup({ plan_review: 'on' }, null);
+  const home = tmp();
+  fs.mkdirSync(path.join(home, '.claude', 'trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(home, '.claude', 'trailhead', 'config.json'), JSON.stringify({ 'plan_review.rounds': 4 }));
+  const r = run(['ask', '--repo', s.root], { env: { HOME: home, PATH: '/nowhere' }, which: (n) => n === 'codex', kimiHelp: () => null });
+  ok('config: without CLAUDE_CONFIG_DIR the global file is ~/.claude/trailhead/config.json', r.json.configured === 4);
+  rm(home);
+  s.done();
+}
+
+// --- ask: invalid config -----------------------------------------------------
+{
+  const bad = setup('{not json', null);
+  const r = ask(bad, ['codex']);
+  ok('error: an unparseable project config is status error, exit 1', r.code === 1 && r.json.status === 'error' && /JSON/.test(r.json.reason));
+  bad.done();
+  const arr = setup('[1]', null);
+  ok('error: a non-object config is status error', ask(arr, ['codex']).json.status === 'error');
+  arr.done();
+  const gl = setup({}, '{nope');
+  ok('error: an unparseable global config is status error', ask(gl, ['codex']).code === 1);
+  gl.done();
+  const typ = setup({ plan_review: 7 }, null);
+  ok('error: a non-string plan_review is status error', ask(typ, ['codex']).json.status === 'error');
+  typ.done();
+  const empty = setup({ plan_review: ' , ' }, null);
+  ok('error: a plan_review list with no name is status error', ask(empty, ['codex']).json.status === 'error');
+  empty.done();
+}
+{
+  const s = setup({ plan_review: 'on' }, null);
+  const failing = { readFileSync: () => { const e = new Error('EACCES: denied'); e.code = 'EACCES'; throw e; } };
+  const r = run(['ask', '--repo', s.root], { ...deps(s.gdir, ['codex']), fs: failing });
+  ok('error: an unreadable config (not ENOENT) is status error', r.code === 1 && r.json.status === 'error' && /cannot read/.test(r.json.reason));
+  s.done();
+}
+
+// --- ask: real PATH scan -----------------------------------------------------
+{
+  const bin = tmp();
+  fs.writeFileSync(path.join(bin, 'gemini'), '#!/bin/sh\n', { mode: 0o755 });
+  fs.writeFileSync(path.join(bin, 'qwen'), '#!/bin/sh\n', { mode: 0o644 });
+  fs.mkdirSync(path.join(bin, 'codex'));
+  const s = setup({ plan_review: 'on' }, null);
+  const r = run(['ask', '--repo', s.root], { env: { CLAUDE_CONFIG_DIR: s.gdir, PATH: bin }, kimiHelp: () => null });
+  ok('path: the default scan finds executable files only', r.json.status === 'ask' && JSON.stringify(r.json.reviewers) === '["gemini"]');
+  s.done();
+  rm(bin);
+}
+
+// --- round -------------------------------------------------------------------
+const c = (key, text) => ({ key, text: text || `full text of ${key}` });
+function round(history, choice, configured, extra = {}) {
+  const dir = tmp();
+  const file = path.join(dir, 'history.json');
+  fs.writeFileSync(file, typeof history === 'string' ? history : JSON.stringify(history));
+  const r = run(['round', '--choice', choice, '--configured', String(configured), '--history', file], extra);
+  rm(dir);
+  return r;
+}
+const decision = (r) => r.json.decision;
+
+ok('round: a latest round with no concern is converged', decision(round([[c('a')], []], '2', 2)) === 'converged' && round([[]], 'until', 2).json.rounds === 1);
+ok('round: converged carries no surviving', !('surviving' in round([[]], '1', 2).json));
+ok('round: a fixed choice with rounds left continues', decision(round([[c('a')]], '2', 2)) === 'continue' && !('surviving' in round([[c('a')]], '2', 2).json));
+{
+  const r = round([[c('a', 'A is wrong because X'), c('b')], [c('a', 'A is still wrong because X')]], '2', 2);
+  ok('round: a fixed choice with rounds spent is exhausted', decision(r) === 'exhausted');
+  ok('round: exhausted surviving carries the full {key,text} of the latest round', JSON.stringify(r.json.surviving) === JSON.stringify([c('a', 'A is still wrong because X')]));
+}
+ok('round: config resolves to --configured', decision(round([[c('a')]], 'config', 1)) === 'exhausted' && decision(round([[c('a')]], 'config', 3)) === 'continue');
+ok('round: exhausted is not reported for a fixed choice before its rounds', decision(round([[c('a')], [c('b')]], '3', 2)) === 'continue');
+ok('round: a fixed choice never reports no-progress', decision(round([[c('a')], [c('a')]], '3', 2)) === 'continue');
+ok('round: until continues while concerns change', decision(round([[c('a')], [c('a'), c('b')], [c('b')]], 'until', 2)) === 'continue');
+ok('round: until with round 1 never reports no-progress', decision(round([[c('a')]], 'until', 2)) === 'continue');
+{
+  const r = round([[c('a'), c('b')], [c('a'), c('b'), c('c', 'new one')]], 'until', 2);
+  ok('round: until with none of the previous concerns resolved is no-progress', decision(r) === 'no-progress' && r.json.surviving.length === 3 && r.json.surviving[2].text === 'new one');
+}
+ok('round: until with one previous concern resolved keeps going', decision(round([[c('a'), c('b')], [c('a')]], 'until', 2)) === 'continue');
+ok('round: keys are compared normalised', decision(round([[c('  Plan  Gap ')], [c('plan gap')]], 'until', 2)) === 'no-progress');
+ok('round: until at 5 rounds with progress is ceiling', decision(round([[c('a')], [c('b')], [c('c')], [c('d')], [c('e')]], 'until', 2)) === 'ceiling');
+ok('round: ceiling carries surviving', round([[c('a')], [c('b')], [c('c')], [c('d')], [c('e')]], 'until', 2).json.surviving[0].key === 'e');
+ok('round: until at 4 rounds still continues', decision(round([[c('a')], [c('b')], [c('c')], [c('d')]], 'until', 2)) === 'continue');
+ok('round: precedence: converged beats ceiling', decision(round([[c('a')], [c('b')], [c('c')], [c('d')], []], 'until', 2)) === 'converged');
+ok('round: precedence: no-progress beats ceiling at round 5', decision(round([[c('a')], [c('b')], [c('c')], [c('d')], [c('d')]], 'until', 2)) === 'no-progress');
+ok('round: precedence: converged beats exhausted', decision(round([[c('a')], []], '1', 1)) === 'converged');
+ok('round: output is one status ok JSON line with the round count', round([[c('a')]], '2', 2).json.status === 'ok' && round([[c('a')]], '2', 2).json.rounds === 1 && round([[c('a')]], '2', 2).out.trim().split('\n').length === 1);
+
+// --- usage errors ------------------------------------------------------------
+{
+  const u = (argv) => run(argv);
+  ok('usage: no command exits 2', u([]).code === 2);
+  ok('usage: unknown command exits 2', u(['go', '--repo', '/x']).code === 2);
+  ok('usage: ask without --repo exits 2', u(['ask']).code === 2);
+  ok('usage: ask with a bad --host exits 2', u(['ask', '--repo', '/x', '--host', 'vim']).code === 2);
+  ok('usage: unknown flag exits 2', u(['ask', '--repo', '/x', '--bogus', '1']).code === 2);
+  ok('usage: a flag without a value exits 2', u(['ask', '--repo']).code === 2);
+  ok('usage: round without --choice exits 2', u(['round', '--configured', '2', '--history', '/x']).code === 2);
+  ok('usage: round with a bad --choice exits 2', u(['round', '--choice', '4', '--configured', '2', '--history', '/x']).code === 2);
+  ok('usage: round without --configured exits 2', u(['round', '--choice', '1', '--history', '/x']).code === 2);
+  ok('usage: round with a non-positive --configured exits 2', u(['round', '--choice', '1', '--configured', '0', '--history', '/x']).code === 2);
+  ok('usage: round without --history exits 2', u(['round', '--choice', '1', '--configured', '2']).code === 2);
+  ok('usage: errors go to stderr, stdout stays empty', u(['ask']).errOut.startsWith('usage:') && u(['ask']).out === '');
+  ok('usage: history that is not JSON exits 2', round('{nope', '2', 2).code === 2);
+  ok('usage: history that is not an array exits 2', round({ a: 1 }, '2', 2).code === 2);
+  ok('usage: an empty history exits 2', round([], '2', 2).code === 2);
+  ok('usage: a round that is not an array exits 2', round([{}], '2', 2).code === 2);
+  ok('usage: a concern that is a bare string exits 2', round([['a']], '2', 2).code === 2);
+  ok('usage: a concern with an empty key exits 2', round([[{ key: ' ', text: 'x' }]], '2', 2).code === 2);
+  ok('usage: a concern with an empty text exits 2', round([[{ key: 'a', text: '' }]], '2', 2).code === 2);
+  ok('usage: a concern with a non-string text exits 2', round([[{ key: 'a', text: 3 }]], '2', 2).code === 2);
+  const missing = run(['round', '--choice', '1', '--configured', '2', '--history', '/nowhere/h.json']);
+  ok('usage: a missing history file is status error, exit 1', missing.code === 1 && missing.json.status === 'error');
+}
+
+// --- end-to-end --------------------------------------------------------------
+{
+  const s = setup({ plan_review: 'on' }, null);
+  const bin = tmp();
+  fs.writeFileSync(path.join(bin, 'gemini'), '#!/bin/sh\n', { mode: 0o755 });
+  const res = spawnSync(process.execPath, [scriptPath, 'ask', '--repo', s.root], { encoding: 'utf8', env: { ...process.env, CLAUDE_CONFIG_DIR: s.gdir, PATH: bin } });
+  const j = JSON.parse(res.stdout.trim());
+  ok('e2e: ask prints one JSON line and exits 0', res.status === 0 && j.status === 'ask' && JSON.stringify(j.reviewers) === '["gemini"]' && j.options.length === 4);
+  const dir = tmp();
+  const file = path.join(dir, 'h.json');
+  fs.writeFileSync(file, JSON.stringify([[c('a')]]));
+  const rr = spawnSync(process.execPath, [scriptPath, 'round', '--choice', '1', '--configured', '2', '--history', file], { encoding: 'utf8' });
+  const rj = JSON.parse(rr.stdout.trim());
+  ok('e2e: round prints the decision and exits 0', rr.status === 0 && rj.decision === 'exhausted' && rj.surviving[0].key === 'a');
+  ok('e2e: usage error exits 2', spawnSync(process.execPath, [scriptPath, '--bogus'], { encoding: 'utf8' }).status === 2);
+  const bad = setup('{nope', null);
+  ok('e2e: an invalid config exits 1', spawnSync(process.execPath, [scriptPath, 'ask', '--repo', bad.root], { encoding: 'utf8', env: { ...process.env, CLAUDE_CONFIG_DIR: bad.gdir } }).status === 1);
+  bad.done(); s.done(); rm(bin); rm(dir);
+}
+
+console.log(`plan-review-rounds.test.js: ${passed} checks passed`);

package/plugins/trailhead/hooks/lib/report-status.test.js

@@ -16,13 +16,15 @@ const fs = require('fs');
 const os = require('os');
 
 const scriptPath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-report-status.js');
-const { checkReport, TOKENS, CONTRACTS, FAMILY_OF } = require(scriptPath);
+const { checkReport, TOKENS, CONTRACTS, FAMILY_OF, VERIFY_CLASSES } = require(scriptPath);
 const techDir = path.resolve(__dirname, '..', '..', 'skills', '_shared', 'techniques');
 
 let passed = 0;
 const ok = (name, cond) => { assert.ok(cond, name); passed++; };
 
 const K = 'critical: 0 · warning: 1 · info: 2'; // the counts line
+const K1 = 'critical: 1 · warning: 0 · info: 0';
+const K2 = 'critical: 2 · warning: 1 · info: 0';
 const V = 'verify';
 const C = 'code-review';
 const KEYS = ['action', 'verdict', 'problem', 'report', 'fields', 'body'];
@@ -119,6 +121,60 @@ const rows = [
   ['two counts lines', C, `status: clean\n${K}\nbody\n${K}\n`, ['reask', null, 'counts']],
   ['two different counts lines', C, `status: clean\n${K}\ncritical: 1 · warning: 1 · info: 2\n`, ['reask', null, 'counts']],
   ['counts only inside a code fence', C, `status: clean\n\`\`\`\n${K}\n\`\`\`\n`, ['reask', null, 'counts']],
+
+  // --- verdict vs content: code-review fails closed on an unclosed Critical ---
+  ['clean with critical 2 and no ledger (ticket repro)', C, `status: clean\n${K2}\n\n- critical: SQL injection\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K2}\n\n- critical: SQL injection\n`]],
+  ['clean, critical 1, C1 fixed', C, `status: clean\n${K1}\nC1 fixed (abc123)\n`, ['accept', 'clean', null]],
+  ['clean, critical 1, C1 deferred', C, `status: clean\n${K1}\n- C1: deferred → #12\n`, ['accept', 'clean', null]],
+  ['clean, critical 1, C1 accepted', C, `status: clean\n${K1}\nC1 accepted: false positive\n`, ['accept', 'clean', null]],
+  ['clean, critical 2, only C1 closed', C, `status: clean\n${K2}\nC1 fixed (a)\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K2}\nC1 fixed (a)\n`]],
+  ['clean, critical 1, C1 open', C, `status: clean\n${K1}\nC1 open\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1 open\n`]],
+  ['clean, critical 1, C1 fixed and C2 open', C, `status: clean\n${K1}\nC1 fixed (a)\nC2 open\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1 fixed (a)\nC2 open\n`]],
+  ['clean, critical 1, only a reclassified pointer', C, `status: clean\n${K1}\nC1 reclassified as W3\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1 reclassified as W3\n`]],
+  ['clean, critical 1, ledger line only inside a fence', C, `status: clean\n${K1}\n\`\`\`\nC1 fixed (a)\n\`\`\`\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\n\`\`\`\nC1 fixed (a)\n\`\`\`\n`]],
+  ['clean, critical 2, a repeated C1 line counts once', C, `status: clean\n${K2}\nC1 fixed (a)\nc1 fixed (b)\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K2}\nC1 fixed (a)\nc1 fixed (b)\n`]],
+  ['finding prose with open after a closed ledger line stays clean', C, `status: clean\n${K1}\nC1: fixed (abc)\nC1 file.js:3 handler leaves the socket open\n`, ['accept', 'clean', null]],
+  ['open redirect prose with a fixed ledger stays clean', C, `status: clean\n${K1}\nC1 fixed (abc)\nC1 open redirect in login.js:9\n`, ['accept', 'clean', null]],
+  ['a lone fixed-size prose line does not close the Critical', C, `status: clean\n${K1}\nC1 fixed-size buffer overflow in x.js:3: open\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1 fixed-size buffer overflow in x.js:3: open\n`]],
+  ['bold id and en-dash separator ledger line', C, `status: clean\n${K1}\n- **C1** – fixed (abc)\n`, ['accept', 'clean', null]],
+  ['verify subclass is not a class line', V, 'status: met\n- a, subclass: unmet\n', ['accept', 'met', null]],
+  ['an unparsed open line for an uncounted Critical fails closed', C, `status: clean\n${K2}\nC1 fixed (a)\nC2 fixed (b)\nC3 open because x\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K2}\nC1 fixed (a)\nC2 fixed (b)\nC3 open because x\n`]],
+  ['em dash separator closes the Critical', C, `status: clean\n${K1}\nC1 ${String.fromCharCode(0x2014)} fixed (abc)\n`, ['accept', 'clean', null]],
+  ['still open fails closed', C, `status: clean\n${K1}\nC1: still open\nC2 fixed (a)\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1: still open\nC2 fixed (a)\n`]],
+  ['bracketed open fails closed', C, `status: clean\n${K1}\nC1 [open]\nC2 fixed (a)\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1 [open]\nC2 fixed (a)\n`]],
+  ['a reclassified Critical does not gate the rest', C, `status: clean\n${K1}\nC1 reclassified as W3\nC2 fixed (a)\n`, ['accept', 'clean', null]],
+  ['clean, critical 0, warnings open never gate', C, `status: clean\n${K}\nW1 open\n`, ['accept', 'clean', null]],
+  ['issues_found is never changed', C, `status: issues_found\n${K1}\nC1 fixed (a)\n`, ['accept', 'issues_found', null]],
+
+  // --- verdict vs content: verify raises the tag to the highest claim class ---
+  ['verify met with a met claim', V, 'status: met\n- claim 1, class: met\n', ['accept', 'met', null]],
+  ['verify met with an unmet claim', V, 'status: met\n- Claim 2: login wired, class: unmet\n',
+    ['normalise', 'gaps_found', null, 'status: gaps_found\n- Claim 2: login wired, class: unmet\n']],
+  ['verify met with a partial claim', V, 'status: met\n- claim 1, class: partial\n',
+    ['normalise', 'gaps_found', null, 'status: gaps_found\n- claim 1, class: partial\n']],
+  ['verify met with an inconclusive claim', V, 'status: met\n- claim 1, class: inconclusive\n  reason: unrunnable-check\n',
+    ['normalise', 'inconclusive', null, 'status: inconclusive\n- claim 1, class: inconclusive\n  reason: unrunnable-check\n']],
+  ['verify met with inconclusive and unmet', V, 'status: met\n- a, class: inconclusive\n- b, class: unmet\n',
+    ['normalise', 'gaps_found', null, 'status: gaps_found\n- a, class: inconclusive\n- b, class: unmet\n']],
+  ['verify inconclusive with an unmet claim', V, 'status: inconclusive\n- b, class: unmet\n',
+    ['normalise', 'gaps_found', null, 'status: gaps_found\n- b, class: unmet\n']],
+  ['verify gaps_found with only met claims stays', V, 'status: gaps_found\n- a, class: met\n', ['accept', 'gaps_found', null]],
+  ['verify inconclusive with only met claims stays', V, 'status: inconclusive\n- a, class: met\n', ['accept', 'inconclusive', null]],
+  ['verify class line inside a fence is ignored', V, 'status: met\n```\n- a, class: unmet\n```\n', ['accept', 'met', null]],
+  ['verify class line inside a blockquote is ignored', V, 'status: met\n> - a, class: unmet\n', ['accept', 'met', null]],
+  ['verify upper-case class counts', V, 'status: met\n- a, Class: UNMET\n',
+    ['normalise', 'gaps_found', null, 'status: gaps_found\n- a, Class: UNMET\n']],
 ];
 
 for (const [name, technique, input, expected] of rows) {
@@ -274,6 +330,17 @@ ok('vocabulary: code-review tokens equal the ones code-review.md defines',
     ok(`contracts: technique ${technique} maps to the family of trailhead-${technique} in the sync script`, FAMILIES[`trailhead-${technique}`] === family);
     ok(`contracts: TOKENS.${technique} are the ${family} tokens`, JSON.stringify(TOKENS[technique]) === JSON.stringify(CONTRACTS[family].tokens));
   }
+  // the reviewing block names the verify class vocabulary and the closing dispositions
+  const bullet = (block, prefix) => block.split('\n').find((l) => l.startsWith(`- ${prefix}:`)) || '';
+  const classTokens = (text) => [...text.matchAll(/class: <([a-z|]+)>/g)].flatMap((m) => m[1].split('|'));
+  ok('contracts: reviewing verify bullet names the checker class vocabulary',
+    JSON.stringify(classTokens(bullet(blocks.reviewing, 'trailhead-verify'))) === JSON.stringify(VERIFY_CLASSES));
+  const crBullet = bullet(blocks.reviewing, 'trailhead-code-review');
+  ok('contracts: reviewing code-review bullet names the closing dispositions',
+    ['fixed', 'deferred', 'accepted'].every((d) => new RegExp(`\\x60${d}\\x60`).test(crBullet)));
+  const verifyDoc = fs.readFileSync(path.join(techDir, 'verify.md'), 'utf8');
+  ok('contracts: verify.md names the same class vocabulary',
+    classTokens(verifyDoc.replace(/class: ([a-z]+(?: \| [a-z]+)+)/g, (m, g) => `class: <${g.replace(/ \| /g, '|')}>`)).join() === VERIFY_CLASSES.join());
   ok('contracts: every non-review agent has a technique here',
     Object.entries(FAMILIES).filter(([, f]) => f !== 'reviewing').every(([a]) => FAMILY_OF[a.replace(/^trailhead-/, '')] !== undefined));
 }

package/plugins/trailhead/hooks/lib/shell-scan.js

@@ -633,6 +633,23 @@ const SEARCH_VERB_CONFIG = {
   awk: { patternFirst: true, valueFlags: new Set(['-f', '-v']), patternFlags: new Set() },
 };
 
+// #316: the -f / --file operand of a flag token, or null when the token is not one.
+// Forms: `-f V`, `-fV`, a short cluster whose FIRST value-taking letter is `f`
+// (`-if.env`; after another value letter the rest is that flag's value, so
+// `-ef.env` is a pattern), `--file V`, `--file=V`. `consumed` = extra tokens used.
+function fileFlagOperand(t, next, config) {
+  if (t === '--file') return { value: next, consumed: 1 };
+  if (t.startsWith('--file=')) return { value: t.slice('--file='.length), consumed: 0 };
+  if (t.startsWith('--')) return null;
+  for (let i = 1; i < t.length; i++) {
+    if (!config.valueFlags.has(`-${t[i]}`)) continue;
+    if (t[i] !== 'f') return null;
+    const rest = t.slice(i + 1);
+    return rest ? { value: rest, consumed: 0 } : { value: next, consumed: 1 };
+  }
+  return null;
+}
+
 // Walk a verb's argument tokens (verb itself already stripped), skipping
 // flags (and their separate-token values), an explicit `--` end-of-options
 // marker (which must not itself swallow the next real positional), and the
@@ -647,6 +664,14 @@ function scanArgsSkippingPattern(args, config, isMatch) {
     const t = args[j];
     if (!afterDashDash && t === '--') { afterDashDash = true; continue; }
     if (!afterDashDash && t.startsWith('-') && t !== '-') {
+      // #316: the value of -f / --file is a FILE the verb reads, so it is tested.
+      const file = fileFlagOperand(t, args[j + 1], config);
+      if (file) {
+        if (file.value !== undefined && file.value !== '' && isMatch(file.value)) return file.value;
+        patternConsumed = true; // the pattern/script comes from that file, so positionals are FILEs
+        j += file.consumed;
+        continue;
+      }
       if (config.valueFlags.has(t)) {
         j++; // consume its separate-token value
         if (config.patternFlags && config.patternFlags.has(t)) patternConsumed = true;