@marcomigozzi/trailhead 0.15.0 → 0.16.1

package/plugins/trailhead/hooks/trailhead-bash-guards.test.js

@@ -17,8 +17,8 @@ const ok = (name, cond) => { assert.ok(cond, name); passed++; };
 const eq = (name, actual, expected) => { assert.deepStrictEqual(actual, expected, name); passed++; };
 
 // Run the merged hook end-to-end: tool_input JSON on stdin, capture {code, out, err}.
-function runHook(command, { env = {}, args = [], hook = HOOK } = {}) {
-  const input = JSON.stringify({ tool_input: { command } });
+function runHook(command, { env = {}, args = [], hook = HOOK, cwd } = {}) {
+  const input = JSON.stringify({ tool_input: { command }, ...(cwd ? { cwd } : {}) });
   const r = spawnSync('node', [hook, ...args], { input, env: { ...process.env, ...env } });
   return { code: r.status, out: r.stdout.toString(), err: r.stderr.toString() };
 }
@@ -30,9 +30,10 @@ const BAD_SECRET = 'gh issue comment 5 --body "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ012
 const BAD_INSTALL = 'npm install left-pad';
 const BAD_SEARCH = 'cd x && grep y z';
 const BAD_BODY = 'gh issue edit 5 --body ""';
+const BAD_LABELS = 'gh issue create --title x --body y --label trailhead:bug';
 
 // --- unit: constants ---
-eq('guard order is fixed', GUARD_ORDER, ['commit', 'secret', 'install', 'search', 'body']);
+eq('guard order is fixed', GUARD_ORDER, ['commit', 'secret', 'install', 'search', 'body', 'labels']);
 ok('freshness window is 5s', MOD_GUARDS_FRESH_MS === 5000);
 
 // --- unit: parseModGuards ---
@@ -48,10 +49,10 @@ for (const bad of ['commit', '@123', 'commit@abc', ',@1', '', undefined, 'commit
 eq('unknown names are ignored', [...parseModGuards(`commit,bogus@${NOW}`, NOW)], ['commit']);
 
 // --- unit: parseGuardsArg ---
-eq('no --guards -> all five', parseGuardsArg([]), GUARD_ORDER);
+eq('no --guards -> all six', parseGuardsArg([]), GUARD_ORDER);
 eq('valid subset keeps canonical order', parseGuardsArg(['--guards=body,commit']), ['commit', 'body']);
-eq('empty --guards -> all five', parseGuardsArg(['--guards=']), GUARD_ORDER);
-eq('malformed --guards -> all five', parseGuardsArg(['--guards=commit,,body']), GUARD_ORDER);
+eq('empty --guards -> all six', parseGuardsArg(['--guards=']), GUARD_ORDER);
+eq('malformed --guards -> all six', parseGuardsArg(['--guards=commit,,body']), GUARD_ORDER);
 eq('any unknown name invalidates the whole list', parseGuardsArg(['--guards=commit,secert']), GUARD_ORDER);
 
 // --- unit: runGuards with fake evaluators ---
@@ -65,7 +66,7 @@ const blocker = (code) => () => ({ kind: 'block', payload: { decision: 'block',
     evaluators: {
       commit: spy('commit', () => { throw new Error('boom'); }),
       secret: spy('secret', allow), install: spy('install', blocker('I')),
-      search: spy('search', blocker('S')), body: spy('body', allow),
+      search: spy('search', blocker('S')), body: spy('body', allow), labels: spy('labels', allow),
     },
   });
   eq('a throwing guard counts as allow and the next one still blocks', r.code, 2);
@@ -75,7 +76,7 @@ const blocker = (code) => () => ({ kind: 'block', payload: { decision: 'block',
 {
   const r = runGuards('x', {
     now: NOW, env: { TRAILHEAD_MOD_GUARDS: `commit@${NOW}` },
-    evaluators: { commit: blocker('C'), secret: allow, install: allow, search: allow, body: allow },
+    evaluators: { commit: blocker('C'), secret: allow, install: allow, search: allow, body: allow, labels: allow },
   });
   eq('a fresh stamp skips the listed guard', r.code, 0);
 }
@@ -83,7 +84,7 @@ const blocker = (code) => () => ({ kind: 'block', payload: { decision: 'block',
   const adv = (t) => () => ({ kind: 'advise', stderr: `${t}\n`, payload: { hookSpecificOutput: { additionalContext: t } } });
   const r = runGuards('x', {
     now: NOW, env: {},
-    evaluators: { commit: adv('a'), secret: adv('b'), install: allow, search: allow, body: allow },
+    evaluators: { commit: adv('a'), secret: adv('b'), install: allow, search: allow, body: allow, labels: allow },
   });
   eq('advisories exit 0', r.code, 0);
   eq('advisory stderr lines are all written', r.stderr, 'a\nb\n');
@@ -96,9 +97,10 @@ const { evaluate: evSecret } = require('./trailhead-secret-guard.js');
 const { evaluate: evInstall } = require('./trailhead-install-guard.js');
 const { evaluate: evSearch } = require('./trailhead-search-guard.js');
 const { evaluate: evBody } = require('./trailhead-body-guard.js');
+const { evaluate: evLabels } = require('./trailhead-labels-guard.js');
 for (const [name, cmd, ev] of [
   ['commit', BAD_COMMIT, evCommit], ['secret', BAD_SECRET, evSecret], ['install', BAD_INSTALL, evInstall],
-  ['search', BAD_SEARCH, evSearch], ['body', BAD_BODY, evBody],
+  ['search', BAD_SEARCH, evSearch], ['body', BAD_BODY, evBody], ['labels', BAD_LABELS, evLabels],
 ]) {
   const r = runHook(cmd);
   const want = ev(cmd);
@@ -169,19 +171,19 @@ for (const [name, cmd, ev] of [
     const hook = path.join(tmp, 'trailhead-bash-guards.js');
     fs.rmSync(path.join(tmp, 'trailhead-search-guard.js'));
 
-    const codex = runHook(BAD_SEARCH, { hook, args: ['--guards=commit,secret,install,body'] });
+    const codex = runHook(BAD_SEARCH, { hook, args: ['--guards=commit,secret,install,body,labels'] });
     eq('--guards without search never loads search-guard', codex.code, 0);
     eq('--guards without search: no warning', codex.err, '');
-    const still = runHook(BAD_INSTALL, { hook, args: ['--guards=commit,secret,install,body'] });
+    const still = runHook(BAD_INSTALL, { hook, args: ['--guards=commit,secret,install,body,labels'] });
     eq('--guards subset still blocks with its guards', still.code, 2);
     const only = runHook(BAD_INSTALL, { hook, args: ['--guards=commit'] });
     eq('unselected guards do not run', only.code, 0);
 
     for (const bad of ['--guards=', '--guards=commit,secert', '--guards=commit,,body']) {
       const r = runHook(BAD_INSTALL, { hook, args: [bad] });
-      eq(`${bad}: falls back to all five (install blocks)`, r.code, 2);
+      eq(`${bad}: falls back to all six (install blocks)`, r.code, 2);
       const clean = runHook('git status', { hook, args: [bad] });
-      ok(`${bad}: all five are selected (the missing search module is reported)`, /search/.test(clean.err));
+      ok(`${bad}: all six are selected (the missing search module is reported)`, /search/.test(clean.err));
     }
 
     const missing = runHook(`${BAD_BODY} && ${BAD_SEARCH}`, { hook });
@@ -212,12 +214,16 @@ for (const [name, cmd, ev] of [
 }
 
 // --- every existing guard suite, re-run through the merged hook ---
-for (const name of ['commit', 'secret', 'install', 'search', 'body']) {
+// Run from a scratch dir outside any trailhead repo: those suites open unlabelled issues, which
+// the labels guard (rightly) blocks inside a trailhead repo.
+const SUITE_CWD = fs.mkdtempSync(path.join(os.tmpdir(), 'tb-suites-'));
+for (const name of ['commit', 'secret', 'install', 'search', 'body', 'labels']) {
   const file = path.join(__dirname, `trailhead-${name}-guard.test.js`);
-  const r = spawnSync('node', [file], { env: { ...process.env, TRAILHEAD_GUARD_HOOK: HOOK } });
+  const r = spawnSync('node', [file], { cwd: SUITE_CWD, env: { ...process.env, TRAILHEAD_GUARD_HOOK: HOOK } });
   if (r.status !== 0) process.stderr.write(r.stdout.toString() + r.stderr.toString());
   eq(`${name}-guard suite passes through the merged hook`, r.status, 0);
 }
+fs.rmSync(SUITE_CWD, { recursive: true, force: true });
 
 // --- registration: one Bash entry, one command (the merged hook) ---
 {

package/plugins/trailhead/hooks/trailhead-labels-guard.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+// trailhead-labels-guard.js: PreToolUse(Bash) hook.
+// A trailhead ticket is identified by its label set: `trailhead:ticket`, exactly one
+// type label and exactly one destination (a map or the whiteboard). When an agent
+// opens a ticket with `gh issue create` and forgets part of that set (or adds the
+// missing labels in a later call that never comes), the ticket is invisible to the
+// board and the engine. This guard checks the label set at the create call itself.
+//   - A create that carries at least one `trailhead:*` label must carry the whole
+//     ticket shape: `trailhead:ticket`, exactly one of trailhead:decision | research |
+//     prototype | build | bug | task, and exactly one of `trailhead:map-<n>` |
+//     `trailhead:whiteboard` (never both, never two maps). Non-ticket trailhead issues
+//     (`trailhead:map`, `trailhead:dashboard`, `trailhead:codebase`,
+//     `trailhead:conventions`, and `trailhead:fog` / `trailhead:unverified`) are exempt.
+//     State labels (blocked, seed, paused, ...) are allowed extras and never count
+//     toward the shape. This rule applies in any repo.
+//   - A create with NO `trailhead:*` label is blocked too, but only inside a trailhead
+//     repo (the hook cwd sits in a git work tree whose top level has a `.trailhead/`
+//     directory) and not when aimed at another repo (-R / --repo / GH_REPO=). A
+//     deliberate non-trailhead issue opts out by prefixing the command with
+//     `TRAILHEAD_PLAIN_ISSUE=1`, like the install guard's TRAILHEAD_VERIFIED_INSTALL=1.
+//     After a `cd` the working directory is unknown, so this ground never blocks there.
+//   - A label value that cannot be resolved statically ($VAR, `$(...)`, backticks) makes
+//     the whole create unparseable: it is never blocked on what cannot be read.
+// The command is not required to START with `gh`: the shared statement walk (ghWrites in
+// secret-guard) finds each `gh issue create` through `;` `&&` `||` `|`, subshells and
+// leading NAME=v. Opaque writes (eval, sh -c, ...) are ignored (fail-open).
+// Blocks with exit 2 + {"decision":"block",...}; allows everything else.
+// Crash-safe: any error -> allow. Self-contained except for the sibling lib/ modules and
+// the secret-guard statement walk. Pure functions are exported for tests and the merged
+// trailhead-bash-guards.js; runs as a hook when executed directly.
+
+const fs = require('fs');
+const path = require('path');
+const { parseGhSubcommand, dequote } = require('./lib/gh-subcommand.js');
+const { words, parseRedirects } = require('./lib/body-sources.js');
+
+const PLAIN_SENTINEL = /(?:^|\s)TRAILHEAD_PLAIN_ISSUE=1(?:\s|$)/;
+const TYPES = ['decision', 'research', 'prototype', 'build', 'bug', 'task'];
+const EXEMPT = ['trailhead:map', 'trailhead:dashboard', 'trailhead:codebase', 'trailhead:conventions', 'trailhead:fog', 'trailhead:unverified'];
+const MAP_RE = /^trailhead:map-\d+$/;
+const WHITEBOARD = 'trailhead:whiteboard';
+const TYPE_LIST = TYPES.map((t) => `trailhead:${t}`).join(' | ');
+
+// gh issue create flags that consume a value (long and short forms).
+const VALUE_FLAGS = new Set([
+  '--assignee', '--body', '--body-file', '--label', '--milestone', '--project', '--repo', '--title', '--template', '--recover',
+  '-a', '-b', '-F', '-l', '-m', '-p', '-R', '-t', '-T',
+]);
+const ASSIGN_RE = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+// Read the options of one `gh issue create` statement.
+//   { labels: [lowercased label names], unresolved: bool, repoFlag: bool, help: bool }
+function parseCreate(text) {
+  const { args } = parseRedirects(words(text));
+  const toks = args.map(dequote);
+  const labels = [];
+  let unresolved = false;
+  let repoFlag = false;
+  let help = false;
+  let afterCreate = false;
+  let sawIssue = false;
+  const take = (v) => {
+    if (/[$`]/.test(v)) unresolved = true;
+    for (const part of v.split(',')) {
+      const l = part.trim().toLowerCase();
+      if (l) labels.push(l);
+    }
+  };
+  // leading NAME=v: GH_REPO aims the command at another repo
+  let i = 0;
+  while (i < toks.length && ASSIGN_RE.test(toks[i])) {
+    if (/^GH_REPO=/.test(toks[i])) repoFlag = true;
+    i++;
+  }
+  for (i += 1; i < toks.length; i++) { // past the gh word
+    if (args[i].startsWith('#')) break; // an unquoted shell comment: the rest is not an argument
+    const t = toks[i];
+    if (t === '-h' || t === '--help') { help = true; continue; }
+    if (!t.startsWith('-')) {
+      if (!sawIssue && t === 'issue') sawIssue = true;
+      else if (sawIssue && t === 'create') afterCreate = true;
+      continue;
+    }
+    let flag = t;
+    let value;
+    if (t.startsWith('--')) {
+      const eq = t.indexOf('=');
+      if (eq !== -1) { flag = t.slice(0, eq); value = t.slice(eq + 1); }
+      else if (VALUE_FLAGS.has(t)) value = toks[++i];
+    } else if (VALUE_FLAGS.has(t)) {
+      value = toks[++i];
+    } else if (t.length > 2 && VALUE_FLAGS.has(t.slice(0, 2))) {
+      flag = t.slice(0, 2); // glued shorthand: -lbug, -l=bug
+      value = t.slice(2).replace(/^=/, '');
+    }
+    if (value === undefined) continue;
+    if (flag === '-R' || flag === '--repo') repoFlag = true;
+    else if (afterCreate && (flag === '--label' || flag === '-l')) take(value);
+  }
+  return { labels, unresolved, repoFlag, help };
+}
+
+// Is `cwd` in a git work tree whose top level has a `.trailhead/` directory? Walks up to
+// the first directory holding `.git` (dir or file). Any fs error -> false (fail open).
+function inTrailheadRepo(cwd) {
+  try {
+    let dir = path.resolve(cwd || process.cwd());
+    for (;;) {
+      if (fs.existsSync(path.join(dir, '.git'))) {
+        return fs.statSync(path.join(dir, '.trailhead')).isDirectory();
+      }
+      const up = path.dirname(dir);
+      if (up === dir) return false;
+      dir = up;
+    }
+  } catch {
+    return false;
+  }
+}
+
+// The ticket-shape problems of a label set that has at least one trailhead:* label
+// and is not a non-ticket issue. Empty list = well formed.
+function shapeProblems(th) {
+  const problems = [];
+  if (!th.includes('trailhead:ticket')) problems.push('missing `trailhead:ticket`');
+  const types = th.filter((l) => TYPES.some((t) => l === `trailhead:${t}`));
+  if (types.length === 0) problems.push(`missing a type label (exactly one of ${TYPE_LIST})`);
+  else if (new Set(types).size > 1) problems.push(`conflicting type labels (${[...new Set(types)].join(', ')}): keep exactly one`);
+  const maps = [...new Set(th.filter((l) => MAP_RE.test(l)))];
+  const board = th.includes(WHITEBOARD);
+  if (maps.length === 0 && !board) problems.push('missing a destination (exactly one of `trailhead:map-<n>` | `trailhead:whiteboard`)');
+  else if (maps.length > 1) problems.push(`two map destinations (${maps.join(', ')}): keep exactly one`);
+  else if (maps.length === 1 && board) problems.push(`two destinations (${maps[0]} and ${WHITEBOARD}): keep exactly one`);
+  return problems;
+}
+
+const RETRY =
+  'Retry with the full label set in the SAME `gh issue create` call (`--label trailhead:ticket --label <type> --label <destination>`); ' +
+  'never add labels afterwards with `--add-label`.';
+
+function block(code, reason) {
+  return { kind: 'block', payload: { decision: 'block', code, reason } };
+}
+
+// Verdict for one parsed create, or null to allow.
+function checkCreate(parsed, { cmd, cwd, cwdKnown }) {
+  if (parsed.help) return null; // `--help` creates nothing
+  if (parsed.unresolved) return null; // a label we cannot read: never block on it
+  const th = parsed.labels.filter((l) => l.startsWith('trailhead:'));
+  if (th.length > 0) {
+    if (th.some((l) => EXEMPT.includes(l))) return null; // a non-ticket trailhead issue
+    const problems = shapeProblems(th);
+    if (problems.length === 0) return null;
+    return block(
+      'TICKET_LABELS_INCOMPLETE',
+      `trailhead: this gh issue create opens a trailhead ticket (labels: ${th.join(', ')}) with an incomplete label set: ${problems.join('; ')}. ${RETRY}`,
+    );
+  }
+  if (parsed.repoFlag || !cwdKnown || PLAIN_SENTINEL.test(cmd)) return null;
+  if (!inTrailheadRepo(cwd)) return null;
+  return block(
+    'TRAILHEAD_ISSUE_WITHOUT_LABELS',
+    'trailhead: this gh issue create carries no `trailhead:*` label, so the issue would be invisible to the board and the engine. ' +
+      `${RETRY} ` +
+      'For a deliberate non-trailhead issue, re-run the exact command prefixed with `TRAILHEAD_PLAIN_ISSUE=1`.',
+  );
+}
+
+// Every statement of the command that is a `gh issue create`: { text, cwdKnown }.
+function creates(cmd) {
+  let ghWrites;
+  try {
+    ({ ghWrites } = require('./trailhead-secret-guard.js'));
+  } catch {
+    return [{ text: cmd, cwdKnown: true }]; // partial install: check the lone statement
+  }
+  const out = [];
+  for (const w of ghWrites(cmd, {})) {
+    if (w.kind !== 'issue') continue;
+    const p = parseGhSubcommand(w.text);
+    if (p && p.sub === 'issue' && p.verb === 'create') out.push({ text: w.text, cwdKnown: w.cwdKnown });
+  }
+  return out;
+}
+
+// Pure verdict: null (allow), or { kind:'block', payload }. Never exits or writes; any
+// internal error allows.
+function evaluate(cmd, opts) {
+  try {
+    const cwd = opts && opts.cwd;
+    for (const c of creates(String(cmd))) {
+      const p = parseGhSubcommand(c.text);
+      if (!p || p.sub !== 'issue' || p.verb !== 'create') continue;
+      const verdict = checkCreate(parseCreate(c.text), { cmd: String(cmd), cwd, cwdKnown: c.cwdKnown });
+      if (verdict) return verdict;
+    }
+  } catch {
+    // a guard must never wedge the workflow
+  }
+  return null;
+}
+
+function run(data) {
+  let cmd = '';
+  let cwd;
+  try {
+    const input = JSON.parse(data);
+    cmd = (input.tool_input || {}).command || '';
+    cwd = typeof input.cwd === 'string' && input.cwd ? input.cwd : undefined;
+  } catch {
+    process.exit(0);
+  }
+  const v = evaluate(cmd, { cwd });
+  if (v && v.kind === 'block') {
+    process.stdout.write(JSON.stringify(v.payload));
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
+if (require.main === module) {
+  let data = '';
+  const timer = setTimeout(() => process.exit(0), 5000); // stdin never ends -> give up
+  process.stdin.on('data', (c) => (data += c));
+  process.stdin.on('end', () => {
+    clearTimeout(timer);
+    run(data);
+  });
+}
+
+module.exports = { parseCreate, shapeProblems, inTrailheadRepo, evaluate };

package/plugins/trailhead/hooks/trailhead-labels-guard.test.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// Tests for trailhead-labels-guard.js. Run: node trailhead-labels-guard.test.js
+// No framework: plain asserts + child_process for the end-to-end hook behaviour.
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+// TRAILHEAD_GUARD_HOOK re-runs this suite through the merged trailhead-bash-guards.js.
+const HOOK = process.env.TRAILHEAD_GUARD_HOOK || path.join(__dirname, 'trailhead-labels-guard.js');
+const { evaluate, parseCreate, inTrailheadRepo } = require('./trailhead-labels-guard.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// Scratch dirs: a trailhead repo (.git + .trailhead/), a plain repo (.git only), a plain dir.
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'labels-guard-'));
+const mk = (rel, ...sub) => {
+  const d = path.join(tmp, rel);
+  fs.mkdirSync(d, { recursive: true });
+  for (const s of sub) fs.mkdirSync(path.join(d, s), { recursive: true });
+  return d;
+};
+const TH = mk('th', '.git', '.trailhead', 'src/deep');
+const THDEEP = path.join(TH, 'src', 'deep');
+const PLAIN_REPO = mk('plain', '.git');
+const NOREPO = mk('norepo');
+// A worktree-style repo: `.git` is a file, not a dir.
+const WT = mk('wt', '.trailhead');
+fs.writeFileSync(path.join(WT, '.git'), 'gitdir: /elsewhere\n');
+
+// Run the hook end-to-end: tool_input JSON (+ cwd) on stdin, capture {code, out}.
+function runHook(command, cwd) {
+  const input = JSON.stringify({ tool_input: { command }, ...(cwd ? { cwd } : {}) });
+  const r = spawnSync('node', [HOOK], { input, cwd: NOREPO });
+  return { code: r.status, out: r.stdout.toString() };
+}
+const blocked = (cmd, cwd) => { const v = evaluate(cmd, { cwd, env: {} }); return !!v && v.kind === 'block'; };
+const reasonOf = (cmd, cwd) => { const v = evaluate(cmd, { cwd, env: {} }); return v ? v.payload.reason : ''; };
+const codeOf = (cmd, cwd) => { const v = evaluate(cmd, { cwd, env: {} }); return v ? v.payload.code : null; };
+
+const create = (labels, extra = '') =>
+  `gh issue create --title x --body y ${labels.map((l) => `--label ${l}`).join(' ')} ${extra}`.trim();
+const FULL_WB = ['trailhead:ticket', 'trailhead:bug', 'trailhead:whiteboard'];
+const FULL_MAP = ['trailhead:ticket', 'trailhead:build', 'trailhead:map-12'];
+
+// --- the repro commands (#308) ---
+{
+  const r1 = 'gh issue create --label trailhead:bug --label trailhead:whiteboard --title x --body-file /dev/null';
+  const r2 = 'gh issue create --label "trailhead:bug,trailhead:whiteboard" --title x --body y';
+  const r3 = 'gh issue create --title x --body y';
+  for (const c of [r1, r2]) {
+    ok(`blocks partial set: ${c.slice(0, 50)}`, blocked(c, NOREPO));
+    ok('names the missing ticket label', reasonOf(c, NOREPO).includes('missing `trailhead:ticket`'));
+    ok('tells to retry in the same create call', /SAME `gh issue create`/.test(reasonOf(c, NOREPO)) && /--add-label/.test(reasonOf(c, NOREPO)));
+    const h = runHook(c, NOREPO);
+    ok('hook exits 2 with a block payload', h.code === 2 && JSON.parse(h.out).decision === 'block');
+  }
+  ok('no-label create is blocked in a trailhead repo', blocked(r3, TH));
+  ok('no-label block mentions the opt-out', reasonOf(r3, TH).includes('TRAILHEAD_PLAIN_ISSUE=1'));
+  const h = runHook(r3, TH);
+  ok('no-label hook exits 2 inside a trailhead repo', h.code === 2 && JSON.parse(h.out).code === 'TRAILHEAD_ISSUE_WITHOUT_LABELS');
+  ok('no-label hook exits 0 outside', runHook(r3, NOREPO).code === 0);
+}
+
+// --- a complete ticket is allowed ---
+ok('whiteboard ticket passes', !blocked(create(FULL_WB), TH));
+ok('map ticket passes', !blocked(create(FULL_MAP), TH));
+ok('comma-separated full set passes', !blocked('gh issue create --title x --body y --label "trailhead:ticket,trailhead:task,trailhead:map-3"', TH));
+ok('-l shorthand passes', !blocked('gh issue create -t x -b y -l trailhead:ticket -l trailhead:research -l trailhead:whiteboard', TH));
+ok('--label=value passes', !blocked('gh issue create --title x --body y --label=trailhead:ticket --label=trailhead:decision --label=trailhead:whiteboard', TH));
+ok('glued -lvalue passes', !blocked('gh issue create -t x -b y -ltrailhead:ticket -ltrailhead:task -ltrailhead:map-1', TH));
+ok('quoted values pass', !blocked('gh issue create --title x --body y --label "trailhead:ticket" --label \'trailhead:prototype\' --label "trailhead:whiteboard"', TH));
+ok('state labels are allowed extras', !blocked(create([...FULL_WB, 'trailhead:blocked', 'trailhead:needs-you', 'bug']), TH));
+ok('non-trailhead labels beside a full set pass', !blocked(create([...FULL_MAP, 'enhancement']), NOREPO));
+ok('every type passes', ['decision', 'research', 'prototype', 'build', 'bug', 'task']
+  .every((t) => !blocked(create(['trailhead:ticket', `trailhead:${t}`, 'trailhead:whiteboard']), TH)));
+ok('seed shape passes', !blocked(create(['trailhead:ticket', 'trailhead:task', 'trailhead:map-4', 'trailhead:seed', 'trailhead:blocked']), TH));
+ok('a seed without type is blocked', blocked(create(['trailhead:ticket', 'trailhead:map-4', 'trailhead:seed', 'trailhead:blocked']), TH));
+
+// --- the shape rules, with the names in the reason ---
+{
+  const noTicket = create(['trailhead:bug', 'trailhead:map-2']);
+  ok('missing ticket blocks', blocked(noTicket, NOREPO) && reasonOf(noTicket, NOREPO).includes('missing `trailhead:ticket`'));
+  const noType = create(['trailhead:ticket', 'trailhead:whiteboard']);
+  ok('missing type blocks', blocked(noType, NOREPO) && /missing a type label/.test(reasonOf(noType, NOREPO)));
+  ok('missing type names the choices', reasonOf(noType, NOREPO).includes('trailhead:decision'));
+  const noDest = create(['trailhead:ticket', 'trailhead:bug']);
+  ok('missing destination blocks', blocked(noDest, NOREPO) && /missing a destination/.test(reasonOf(noDest, NOREPO)));
+  const both = create(['trailhead:ticket', 'trailhead:bug', 'trailhead:map-2', 'trailhead:whiteboard']);
+  ok('both destinations block', blocked(both, NOREPO) && /two destinations \(trailhead:map-2 and trailhead:whiteboard\)/.test(reasonOf(both, NOREPO)));
+  const twoMaps = create(['trailhead:ticket', 'trailhead:bug', 'trailhead:map-2', 'trailhead:map-3']);
+  ok('two maps block', blocked(twoMaps, NOREPO) && /two map destinations \(trailhead:map-2, trailhead:map-3\)/.test(reasonOf(twoMaps, NOREPO)));
+  const twoTypes = create(['trailhead:ticket', 'trailhead:bug', 'trailhead:task', 'trailhead:whiteboard']);
+  ok('two types block', blocked(twoTypes, NOREPO) && /conflicting type labels \(trailhead:bug, trailhead:task\)/.test(reasonOf(twoTypes, NOREPO)));
+  const multi = create(['trailhead:whiteboard']);
+  ok('several gaps are all named', ['trailhead:ticket', 'type label'].every((n) => reasonOf(multi, NOREPO).includes(n)));
+  ok('a state label alone does not satisfy the shape', blocked(create(['trailhead:blocked']), NOREPO));
+  ok('trailhead:map alone is not a destination for a ticket',
+    !blocked(create(['trailhead:map']), NOREPO)); // it IS the map issue, exempt
+  ok('a bare map-x (not digits) is no destination', blocked(create(['trailhead:ticket', 'trailhead:bug', 'trailhead:map-x']), NOREPO));
+  ok('labels are matched case-insensitively', !blocked(create(['Trailhead:Ticket', 'TRAILHEAD:BUG', 'trailhead:WhiteBoard']), NOREPO));
+}
+
+// --- non-ticket trailhead issues are exempt ---
+for (const l of ['trailhead:map', 'trailhead:dashboard', 'trailhead:codebase', 'trailhead:conventions', 'trailhead:fog', 'trailhead:unverified']) {
+  ok(`${l} create passes`, !blocked(create([l]), TH));
+}
+ok('map issue with extra labels passes', !blocked(create(['trailhead:map', 'trailhead:paused']), TH));
+
+// --- no-label ground: only inside a trailhead repo ---
+{
+  const bare = 'gh issue create --title x --body y';
+  ok('blocked at the trailhead repo root', blocked(bare, TH));
+  ok('blocked from a subdirectory (walks up to .git)', blocked(bare, THDEEP));
+  ok('blocked in a worktree whose .git is a file', blocked(bare, WT));
+  ok('allowed in a repo without .trailhead/', !blocked(bare, PLAIN_REPO));
+  ok('allowed outside any repo', !blocked(bare, NOREPO));
+  ok('allowed with an unlabelled non-trailhead label', !blocked(bare, NOREPO) && blocked(`${bare} --label bug`, TH));
+  ok('TRAILHEAD_PLAIN_ISSUE=1 opts out', !blocked(`TRAILHEAD_PLAIN_ISSUE=1 ${bare}`, TH));
+  ok('opt-out works on a compound command', !blocked(`cd x; TRAILHEAD_PLAIN_ISSUE=1 ${bare}`, TH));
+  ok('TRAILHEAD_PLAIN_ISSUE=0 does not opt out', blocked(`TRAILHEAD_PLAIN_ISSUE=0 ${bare}`, TH));
+  ok('opt-out never excuses a partial trailhead set', blocked(`TRAILHEAD_PLAIN_ISSUE=1 ${create(['trailhead:bug'])}`, TH));
+  ok('-R other/repo is not blocked on the no-label ground', !blocked(`${bare} -R other/repo`, TH));
+  ok('--repo=other/repo is not blocked on the no-label ground', !blocked(`${bare} --repo=other/repo`, TH));
+  ok('global -R before the subcommand is not blocked', !blocked('gh -R other/repo issue create --title x --body y', TH));
+  ok('GH_REPO=other/repo is not blocked on the no-label ground', !blocked(`GH_REPO=other/repo ${bare}`, TH));
+  ok('-R other/repo is still checked on the partial-label ground', blocked(`${create(['trailhead:bug'])} -R other/repo`, TH));
+  ok('--web with no labels is treated like any create', blocked('gh issue create --web', TH));
+  ok('an unreadable cwd fails open', !blocked(bare, path.join(tmp, 'does', 'not', 'exist')));
+  ok('inTrailheadRepo: .trailhead as a plain file is not a trailhead repo', (() => {
+    const d = mk('filedir', '.git');
+    fs.writeFileSync(path.join(d, '.trailhead'), 'x');
+    return inTrailheadRepo(d) === false;
+  })());
+}
+
+// --- unresolvable labels fail open ---
+ok('$VAR label does not block', !blocked('gh issue create --title x --body y --label "$LABEL"', TH));
+ok('$VAR beside a partial set does not block', !blocked('gh issue create --title x --body y --label trailhead:bug --label $L', TH));
+ok('backtick label does not block', !blocked('gh issue create --title x --body y --label `cat l`', TH));
+ok('$(...) label does not block', !blocked('gh issue create --title x --body y --label "$(echo trailhead:bug)"', TH));
+ok('${VAR}-embedded label does not block', !blocked('gh issue create --title x --body y --label "trailhead:${KIND}"', TH));
+
+// --- compound commands, wrappers, quoting ---
+{
+  const bad = 'gh issue create --title x --body y --label trailhead:bug';
+  ok('after cd &&', blocked(`cd x && ${bad}`, NOREPO));
+  ok('after ;', blocked(`echo hi; ${bad}`, NOREPO));
+  ok('after &&', blocked(`true && ${bad}`, NOREPO));
+  ok('after ||', blocked(`false || ${bad}`, NOREPO));
+  ok('in a subshell', blocked(`(${bad})`, NOREPO));
+  ok('behind a leading assignment', blocked(`FOO=1 ${bad}`, NOREPO));
+  ok('behind a global flag', blocked('gh --hostname h issue create --title x --body y --label trailhead:bug', NOREPO));
+  ok('behind -R', blocked('gh -R o/r issue create --title x --body y --label trailhead:bug', NOREPO));
+  ok('quoted gh word', blocked('"gh" issue create --title x --body y --label trailhead:bug', NOREPO));
+  ok('the second of two creates is checked', blocked(`${create(FULL_WB)} && ${bad}`, NOREPO));
+  ok('two good creates pass', !blocked(`${create(FULL_WB)} && ${create(FULL_MAP)}`, TH));
+  ok('after a cd the cwd is unknown: no-label ground does not block', !blocked('cd /elsewhere && gh issue create --title x --body y', TH));
+  ok('a label-looking word in the title is not a label', blocked('gh issue create --title "--label trailhead:ticket" --body y --label trailhead:bug', NOREPO));
+  ok('a label-looking word in the body is not a label', !blocked('gh issue create --title x --body "-l trailhead:bug" --label trailhead:ticket --label trailhead:bug --label trailhead:whiteboard', NOREPO));
+  ok('a quoted gh text in an echo is not a create', !blocked('echo "gh issue create --label trailhead:bug"', TH));
+  ok('a heredoc body mentioning a create is not a create', !blocked('cat <<EOF\ngh issue create --label trailhead:bug\nEOF', TH));
+  ok('the create is blocked through a pipeline', blocked(`echo y | ${bad}`, NOREPO));
+}
+
+// --- everything that is not `gh issue create` is untouched ---
+for (const c of [
+  'gh issue edit 5 --add-label trailhead:bug',
+  'gh issue list --label trailhead:bug',
+  'gh issue view 5 --json labels',
+  'gh issue comment 5 --body hi',
+  'gh pr create --title x --body y',
+  'gh pr create --title x --body y --label trailhead:bug',
+  'git status',
+  'gh label create trailhead:bug',
+  'gh api repos/o/r/issues -f title=x',
+  '',
+]) ok(`untouched: ${c || '(empty)'}`, !blocked(c, TH));
+
+// --- help and shell comments (review of #308) ---
+ok('--help is not a create', !blocked('gh issue create --help', TH));
+ok('-h is not a create', !blocked('gh issue create -h', TH));
+ok('a trailing comment cannot supply the labels',
+  blocked('gh issue create -t x -b y # --label trailhead:ticket,trailhead:bug,trailhead:whiteboard', TH));
+ok('a comment after a full set changes nothing', !blocked(`${create(FULL_WB)} # note`, TH));
+ok('a quoted # is still a value', !blocked('gh issue create -t "#1 x" -b y --label "trailhead:ticket,trailhead:bug,trailhead:whiteboard"', TH));
+
+// --- parseCreate ---
+{
+  const p = parseCreate('gh issue create -l a,b --label=c -ld --title t');
+  ok('parseCreate reads every label form', JSON.stringify(p.labels) === JSON.stringify(['a', 'b', 'c', 'd']));
+  ok('parseCreate flags an unresolved value', parseCreate('gh issue create --label $X').unresolved === true);
+  ok('parseCreate sees -R', parseCreate('gh issue create -R o/r').repoFlag === true);
+}
+
+// --- crash-safety ---
+ok('non-string input does not throw', evaluate(undefined, {}) === null && evaluate(null) === null);
+{
+  const bad = spawnSync('node', [HOOK], { input: 'not json {{' });
+  ok('unparseable hook input exits 0', bad.status === 0);
+  const nul = spawnSync('node', [HOOK], { input: 'null' });
+  ok('null hook input exits 0', nul.status === 0);
+  const clean = runHook('git status', TH);
+  ok('a clean command exits 0 with empty stdout', clean.code === 0 && clean.out === '');
+  const good = runHook(create(FULL_WB), TH);
+  ok('a full whiteboard create exits 0 end to end', good.code === 0 && good.out === '');
+}
+
+fs.rmSync(tmp, { recursive: true, force: true });
+console.log(`labels-guard: ${passed} assertions passed`);