@marcomigozzi/trailhead 0.15.0 → 0.16.1

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

@@ -36,6 +36,12 @@
 // 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.
+// The verdict must also agree with the report's content, and only ever moves to the
+// stricter one (fail closed, action normalise): a code-review `clean` whose counts line has
+// critical N > 0 stands only if the ledger closes (`fixed`/`deferred`/`accepted`, first
+// disposition word after the `C<n>` id) at least N distinct Critical ids and none is `open`,
+// else it becomes `issues_found`; a verify tag below the highest `class: <c>` claim line
+// (unmet/partial > inconclusive > met) is raised to it. Warnings and Info never gate.
 
 const fs = require('fs');
 
@@ -48,6 +54,10 @@ const REVIEW_TOKENS = Object.freeze({
   'code-review': frozen(['clean', 'issues_found']),
 });
 
+// The class a verify claim line carries (`class: <c>`); the contract is pinned against
+// scripts/agent-blocks.md and verify.md by report-status.test.js.
+const VERIFY_CLASSES = frozen(['met', 'unmet', 'partial', 'inconclusive']);
+
 // 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
@@ -144,6 +154,58 @@ function countsOf(line) {
   return m ? `critical: ${m[1]} · warning: ${m[2]} · info: ${m[3]}` : null;
 }
 
+// A ledger line: `C<n>`, an optional separator (colon, hyphen, en dash, em dash, `)`), then
+// the disposition word right away (a bare `open` must end the line or be followed by
+// punctuation: `C1 open redirect` is prose).
+const LEDGER_RE = /^C(\d+)\s*[:\-\u2013\u2014)]?\s*(fixed|deferred|accepted|reclassified|open(?=\s*(?:$|[:.,;(\u2192])))(?![-\w])/i;
+const CRITICAL_ID_RE = /^C(\d+)\b/i;
+const CLOSED = frozen(['fixed', 'deferred', 'accepted']);
+// Verify verdicts by strictness; unmet and partial claims both mean gaps_found.
+const VERIFY_RANK = Object.freeze({ met: 0, inconclusive: 1, gaps_found: 2 });
+const CLASS_VERDICT = Object.freeze({ met: 'met', unmet: 'gaps_found', partial: 'gaps_found', inconclusive: 'inconclusive' });
+
+// Critical ids at the start of any candidate line, as { seen, ledger }: `seen` is every id
+// (parsed as a ledger line or not), `ledger` the parsed lines [{ id, disposition }].
+function criticalLines(lines, cands) {
+  const stripped = cands.map((i) => strip(lines[i]));
+  const seen = stripped.flatMap((s) => { const m = CRITICAL_ID_RE.exec(s); return m ? [`C${m[1]}`] : []; });
+  const ledger = stripped.flatMap((s) => {
+    const m = LEDGER_RE.exec(s);
+    return m ? [{ id: `C${m[1]}`, disposition: m[2].toLowerCase() }] : [];
+  });
+  return { seen: new Set(seen), ledger };
+}
+
+// Does a `clean` verdict with `critical` Criticals stand against its ledger? Every id seen
+// must be closed (or reclassified away), none parsed as open, and the closed count reach N.
+function cleanStands(critical, { seen, ledger }) {
+  if (critical === 0) return true;
+  if (ledger.some((e) => e.disposition === 'open')) return false;
+  const closed = new Set(ledger.filter((e) => CLOSED.includes(e.disposition)).map((e) => e.id));
+  const moved = new Set(ledger.filter((e) => e.disposition === 'reclassified').map((e) => e.id));
+  if ([...seen].some((id) => !closed.has(id) && !moved.has(id))) return false;
+  return closed.size >= critical;
+}
+
+// The verify verdict raised to the highest class among the claim lines; never lowered.
+function raisedVerify(verdict, lines, cands, statusIdx) {
+  const classes = cands.filter((i) => !statusIdx.has(i)).flatMap((i) => {
+    const m = new RegExp(`(?:^|[\\s,;(])class\\s*:\\s*(${VERIFY_CLASSES.join('|')})\\b(?![-\\w])`, 'i').exec(strip(lines[i]));
+    return m ? [CLASS_VERDICT[m[1].toLowerCase()]] : [];
+  });
+  return classes.reduce((v, c) => (VERIFY_RANK[c] > VERIFY_RANK[v] ? c : v), verdict);
+}
+
+// The verdict after the content check: the declared one, or the stricter one it contradicts.
+function checkedVerdict(technique, verdict, lines, cands, statusIdx, counts) {
+  if (technique === 'verify') return raisedVerify(verdict, lines, cands, statusIdx);
+  if (technique === 'code-review' && verdict === 'clean') {
+    const critical = Number(/^critical: (\d+)/.exec(counts[0].text)[1]);
+    return cleanStands(critical, criticalLines(lines, cands)) ? verdict : 'issues_found';
+  }
+  return verdict;
+}
+
 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());
