@marcomigozzi/trailhead 0.14.0 → 0.16.0

package/plugins/trailhead/templates/trailhead-plan-review-rounds.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead plan review rounds (self-contained, ships in templates/ so it reaches every
+// install channel: bin/trailhead.js copies templates/ wholesale for Claude/npm and Codex).
+// Backs the autonomous run's "External review rounds" start-up ask and the per-round
+// convergence decision of Cross-AI plan review. #284.
+//
+// CLI:
+//   node trailhead-plan-review-rounds.js ask   --repo <project-root> [--host claude|codex]
+//   node trailhead-plan-review-rounds.js round --choice <config|1|2|3|until> --configured <n> --history <file>
+// Prints one JSON line on stdout. Exit 0 ok / 1 error / 2 usage (message on stderr).
+//
+// Config: `plan_review` (off | on | comma list of CLIs, default off) and `plan_review.rounds`
+// (positive integer, default 2), flat keys. The project file (<project-root>/.trailhead/config.json)
+// and the global one (${CLAUDE_CONFIG_DIR:-~/.claude}/trailhead/config.json) are read key by key,
+// nearest wins. A non-positive or non-integer rounds value falls back to 2 with a warning.
+//
+// ask: resolves the candidate CLIs (`on` = the known roster, a list = only those), keeps the ones
+// whose binary is on PATH (kimi only when `kimi --help` mentions --output-format) and drops the
+// host's own CLI (claude by default, codex with --host codex). A name in an explicit list that is
+// not in the roster (a custom reviewer) counts only when a binary of that name is on PATH; else it
+// is listed under `unknown` with a warning and does not count.
+//   {"status":"skip","reason":"off"|"no-reviewer","configured":n,"unknown":[],"warnings":[]}
+//   {"status":"ask","configured":n,"reviewers":[],"unknown":[],"warnings":[],"options":[],"fallback":[]}
+//   {"status":"error","reason":<text>}                (unreadable or invalid config; exit 1)
+// `options` is the AskUserQuestion menu, at most four entries (the tool's cap); each entry is
+// {"value":"config"|"1"|"2"|"3"|"until","label":<text>,"recommended"?:true}. With n in 1..3 it is
+// config (Recommended), the other two counts, until; otherwise config, 1, 2, until (3 stays
+// reachable through the typed Other answer). `fallback` is the numbered list for a host without a
+// structured question tool: config, 1, 2, 3, until (same entry shape, all five).
+//
+// round: --history is a JSON array, one entry per review round done so far, each an array of the
+// blocking concerns still open after that round; a concern is {"key","text"}: `key` a short stable
+// id reused across rounds (compared trimmed, lower-cased, whitespace collapsed), `text` the full
+// human-readable concern. A malformed history is a usage error (exit 2).
+//   {"status":"ok","decision":<d>,"rounds":<rounds done>,"surviving"?:[{key,text}]}
+//   decision, first match wins: converged (latest round has no blocking concern) | no-progress
+//   (choice until, round 2 or later: the latest round resolved none of the previous round's
+//   concerns) | ceiling (choice until: 5 rounds done) | exhausted (fixed choice: its rounds are
+//   spent) | continue. Every stop but converged carries `surviving`, the latest round's concerns.
+//   `config` resolves to --configured.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const CONFIG_REL = path.join('.trailhead', 'config.json');
+const ROSTER = ['claude', 'gemini', 'codex', 'qwen', 'kimi', 'agy', 'opencode', 'cursor-agent', 'coderabbit'];
+const DEFAULT_ROUNDS = 2;
+const CEILING = 5;
+const HOSTS = ['claude', 'codex'];
+const CHOICES = ['config', '1', '2', '3', 'until'];
+const VALUED = { ask: ['repo', 'host'], round: ['choice', 'configured', 'history'] };
+
+class Usage extends Error {}
+
+function parseArgs(argv) {
+  const command = argv[0];
+  if (!Object.keys(VALUED).includes(command)) return { error: `usage: first argument must be one of ${Object.keys(VALUED).join(', ')}` };
+  const out = { command };
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    const name = a.startsWith('--') ? a.slice(2) : null;
+    if (!name || !VALUED[command].includes(name)) return { error: `usage: unknown argument ${a}` };
+    const v = argv[++i];
+    if (v === undefined || v.startsWith('--')) return { error: `usage: ${a} needs a value` };
+    out[name] = v;
+  }
+  if (command === 'ask') {
+    if (!out.repo) return { error: 'usage: missing --repo <project-root>' };
+    if (out.host !== undefined && !HOSTS.includes(out.host)) return { error: `usage: --host must be one of ${HOSTS.join(', ')}` };
+  } else {
+    if (!out.choice || !CHOICES.includes(out.choice)) return { error: `usage: --choice must be one of ${CHOICES.join(', ')}` };
+    if (!out.configured || !/^[1-9]\d*$/.test(out.configured)) return { error: 'usage: --configured needs a positive integer' };
+    if (!out.history) return { error: 'usage: missing --history <file>' };
+  }
+  return out;
+}
+
+const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+// Reads one config file. { cfg } (null when absent) or { error }.
+function readFile(file, fs_) {
+  let text;
+  try {
+    text = fs_.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { cfg: null };
+    return { error: `cannot read ${file}: ${err && err.message ? err.message : err}` };
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(text);
+  } catch (err) {
+    return { error: `${file} is not valid JSON` };
+  }
+  if (!isObject(cfg)) return { error: `${file} is not a JSON object` };
+  return { cfg };
+}
+
+function globalConfigPath(env) {
+  const base = env.CLAUDE_CONFIG_DIR || path.join(env.HOME || os.homedir(), '.claude');
+  return path.join(base, 'trailhead', 'config.json');
+}
+
+// Effective { planReview, rounds } (undefined when unset) or { error }. Nearest file wins per key.
+function readConfig(root, env, fs_) {
+  const files = [path.join(root, CONFIG_REL), globalConfigPath(env)];
+  const parsed = [];
+  for (const file of files) {
+    const r = readFile(file, fs_);
+    if (r.error) return { error: r.error };
+    if (r.cfg) parsed.push({ file, cfg: r.cfg });
+  }
+  const out = {};
+  for (const [key, prop] of [['plan_review', 'planReview'], ['plan_review.rounds', 'rounds']]) {
+    const hit = parsed.find(({ cfg }) => has(cfg, key));
+    if (hit) out[prop] = { value: hit.cfg[key], file: hit.file };
+  }
+  return out;
+}
+
+function resolveRounds(entry, warnings) {
+  if (!entry) return DEFAULT_ROUNDS;
+  const v = entry.value;
+  if (Number.isInteger(v) && v > 0) return v;
+  warnings.push(`plan_review.rounds in ${entry.file} must be a positive integer; using ${DEFAULT_ROUNDS}`);
+  return DEFAULT_ROUNDS;
+}
+
+// Pure PATH scan: an executable regular file named `name` in some PATH directory.
+function pathLookup(env, fs_) {
+  const dirs = String(env.PATH || '').split(path.delimiter).filter(Boolean);
+  return (name) => dirs.some((dir) => {
+    const file = path.join(dir, name);
+    try {
+      return fs_.statSync(file).isFile() && (fs_.accessSync(file, fs_.constants.X_OK), true);
+    } catch (err) {
+      return false;
+    }
+  });
+}
+
+// `kimi --help` output, or null when it cannot run.
+function runKimiHelp() {
+  const r = spawnSync('kimi', ['--help'], { encoding: 'utf8', timeout: 10000, stdio: ['ignore', 'pipe', 'pipe'] });
+  if (r.error || r.status !== 0) return null;
+  return `${r.stdout || ''}${r.stderr || ''}`;
+}
+
+const entry = (value, label, recommended) => ({ value, label, ...(recommended ? { recommended: true } : {}) });
+const countLabel = (n) => `${n} round${n === 1 ? '' : 's'}`;
+
+function buildMenus(n) {
+  const config = entry('config', `As in config (${n})`, true);
+  const until = entry('until', 'Until convergence (stop on a round with no progress, ceiling 5)');
+  const count = (k) => entry(String(k), countLabel(k));
+  const options = n >= 1 && n <= 3
+    ? [config, ...[1, 2, 3].filter((k) => k !== n).map(count), until]
+    : [config, count(1), count(2), until];
+  const fallback = [config, count(1), count(2), count(3), until];
+  return { options, fallback };
+}
+
+function runAsk(parsed, cwd, env, fs_, deps) {
+  const cfg = readConfig(path.resolve(cwd, parsed.repo), env, fs_);
+  if (cfg.error) return { code: 1, result: { status: 'error', reason: cfg.error } };
+  const warnings = [];
+  const configured = resolveRounds(cfg.rounds, warnings);
+  const base = { configured, unknown: [], warnings };
+
+  const raw = cfg.planReview ? cfg.planReview.value : 'off';
+  if (typeof raw !== 'string') return { code: 1, result: { status: 'error', reason: `plan_review in ${cfg.planReview.file} must be a string (off, on or a comma list)` } };
+  const mode = raw.trim().toLowerCase();
+  if (mode === 'off') return { code: 0, result: { status: 'skip', reason: 'off', ...base } };
+
+  const explicit = mode !== 'on';
+  const names = explicit ? [...new Set(raw.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean))] : ROSTER;
+  if (names.length === 0) return { code: 1, result: { status: 'error', reason: `plan_review in ${cfg.planReview.file} names no CLI` } };
+
+  const which = deps.which || pathLookup(env, fs_);
+  const kimiHelp = deps.kimiHelp || runKimiHelp;
+  const host = parsed.host || 'claude';
+  const reviewers = [];
+  const unknown = [];
+  for (const name of names) {
+    if (name === host) continue;
+    const installed = which(name);
+    if (!ROSTER.includes(name)) {
+      if (installed) reviewers.push(name);
+      else {
+        unknown.push(name);
+        warnings.push(`plan_review names "${name}", which is not a known CLI and has no binary on PATH; it does not count (typo?)`);
+      }
+      continue;
+    }
+    if (!installed) continue;
+    if (name === 'kimi') {
+      const help = kimiHelp();
+      if (typeof help !== 'string' || !help.includes('--output-format')) continue;
+    }
+    reviewers.push(name);
+  }
+  if (reviewers.length === 0) return { code: 0, result: { status: 'skip', reason: 'no-reviewer', ...base, unknown } };
+  return { code: 0, result: { status: 'ask', configured, reviewers, unknown, warnings, ...buildMenus(configured) } };
+}
+
+const norm = (key) => key.trim().toLowerCase().replace(/\s+/g, ' ');
+const filled = (v) => typeof v === 'string' && v.trim() !== '';
+
+// Validates the history; throws Usage when malformed.
+function validateHistory(h) {
+  if (!Array.isArray(h) || h.length === 0) throw new Usage('usage: history must be a non-empty JSON array, one entry per round');
+  h.forEach((round, i) => {
+    if (!Array.isArray(round)) throw new Usage(`usage: history[${i}] must be an array of concerns`);
+    round.forEach((c, j) => {
+      if (!isObject(c) || !filled(c.key) || !filled(c.text)) throw new Usage(`usage: history[${i}][${j}] must be {"key","text"} with non-empty strings`);
+    });
+  });
+}
+
+function decide(history, choice, configured) {
+  const rounds = history.length;
+  const latest = history[rounds - 1];
+  if (latest.length === 0) return { status: 'ok', decision: 'converged', rounds };
+  const stop = (decision) => ({ status: 'ok', decision, rounds, surviving: latest.map((c) => ({ key: c.key, text: c.text })) });
+  if (choice === 'until') {
+    const prev = rounds >= 2 ? history[rounds - 2] : [];
+    const latestKeys = new Set(latest.map((c) => norm(c.key)));
+    if (prev.length > 0 && prev.every((c) => latestKeys.has(norm(c.key)))) return stop('no-progress');
+    if (rounds >= CEILING) return stop('ceiling');
+    return { status: 'ok', decision: 'continue', rounds };
+  }
+  const limit = choice === 'config' ? configured : Number(choice);
+  if (rounds >= limit) return stop('exhausted');
+  return { status: 'ok', decision: 'continue', rounds };
+}
+
+function runRound(parsed, cwd, fs_) {
+  const file = path.resolve(cwd, parsed.history);
+  let text;
+  try {
+    text = fs_.readFileSync(file, 'utf8');
+  } catch (err) {
+    return { code: 1, result: { status: 'error', reason: `cannot read ${file}: ${err && err.message ? err.message : err}` } };
+  }
+  let history;
+  try {
+    history = JSON.parse(text);
+  } catch (err) {
+    throw new Usage(`usage: ${file} is not valid JSON`);
+  }
+  validateHistory(history);
+  return { code: 0, result: decide(history, parsed.choice, Number(parsed.configured)) };
+}
+
+function main(argv, { cwd, stdout, stderr, env, fs: fsMod, which, kimiHelp } = {}) {
+  const cwd_ = cwd || process.cwd();
+  const out = stdout || process.stdout;
+  const err = stderr || process.stderr;
+  const env_ = env || process.env;
+  const fs_ = fsMod || fs;
+
+  const parsed = parseArgs(argv || []);
+  if (parsed.error) {
+    err.write(parsed.error + '\n');
+    return 2;
+  }
+  let run;
+  try {
+    run = parsed.command === 'ask' ? runAsk(parsed, cwd_, env_, fs_, { which, kimiHelp }) : runRound(parsed, cwd_, fs_);
+  } catch (e) {
+    if (e instanceof Usage) {
+      err.write(e.message + '\n');
+      return 2;
+    }
+    run = { code: 1, result: { status: 'error', reason: 'error: ' + (e && e.message ? e.message : String(e)) } };
+  }
+  out.write(JSON.stringify(run.result) + '\n');
+  return run.code;
+}
+
+module.exports = { parseArgs, readConfig, decide, main };
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2), { cwd: process.cwd(), stdout: process.stdout, stderr: process.stderr, env: process.env }));
+}

