@marcomigozzi/trailhead 0.14.0 → 0.16.0

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

@@ -4,10 +4,12 @@
 const assert = require('assert');
 const { execFileSync } = 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-install-guard.js');
-const { detectInstall, isVerified } = require('./trailhead-install-guard.js');
+const { detectInstall, isVerified, evaluate } = require('./trailhead-install-guard.js');
 
 let passed = 0;
 const ok = (name, cond) => { assert.ok(cond, name); passed++; };
@@ -86,6 +88,176 @@ ok('detects install after ; chain', (() => { const d = detectInstall('echo hi; p
 ok('detects install in a piped tail', (() => { const d = detectInstall('true | cargo add serde'); return d && d.packages.includes('serde'); })());
 ok('compound with no install stays null', detectInstall('cd app && npm run build && ls') === null);
 
+// --- unit: lockfile installs, redirections, quoted text (#239) ---
+const heredocDoc = ['cat > /tmp/x.md <<\'EOF\'', '| `pnpm install a 2>&1` | x |', 'EOF'].join('\n');
+const neg239 = [
+  'pnpm install --frozen-lockfile --offline 2>&1',
+  'cd app && pnpm install --frozen-lockfile --offline 2>&1 | tail -5',
+  'pnpm install --frozen-lockfile > /tmp/log',
+  'pnpm install --frozen-lockfile --filter web',
+  'pnpm install --frozen-lockfile',
+  'yarn install --immutable',
+  'bun install --frozen-lockfile',
+  'yarn install --frozen-lockfile',
+  'npm install 2>&1',
+  'echo "done; pnpm install lodash"',
+  'echo "a && npm install foo"',
+  'echo "next: pnpm install then build"',
+  'git commit -m "fix: pnpm install guard | npm i x"',
+  heredocDoc,
+];
+for (const cmd of neg239) {
+  ok(`ignores: ${cmd.split('\n')[0]}`, detectInstall(cmd) === null);
+}
+
+// Redirections and quoting must not hide a real named install, nor leak into the name.
+const pos239 = [
+  ['npm install lodash 2>&1', 'npm', ['lodash']],
+  ['pnpm add vite > /tmp/log', 'npm', ['vite']],
+  ['npm install "lodash"', 'npm', ['lodash']],
+  ['echo ok && npm install lodash', 'npm', ['lodash']],
+  ['echo ok; pip install requests', 'pip', ['requests']],
+  ['pnpm add --filter web vite', 'npm', ['vite']],
+];
+for (const [cmd, eco, names] of pos239) {
+  const d = detectInstall(cmd);
+  ok(`detects exactly: ${cmd}`, d && d.ecosystem === eco && JSON.stringify(d.packages) === JSON.stringify(names));
+}
+
+// A lockfile flag never excuses a typed name: the named package is still gated.
+const posLock = [
+  ['npm i --frozen-lockfile evilpkg', 'evilpkg'],
+  ['pnpm install --frozen-lockfile evilpkg', 'evilpkg'],
+  ['yarn install --immutable evilpkg', 'evilpkg'],
+  ['npm install evilpkg --frozen', 'evilpkg'],
+];
+for (const [cmd, name] of posLock) {
+  const d = detectInstall(cmd);
+  ok(`detects despite lockfile flag: ${cmd}`, d && d.packages.includes(name));
+  const r = runHook(cmd);
+  ok(`blocks despite lockfile flag: ${cmd}`, r.code === 2 && new RegExp(name).test(r.out));
+}
+
+// A bare `&` (background) is never listed as a package name.
+ok('background & is not a package', JSON.stringify((detectInstall('npm install lodash &') || {}).packages) === JSON.stringify(['lodash']));
+
+// --- unit: wrapped installs and file-like names (#255) ---
+const posWrap = [
+  ['sudo npm install lodash', 'lodash'],
+  ['time pip install requests', 'requests'],
+  ['env FOO=1 npm i lodash', 'lodash'],
+  ['nohup npm install lodash', 'lodash'],
+  ['xargs npm install lodash', 'lodash'],
+  ['sudo -u bob npm install lodash', 'lodash'],   // flag with a separate-token value
+  ['sudo -- npm i lodash', 'lodash'],
+  ['sudo -E npm i lodash', 'lodash'],
+  ['env -u HOME npm i lodash', 'lodash'],
+  ['env -C /tmp FOO=1 npm i lodash', 'lodash'],
+  ['time -p pip install requests', 'requests'],
+  ['time -o /tmp/t pip install requests', 'requests'],
+  ['xargs -n 1 npm install lodash', 'lodash'],
+  ['xargs -I {} pip install requests', 'requests'],
+  ['xargs --max-args=1 npm i lodash', 'lodash'],
+  ['sudo env FOO=1 nohup npm i lodash', 'lodash'],   // chain
+  ['FOO=1 sudo -u root time -p pip install requests', 'requests'],
+  ['cd app && sudo npm install lodash', 'lodash'],
+  ['/usr/bin/sudo npm install lodash', 'lodash'],
+  ['sudo -nu root npm i lodash', 'lodash'],      // bundled short flags, value flag last
+  ['sudo -Eu bob npm i lodash', 'lodash'],
+  ['sudo -iu root npm i lodash', 'lodash'],
+  ['sudo -uroot npm i lodash', 'lodash'],        // attached value
+  ['sudo -nE npm i lodash', 'lodash'],           // cluster with no value flag
+  ['env -S "npm i lodash"', 'lodash'],           // split-string payload is the command
+  ['env -S npm i lodash', 'lodash'],
+  ["env -S 'npm i lodash'", 'lodash'],
+  ['env --split-string="npm i lodash"', 'lodash'],
+  ['env --split-string npm i lodash', 'lodash'],
+  ['env -a name npm i lodash', 'lodash'],        // argv0 value, command follows
+  ['env -S "FOO=1 sudo npm i lodash"', 'lodash'],
+];
+for (const [cmd, name] of posWrap) {
+  const d = detectInstall(cmd);
+  ok(`detects wrapped: ${cmd}`, d && d.packages.includes(name));
+}
+const negWrap = [
+  'sudo npm install',
+  'sudo npm ci',
+  'time npm install --frozen-lockfile',
+  'env FOO=1 npm install',
+  'xargs echo npm install foo',     // xargs runs echo
+  'sudo -u bob ls',
+  'sudo',
+  'env',
+  'sudo -u',
+  'sudo -nu root ls',
+  'env -S "ls -la"',
+  'env -S "npm install"',
+];
+for (const cmd of negWrap) {
+  ok(`ignores wrapped: ${cmd}`, detectInstall(cmd) === null);
+}
+
+// A file-like suffix is local only for a path or an existing file.
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'install-guard-'));
+fs.writeFileSync(path.join(tmp, 'foo.tgz'), '');
+const inTmp = { cwd: tmp };
+const posFile = ['pip install foo.txt', 'npm install left-pad.toml', 'npm install nope.tgz', 'pip install pkg.whl'];
+for (const cmd of posFile) {
+  const d = detectInstall(cmd, inTmp);
+  ok(`gates absent file-like name: ${cmd}`, d && d.packages.length === 1);
+}
+const negFile = [
+  'pip install ./foo.txt',
+  'pip install sub/req.txt',
+  'pip install /abs/req.txt',
+  'pip install ~/req.txt',
+  'npm install foo.tgz',            // exists in cwd
+];
+for (const cmd of negFile) {
+  ok(`allows path or existing file: ${cmd}`, detectInstall(cmd, inTmp) === null);
+}
+ok('existing file resolved against cwd, not process cwd', detectInstall('npm install foo.tgz', { cwd: os.tmpdir() }) !== null);
+ok('injectable exists check', detectInstall('npm install x.tgz', { exists: () => true }) === null);
+ok('scoped name is never a path', (() => { const d = detectInstall('npm install @scope/pkg.zip', inTmp); return d && d.packages[0] === '@scope/pkg.zip'; })());
+ok('evaluate tolerates null opts', evaluate('npm install lodash', null).kind === 'block');
+const wf = evaluate('npm install foo.tgz', { cwd: tmp });
+ok('evaluate threads cwd (existing file allowed)', wf.kind === 'allow');
+ok('evaluate blocks absent file-like name', evaluate('pip install foo.txt', { cwd: tmp }).kind === 'block');
+const wrapRun = runHook('sudo npm install lodash');
+ok('blocks a sudo-wrapped install end-to-end (exit 2)', wrapRun.code === 2 && /lodash/.test(wrapRun.out));
+const cwdRun = (() => {
+  const input = JSON.stringify({ cwd: tmp, tool_input: { command: 'npm install foo.tgz' } });
+  try { return { code: 0, out: execFileSync('node', [HOOK], { input }).toString() }; } catch (e) { return { code: e.status }; }
+})();
+ok('hook honours input.cwd for the on-disk check (exit 0)', cwdRun.code === 0);
+fs.rmSync(tmp, { recursive: true, force: true });
+
+// Wrappers peeled with their flags: timeout (+ DURATION), nice, stdbuf, setsid, ionice, doas, command, exec.
+const wrapHits = [
+  'timeout 10 npm i x', 'timeout -s KILL 10 npm i x', 'timeout --signal=KILL 5s npm i x',
+  'timeout -k 1 10 npm i x', 'nice npm i x', 'nice -n 5 npm i x', 'nice -n5 npm i x', 'nice -5 npm i x',
+  'command npm i x', 'command -p npm i x', 'exec npm i x', 'exec -a foo npm i x',
+  'doas npm i x', 'doas -u root npm i x', 'setsid npm i x', 'setsid -w npm i x',
+  'ionice -c 3 npm i x', 'stdbuf -oL npm i x', 'stdbuf -o L npm i x',
+  'sudo timeout 10 nice npm i x', 'xargs timeout 10 npm i x', 'timeout -- 10 npm i x',
+  'env -S "env -S \\"npm i lodash\\""',
+  'env -S "env -S \\"env -S \\\\\\"npm i lodash\\\\\\"\\""',
+  "env -S 'npm i lodash'",
+];
+for (const c of wrapHits) ok(`wrapper hit: ${c}`, detectInstall(c) && detectInstall(c).packages.length > 0);
+const wrapMisses = [
+  'timeout 10 ls', 'nice ls', 'command -v npm', 'command -v npm i x', 'command -V npm i x',
+  'command -pv npm i x', 'exec 3>&1', 'exec -a npm ls', 'doas ls',
+  "env -S 'echo \"npm i lodash\"'", 'env -S "echo \\"npm i lodash\\""',
+];
+for (const c of wrapMisses) ok(`wrapper miss: ${c}`, detectInstall(c) === null);
+
+// Known unmodelled gaps (documented, NOT asserted): this guard reads one plain
+// command per statement plus the wrappers it peels, so an install behind
+// `bash -c "..."` / `sh -c "..."`, `$( )`, `eval`, other wrappers (`chrt`,
+// `taskset`, `flock`, `su -c`), or a GNU long-option prefix abbreviation
+// taking a separate value (`timeout --sig KILL 5 ...`) is not seen.
+
 // --- unit: isVerified ---
 ok('sentinel recognised', isVerified('TRAILHEAD_VERIFIED_INSTALL=1 npm install lodash'));
 ok('no sentinel', !isVerified('npm install lodash'));
@@ -107,6 +279,13 @@ ok('non-install allowed (exit 0)', a3.code === 0 && a3.out.trim() === '');
 const a4 = runHook('pip install -r requirements.txt');
 ok('requirements-file install allowed (exit 0)', a4.code === 0 && a4.out.trim() === '');
 
+const a5 = runHook('cd app && pnpm install --frozen-lockfile --offline 2>&1 | tail -5');
+ok('lockfile install with redirection allowed (exit 0)', a5.code === 0 && a5.out.trim() === '');
+const a6 = runHook('echo "done; pnpm install lodash"');
+ok('install text inside echo allowed (exit 0)', a6.code === 0 && a6.out.trim() === '');
+const b3 = runHook('npm install lodash 2>&1');
+ok('named install with redirection still blocks (exit 2)', b3.code === 2 && /lodash/.test(b3.out));
+
 // --- end-to-end: unparseable stdin allowed ---
 const u = (() => {
   try {

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`);