@@ -198,7 +260,7 @@ function checkReport(text, technique) {
   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];
+  const declared = [...valid][0];
 
   let counts = [];
   if (technique === 'code-review') {
@@ -206,6 +268,8 @@ function checkReport(text, technique) {
     if (counts.length !== 1) return reask(original, 'counts');
   }
 
+  const verdict = checkedVerdict(technique, declared, lines, cands, new Set(statusLines.map((c) => c.i)), 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));
@@ -224,7 +288,7 @@ function checkReport(text, technique) {
     if (family === 'plan' && verdict === 'ready') body = text;
   }
 
-  const exact = cleanLayout && statusLines.length === 1 && statusLines[0].i === 0 && lines[0] === `status: ${verdict}`
+  const exact = cleanLayout && statusLines.length === 1 && statusLines[0].i === 0 && lines[0] === `status: ${verdict}` && verdict === declared
     && (counts.length === 0 || (counts[0].i === 1 && lines[1] === counts[0].text));
   if (exact) return { action: 'accept', verdict, problem: null, report: original, fields, body };
 
@@ -271,4 +335,4 @@ function main(argv, io = {}) {
 // 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 };
+module.exports = { checkReport, parseArgs, main, TOKENS, CONTRACTS, FAMILY_OF, VERIFY_CLASSES };

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

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead UAT follow-up finder (self-contained, ships in templates/ so it reaches
+// every install channel). Tells an autonomous run whether a ticket's UAT follow-up
+// already exists, so a resume reuses it instead of opening a second one. #281.
+//
+// CLI:
+//   node trailhead-uat-followup.js find --parent <n> --repo <owner/name>
+//
+// Reads every `trailhead:uat` issue (open and closed) with a direct GraphQL query
+// (`gh api graphql`, `repository.issues`), paginated here 100 at a time. It does not
+// use `gh issue list --label`: gh turns a label filter into a search query, and the
+// search index lags, so a follow-up opened seconds earlier would be missed. It keeps
+// the issues whose body has a line starting `UAT of:` that points at the parent: a
+// markdown link target https://github.com/<owner>/<name>/issues/<n> (same repo, exact
+// number) or a bare `#<n>`. A mid-line mention is not a pointer. Only an OPEN
+// follow-up is reusable: `reuse` is the lowest-numbered open one, null when none is
+// open; closed ones are reported but never count. A read that fails, is unparseable,
+// carries GraphQL errors, has an unexpected shape, or exceeds the page cap (100 pages of 100, so 10,000 issues) fails
+// closed (the caller must not open a follow-up blind).
+//
+// Prints exactly one JSON line on stdout:
+//   ok:    {"status":"ok","parent":n,"open":[{"number","title"}],"closed":[{"number","title"}],"reuse":<n>|null}
+//   error: {"status":"error","reason":"..."}
+// Exit 0 on ok, 1 on an error, 2 on a usage error (stderr).
+
+const { spawnSync } = require('child_process');
+
+const MAX_PAGES = 100; // 100 pages x 100 issues
+const QUERY = 'query($owner:String!,$name:String!,$after:String){repository(owner:$owner,name:$name){issues(first:100,after:$after,labels:["trailhead:uat"],states:[OPEN,CLOSED],orderBy:{field:CREATED_AT,direction:ASC}){nodes{number title state body} pageInfo{hasNextPage endCursor}}}}';
+const URL_RE = /https:\/\/github\.com\/([^/\s)]+)\/([^/\s)]+)\/issues\/(\d+)(?![\w])/gi;
+
+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()) || '';
+const byNumber = (a, b) => a.number - b.number;
+
+function parseArgs(argv) {
+  const cmd = argv[0];
+  if (cmd !== 'find') return { error: `usage: expected find, got: ${cmd === undefined ? '(nothing)' : cmd}` };
+  const o = { cmd, parent: null, repo: null };
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag !== '--parent' && flag !== '--repo') 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 {
+      if (!/^[1-9]\d*$/.test(v)) return { error: `usage: --parent must be a positive integer, got: ${v}` };
+      o.parent = Number(v);
+    }
+  }
+  if (!o.repo) return { error: 'usage: find requires --repo' };
+  if (!o.parent) return { error: 'usage: find requires --parent' };
+  return o;
+}
+
+// Pure: does a `UAT of:` line of the body point at issue `parent` of `repo`?
+function pointsAt(body, parent, repo) {
+  const want = repo.toLowerCase();
+  const lines = String(body || '').replace(/\r/g, '').split('\n');
+  for (const line of lines) {
+    const m = /^UAT of:(.*)$/.exec(line);
+    if (!m) continue;
+    const rest = m[1];
+    const urls = [...rest.matchAll(URL_RE)];
+    if (urls.length) {
+      if (urls.some((u) => `${u[1]}/${u[2]}`.toLowerCase() === want && Number(u[3]) === parent)) return true;
+      continue;
+    }
+    const bare = [...rest.matchAll(/(?:^|[^\w/])#(\d+)\b/g)];
+    if (bare.some((b) => Number(b[1]) === parent)) return true;
+  }
+  return false;
+}
+
+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', reason }); return 1; };
+
+  const [owner, name] = o.repo.split('/');
+  const rows = [];
+  let after = null;
+  for (let page = 1; ; page++) {
+    if (page > MAX_PAGES) return fail(`incomplete read: more than ${MAX_PAGES} pages of trailhead:uat issues`);
+    const args = ['api', 'graphql', '-f', `query=${QUERY}`, '-f', `owner=${owner}`, '-f', `name=${name}`];
+    if (after !== null) args.push('-f', `after=${after}`);
+    const r = run(args);
+    if (r.status !== 0) return fail(`gh api graphql failed: ${firstLine(r.stderr) || 'exit ' + r.status}`);
+    let body;
+    try { body = JSON.parse(r.stdout); } catch { return fail('gh api graphql returned unparseable JSON'); }
+    if (!body || typeof body !== 'object') return fail('gh api graphql returned unexpected JSON');
+    if (Array.isArray(body.errors) && body.errors.length) return fail(`graphql errors: ${firstLine(body.errors[0] && body.errors[0].message) || 'unknown'}`);
+    const repo = body.data && body.data.repository;
+    if (!repo) return fail('repository not found in the graphql response');
+    const issues = repo.issues;
+    if (!issues || !Array.isArray(issues.nodes)) return fail('graphql response has no issues.nodes');
+    const info = issues.pageInfo;
+    if (!info || typeof info.hasNextPage !== 'boolean') return fail('graphql response has no pageInfo');
+    rows.push(...issues.nodes.filter((n) => n && typeof n === 'object'));
+    if (!info.hasNextPage) break;
+    if (typeof info.endCursor !== 'string' || !info.endCursor) return fail('graphql pageInfo has hasNextPage without an endCursor');
+    after = info.endCursor;
+  }
+
+  const mine = rows.filter((i) => pointsAt(i.body, o.parent, o.repo)).map((i) => ({ number: i.number, title: i.title, state: String(i.state || '').toUpperCase() }));
+  const pick = (open) => mine.filter((i) => (i.state === 'OPEN') === open).sort(byNumber).map(({ number, title }) => ({ number, title }));
+  const open = pick(true);
+  emit({ status: 'ok', parent: o.parent, open, closed: pick(false), reuse: open.length ? open[0].number : null });
+  return 0;
+}
+
+module.exports = { main, parseArgs, pointsAt };
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2), {}));
+}