package/plugins/trailhead/templates/trailhead-report-status.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead report status check (self-contained, ships in templates/ so it reaches
+// every install channel). Checks the leading `status:` line of an engine-agent
+// report (Code review, Goal-backward verification #250; executor, fix, plan, debug,
+// research, codebase-map #249) before the engine branches on it, and returns the
+// report's fields.
+//
+// CLI:
+//   node trailhead-report-status.js --technique <technique> [--file <path>]
+// <technique> is verify | code-review | executor | fix | plan | debug | research |
+// codebase-map. Reads the report from --file, or from stdin when there is none.
+// Prints exactly one JSON line {"action","verdict","problem","report","fields","body"}:
+//   action   accept | normalise | reask
+//   verdict  the canonical token, or null on reask
+//   problem  null | missing | unknown-token | conflicting | counts | fields (null iff not reask)
+//   report   the original text on accept and reask; the normalised text on normalise
+//   fields   label -> trimmed value for the report's fields (executor, fix, plan, debug,
+//            research, codebase-map); {} for verify and code-review; null on reask
+//   body     plan with `ready` only: the normalised report without its status line, the
+//            PLAN to post verbatim; null otherwise
+// Exit 0 for all three actions; exit 2 on a usage error (missing or unknown
+// technique, unknown flag, missing or unreadable file) with {"error": "..."} on
+// stderr and nothing on stdout.
+//
+// The rules, in short: a candidate status line is outside code fences and
+// blockquotes and not indented as code; after stripping a heading, list bullet and
+// bold/underscore/backtick decoration it reads `status: <token>` where the token,
+// lower-cased with spaces and hyphens as underscores, is exactly one of the
+// technique's closed set. One valid token in the exact layout (status on line 1;
+// for code-review also the counts line on line 2) is accepted; the same token in
+// any other layout is normalised; anything else is a reask, never a guess.
+// Fields: a field starts at a top-level line (same rules as a status line) reading
+// `<label>:` after the same stripping; its value is the rest of that line plus every
+// following line up to the next field label or the end. Labels are a closed list per
+// family, matched case-insensitively; an empty value or `none` means none. A required
+// field missing, a label given twice or a broken invariant is the `fields` problem.
+// Problem precedence on mixed defects: missing > conflicting > unknown-token > counts > fields.
+
+const fs = require('fs');
+
+const frozen = (a) => Object.freeze([...a]);
+
+// Hard-coded here; report-status.test.js asserts these equal the tokens parsed
+// from skills/_shared/techniques/{verify,code-review}.md, which stay the source.
+const REVIEW_TOKENS = Object.freeze({
+  verify: frozen(['met', 'gaps_found', 'inconclusive']),
+  'code-review': frozen(['clean', 'issues_found']),
+});
+
+// The return contract of each field family. Hard-coded here (the checker ships
+// self-contained); report-status.test.js asserts these equal what scripts/agent-blocks.md
+// states. An invariant says: for these statuses the field (or `body`, the report without
+// its status line) is `none` / `non-empty`.
+const CONTRACTS = Object.freeze({
+  implementing: Object.freeze({
+    tokens: frozen(['done', 'partial', 'blocked']),
+    required: frozen(['commits', 'tests', 'deviations', 'blockers']),
+    optional: frozen(['fidelity', 'surfaced scope']),
+    invariants: Object.freeze([
+      Object.freeze({ when: frozen(['done']), field: 'blockers', rule: 'none' }),
+      Object.freeze({ when: frozen(['partial', 'blocked']), field: 'blockers', rule: 'non-empty' }),
+    ]),
+  }),
+  investigating: Object.freeze({
+    tokens: frozen(['found', 'inconclusive', 'needs_input']),
+    required: frozen(['answer', 'evidence', 'open questions']),
+    optional: frozen([]),
+    invariants: Object.freeze([
+      Object.freeze({ when: frozen(['needs_input']), field: 'open questions', rule: 'non-empty' }),
+    ]),
+  }),
+  plan: Object.freeze({
+    tokens: frozen(['ready', 'needs_input']),
+    required: frozen([]),
+    optional: frozen(['questions']),
+    invariants: Object.freeze([
+      Object.freeze({ when: frozen(['ready']), field: 'body', rule: 'non-empty' }),
+      Object.freeze({ when: frozen(['needs_input']), field: 'questions', rule: 'non-empty' }),
+    ]),
+  }),
+});
+
+// Technique -> field family.
+const FAMILY_OF = Object.freeze({
+  executor: 'implementing',
+  fix: 'implementing',
+  debug: 'investigating',
+  research: 'investigating',
+  'codebase-map': 'investigating',
+  plan: 'plan',
+});
+
+// Technique -> its closed set of status tokens.
+const TOKENS = Object.freeze({
+  ...REVIEW_TOKENS,
+  ...Object.fromEntries(Object.entries(FAMILY_OF).map(([t, f]) => [t, CONTRACTS[f].tokens])),
+});
+
+const COUNTS_RE = /^critical\s*:\s*(\d+)\s*·\s*warning\s*:\s*(\d+)\s*·\s*info\s*:\s*(\d+)$/i;
+const BOM = '';
+
+// Heading marks, a list bullet and bold/underscore/backtick decoration removed.
+function strip(line) {
+  return line
+    .trim()
+    .replace(/^#{1,6}\s+/, '')
+    .replace(/^[-*+]\s+/, '')
+    .replace(/\*\*|__|`/g, '')
+    .trim();
+}
+
+// Index set of the lines that may carry a status or counts line: outside fenced
+// code blocks, outside blockquotes, not indented as code (4+ spaces or a tab).
+function candidateLines(lines) {
+  const out = [];
+  let fence = null; // { char, len } while inside a fenced block
+  lines.forEach((line, i) => {
+    const m = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+    if (fence) {
+      if (m && m[1][0] === fence.char && m[1].length >= fence.len && m[2].trim() === '') fence = null;
+      return;
+    }
+    if (m) {
+      fence = { char: m[1][0], len: m[1].length };
+      return;
+    }
+    if (/^(?: {4,}|\t)/.test(line)) return;
+    if (/^ {0,3}>/.test(line)) return;
+    out.push(i);
+  });
+  return out;
+}
+
+function statusOf(line) {
+  const s = strip(line);
+  const m = /^status\s*:(.*)$/i.exec(s);
+  if (!m) return null;
+  return m[1].trim().toLowerCase().replace(/[\s-]+/g, '_');
+}
+
+function countsOf(line) {
+  const m = COUNTS_RE.exec(strip(line));
+  return m ? `critical: ${m[1]} · warning: ${m[2]} · info: ${m[3]}` : null;
+}
+
+const reask = (text, problem) => ({ action: 'reask', verdict: null, problem, report: text, fields: null, body: null });
+
+const isNone = (v) => v === undefined || /^(none\.?)?$/i.test(v.trim());
+
+// The fields of a report: label -> trimmed value, over the top-level lines that are not
+// status lines. Returns { fields, duplicate }.
+function parseFields(lines, cands, skip, contract) {
+  const allowed = new Set([...contract.required, ...contract.optional]);
+  const hits = [];
+  for (const i of cands) {
+    if (skip.has(i)) continue;
+    const m = /^([A-Za-z][A-Za-z ]*?)\s*:(.*)$/.exec(strip(lines[i]));
+    const label = m && m[1].replace(/\s+/g, ' ').toLowerCase();
+    if (label && allowed.has(label)) hits.push({ i, label, first: m[2].trim() });
+  }
+  const fields = {};
+  let duplicate = false;
+  hits.forEach((h, k) => {
+    const end = k + 1 < hits.length ? hits[k + 1].i : lines.length;
+    const tail = [];
+    for (let j = h.i + 1; j < end; j++) if (!skip.has(j)) tail.push(lines[j]);
+    if (Object.prototype.hasOwnProperty.call(fields, h.label)) duplicate = true;
+    else fields[h.label] = [h.first, ...tail].join('\n').trim();
+  });
+  return { fields, duplicate };
+}
+
+// The fields problem for a verdict, or null when the contract holds.
+function fieldsProblem(contract, verdict, fields, duplicate, body) {
+  if (duplicate) return true;
+  if (contract.required.some((f) => !Object.prototype.hasOwnProperty.call(fields, f))) return true;
+  return contract.invariants.some((inv) => {
+    if (!inv.when.includes(verdict)) return false;
+    const value = inv.field === 'body' ? body : fields[inv.field];
+    return inv.rule === 'none' ? !isNone(value) : isNone(value);
+  });
+}
+
+function checkReport(text, technique) {
+  const tokens = Object.prototype.hasOwnProperty.call(TOKENS, technique) ? TOKENS[technique] : null;
+  if (!tokens) throw new Error(`unknown technique: ${technique}`);
+  const original = typeof text === 'string' ? text : '';
+  const hasBom = original.startsWith(BOM);
+  const lines = (hasBom ? original.slice(1) : original).replace(/\r\n?/g, '\n').split('\n');
+  const cleanLayout = !hasBom && !original.includes('\r');
+
+  const cands = candidateLines(lines);
+  const statusLines = cands.map((i) => ({ i, token: statusOf(lines[i]) })).filter((c) => c.token !== null);
+  if (statusLines.length === 0) return reask(original, 'missing');
+
+  const valid = new Set(statusLines.filter((c) => tokens.includes(c.token)).map((c) => c.token));
+  const anyInvalid = statusLines.some((c) => !tokens.includes(c.token));
+  if (valid.size > 1 || (valid.size === 1 && anyInvalid)) return reask(original, 'conflicting');
+  if (valid.size === 0) return reask(original, 'unknown-token');
+  const verdict = [...valid][0];
+
+  let counts = [];
+  if (technique === 'code-review') {
+    counts = cands.map((i) => ({ i, text: countsOf(lines[i]) })).filter((c) => c.text !== null);
+    if (counts.length !== 1) return reask(original, 'counts');
+  }
+
+  // Blank lines that led the original are not content: drop them with the status lines.
+  const lead = lines.findIndex((l) => l.trim() !== '');
+  const drop = new Set([...statusLines, ...counts].map((c) => c.i));
+  const rest = lines.filter((_, i) => !drop.has(i) && i >= lead);
+
+  let fields = {};
+  let body = null;
+  const family = Object.prototype.hasOwnProperty.call(FAMILY_OF, technique) ? FAMILY_OF[technique] : null;
+  if (family) {
+    const contract = CONTRACTS[family];
+    const statusIdx = new Set(statusLines.map((c) => c.i));
+    const parsed = parseFields(lines, cands, statusIdx, contract);
+    const text = rest.join('\n').replace(/^(?:[ \t]*\n)+/, '').replace(/\s+$/, '');
+    if (fieldsProblem(contract, verdict, parsed.fields, parsed.duplicate, text)) return reask(original, 'fields');
+    fields = parsed.fields;
+    if (family === 'plan' && verdict === 'ready') body = text;
+  }
+
+  const exact = cleanLayout && statusLines.length === 1 && statusLines[0].i === 0 && lines[0] === `status: ${verdict}`
+    && (counts.length === 0 || (counts[0].i === 1 && lines[1] === counts[0].text));
+  if (exact) return { action: 'accept', verdict, problem: null, report: original, fields, body };
+
+  const head = [`status: ${verdict}`, ...counts.map((c) => c.text)];
+  return { action: 'normalise', verdict, problem: null, report: [...head, ...rest].join('\n'), fields, body };
+}
+
+function parseArgs(argv) {
+  const opts = { technique: null, file: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--technique' || a === '--file') {
+      const v = argv[i + 1];
+      if (v === undefined || v === '' || v.startsWith('--')) throw new Error(`${a} needs a value`);
+      opts[a === '--technique' ? 'technique' : 'file'] = v;
+      i++;
+    } else {
+      throw new Error(`unknown argument: ${a}`);
+    }
+  }
+  if (!opts.technique) throw new Error(`--technique <${Object.keys(TOKENS).join('|')}> is required`);
+  if (!Object.prototype.hasOwnProperty.call(TOKENS, opts.technique)) throw new Error(`unknown technique: ${opts.technique}`);
+  return opts;
+}
+
+function main(argv, io = {}) {
+  const stdout = io.stdout || process.stdout;
+  const stderr = io.stderr || process.stderr;
+  const readFile = io.readFile || ((p) => fs.readFileSync(p, 'utf8'));
+  const readStdin = io.readStdin || (() => fs.readFileSync(0, 'utf8'));
+  let result;
+  try {
+    const opts = parseArgs(argv);
+    const text = opts.file !== null ? readFile(opts.file) : readStdin();
+    result = checkReport(text, opts.technique);
+  } catch (e) {
+    stderr.write(`${JSON.stringify({ error: e.message })}\n`);
+    return 2;
+  }
+  stdout.write(`${JSON.stringify(result)}\n`);
+  return 0;
+}
+
+// exitCode, not process.exit(): exiting at once truncates piped stdout at 64 KB.
+if (require.main === module) process.exitCode = main(process.argv.slice(2));
+
+module.exports = { checkReport, parseArgs, main, TOKENS, CONTRACTS, FAMILY_OF };

package/plugins/trailhead/templates/trailhead-uat-backfill.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead UAT backfill (self-contained, ships in templates/ so it reaches every
+// install channel). One-time, idempotent migration: tags every open ticket whose
+// body has a `UAT of:` line with the `trailhead:uat` label, so a pending UAT
+// follow-up opened before the label existed is still findable. #261.
+//
+// CLI:
+//   node trailhead-uat-backfill.js [--repo <owner/name>] [--marker <path>]
+// --marker makes the run once per clone: a present marker exits `skipped` with no
+// `gh` call; the helper writes it only on a clean run (label confirmed, list read
+// ok, no failed edit).
+//
+// Prints exactly one JSON line on stdout:
+//   {"status":"ok"|"skipped"|"error","tagged":[n,...],"failed":[n,...],"reason":"..."}
+// Exit 0 on ok or skipped, 1 on an error, 2 on a usage error (stderr).
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const LABEL = 'trailhead:uat';
+const COLOR = 'BFD4F2';
+const DESCRIPTION = 'Pending UAT: an acceptance test still to run';
+const LIMIT = 1000;
+// A line that starts with `UAT of:` (a mid-line mention is not a pointer).
+const UAT_LINE_RE = /^UAT of:/m;
+
+function defaultGh(args) {
+  const r = spawnSync('gh', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  return { status: r.status === null ? 1 : r.status, stdout: r.stdout || '', stderr: r.stderr || (r.error ? String(r.error.message) : '') };
+}
+
+const firstLine = (s) => String(s || '').split('\n').find((l) => l.trim()) || '';
+
+function parseArgs(argv) {
+  const o = { repo: null, marker: null };
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag !== '--repo' && flag !== '--marker') return { error: `usage: unknown argument: ${flag}` };
+    i++;
+    if (i >= argv.length) return { error: `usage: ${flag} requires a value` };
+    const v = argv[i];
+    if (flag === '--repo') {
+      if (!/^[^/\s]+\/[^/\s]+$/.test(v)) return { error: `usage: --repo must be owner/name, got: ${v}` };
+      o.repo = v;
+    } else {
+      o.marker = v;
+    }
+  }
+  return o;
+}
+
+const names = (labels) => (labels || []).map((l) => (typeof l === 'string' ? l : l.name));
+
+// Ensures the label exists: idempotent create, then a confirming read. A create
+// failure is only "already exists" when the label is actually there.
+function ensureLabel(gh, rArgs) {
+  gh(['label', 'create', LABEL, '--color', COLOR, '--description', DESCRIPTION, ...rArgs]);
+  const r = gh(['label', 'list', '--search', LABEL, '--json', 'name', ...rArgs]);
+  if (r.status !== 0) return `cannot confirm the ${LABEL} label: ${firstLine(r.stderr) || 'exit ' + r.status}`;
+  let list;
+  try { list = JSON.parse(r.stdout); } catch { return `cannot confirm the ${LABEL} label: unparseable label list`; }
+  return Array.isArray(list) && names(list).includes(LABEL) ? null : `the ${LABEL} label does not exist and could not be created`;
+}
+
+function main(argv, { gh, stdout, stderr } = {}) {
+  const out = stdout || process.stdout;
+  const err = stderr || process.stderr;
+  const o = parseArgs(argv || []);
+  if (o.error) { err.write(o.error + '\n'); return 2; }
+  const run = gh || defaultGh;
+  const emit = (obj) => out.write(JSON.stringify(obj) + '\n');
+  const fail = (reason) => { emit({ status: 'error', tagged: [], failed: [], reason }); return 1; };
+
+  if (o.marker && fs.existsSync(o.marker)) { emit({ status: 'skipped', tagged: [], failed: [] }); return 0; }
+
+  const rArgs = o.repo ? ['-R', o.repo] : [];
+  const problem = ensureLabel(run, rArgs);
+  if (problem) return fail(problem);
+
+  const list = run(['issue', 'list', '--state', 'open', '--search', `"UAT of:" in:body -label:${LABEL}`, '--limit', String(LIMIT), '--json', 'number,body,labels', ...rArgs]);
+  if (list.status !== 0) return fail(`gh issue list failed: ${firstLine(list.stderr) || 'exit ' + list.status}`);
+  let issues;
+  try { issues = JSON.parse(list.stdout); } catch { return fail('gh issue list returned unparseable JSON'); }
+  if (!Array.isArray(issues)) return fail('gh issue list returned unexpected JSON');
+
+  const tagged = [];
+  const failed = [];
+  for (const i of issues) {
+    if (names(i.labels).includes(LABEL)) continue;
+    if (!UAT_LINE_RE.test(String(i.body || '').replace(/\r/g, ''))) continue;
+    const r = run(['issue', 'edit', String(i.number), '--add-label', LABEL, ...rArgs]);
+    (r.status === 0 ? tagged : failed).push(i.number);
+  }
+
+  let reason;
+  if (o.marker && failed.length === 0) {
+    try {
+      fs.mkdirSync(path.dirname(o.marker), { recursive: true });
+      fs.writeFileSync(o.marker, new Date().toISOString() + '\n');
+    } catch (e) {
+      reason = `marker not written: ${e && e.message ? e.message : String(e)}`;
+    }
+  }
+  emit(reason ? { status: 'ok', tagged, failed, reason } : { status: 'ok', tagged, failed });
+  return 0;
+}
+
+module.exports = { main, parseArgs, UAT_LINE_RE };
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2), {}));
+}