package/plugins/trailhead/templates/trailhead-unblock.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead unblock helper (self-contained, ships in templates/ so it reaches every
+// install channel). After an autonomous run closes a ticket, removes `trailhead:blocked`
+// from every open dependent whose blockers are now all closed, so the next frontier
+// query returns it. #286.
+//
+// CLI:
+//   node trailhead-unblock.js --issue <n> --repo <owner/name>
+//
+// Reads the closed ticket's dependents (`dependencies/blocking`), and for each OPEN
+// dependent that carries `trailhead:blocked` reads its `blocked_by`; when every blocker
+// is closed it removes the label. Reads are paginated: `gh api --paginate --jq` prints
+// one JSON object per line across every page, so a long list is read whole. A dependent
+// without the label, or a closed one, is skipped, so a retry is idempotent. The first
+// failed or unparseable gh step stops the helper: nothing further is edited.
+//
+// Prints exactly one JSON line on stdout:
+//   ok:    {"status":"ok","unblocked":[n...],"stillBlocked":[{"issue":n,"openBlockers":[...]}]}
+//   error: {"status":"error","reason":"..."}
+// Exit 0 on ok, 1 on an error, 2 on a usage error (stderr).
+
+const { spawnSync } = require('child_process');
+
+const LABEL = 'trailhead:blocked';
+
+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 = { issue: null, repo: null };
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag !== '--issue' && flag !== '--repo') 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 {
+      if (!/^[1-9]\d*$/.test(v)) return { error: `usage: --issue must be a positive integer, got: ${v}` };
+      o.issue = Number(v);
+    }
+  }
+  if (!o.repo) return { error: 'usage: requires --repo' };
+  if (!o.issue) return { error: 'usage: requires --issue' };
+  return o;
+}
+
+// One JSON object per line -> { items } or { error }.
+function parseLines(text, what) {
+  const items = [];
+  for (const line of String(text).split('\n')) {
+    if (!line.trim()) continue;
+    let j;
+    try { j = JSON.parse(line); } catch { return { error: `${what} returned unparseable JSON` }; }
+    if (!j || typeof j !== 'object') return { error: `${what} returned unexpected JSON` };
+    items.push(j);
+  }
+  return { items };
+}
+
+// Paginated read of a dependency list for issue n. { items } or { error }.
+function readList(run, o, n, kind, jq) {
+  const what = `gh api dependencies/${kind} of #${n}`;
+  const r = run(['api', '--paginate', `repos/${o.repo}/issues/${n}/dependencies/${kind}`, '--jq', jq]);
+  if (r.status !== 0) return { error: `${what} failed: ${firstLine(r.stderr) || 'exit ' + r.status}` };
+  return parseLines(r.stdout, what);
+}
+
+const isOpen = (x) => String(x.state || '').toLowerCase() === 'open';
+
+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', reason }); return 1; };
+
+  const deps = readList(run, o, o.issue, 'blocking', '.[] | {number, state, labels: [.labels[].name]}');
+  if (deps.error) return fail(deps.error);
+
+  const unblocked = [];
+  const stillBlocked = [];
+  for (const d of deps.items) {
+    const labels = Array.isArray(d.labels) ? d.labels : [];
+    if (!isOpen(d) || !labels.includes(LABEL)) continue;
+    const blockers = readList(run, o, d.number, 'blocked_by', '.[] | {number, state}');
+    if (blockers.error) return fail(blockers.error);
+    const open = blockers.items.filter(isOpen).map((b) => b.number);
+    if (open.length) { stillBlocked.push({ issue: d.number, openBlockers: open }); continue; }
+    const r = run(['issue', 'edit', String(d.number), '--remove-label', LABEL, '-R', o.repo]);
+    if (r.status !== 0) return fail(`gh issue edit (remove label) of #${d.number} failed: ${firstLine(r.stderr) || 'exit ' + r.status}`);
+    unblocked.push(d.number);
+  }
+  emit({ status: 'ok', unblocked, stillBlocked });
+  return 0;
+}
+
+module.exports = { main, parseArgs, parseLines };
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2), {}));
+}