@marcomigozzi/trailhead 0.15.0 → 0.16.1

package/bin/lib/codex-projection.test.js

@@ -173,8 +173,8 @@ const entries = codexHookEntries('/h');
 ok('codexHookEntries returns 5 entries', Array.isArray(entries) && entries.length === 5);
 const bashEntries = entries.filter((e) => e.event === 'PreToolUse' && e.matcher === 'Bash');
 ok('codexHookEntries: exactly one PreToolUse/Bash registration', bashEntries.length === 1);
-ok('codexHookEntries: the Bash entry is the merged hook with exactly --guards=commit,secret,install,body',
-  bashEntries[0].command === 'node "/h/trailhead-bash-guards.js" --guards=commit,secret,install,body');
+ok('codexHookEntries: the Bash entry is the merged hook with exactly --guards=commit,secret,install,body,labels',
+  bashEntries[0].command === 'node "/h/trailhead-bash-guards.js" --guards=commit,secret,install,body,labels');
 ok('codexHookEntries: no per-guard script is registered on its own', entries.every((e) =>
   !/trailhead-(commit|secret|install|search|body)-guard\.js/.test(e.command)));
 ok('codexHookEntries: secret-read-guard is PreToolUse/Read|Bash', entries.some((e) =>
@@ -441,6 +441,29 @@ ok('convertToCodex keeps CLAUDE_CODE_SESSION_ID intact',
     autoRef.includes('--auto true --auto-done <n>'));
 }
 
+// #319: l'espansione CLAUDE_CONFIG_DIR diventa CODEX_HOME, mai un ibrido che punta alla config di Claude.
+{
+  const a = convertToCodex('${CLAUDE_CONFIG_DIR:-~/.claude}/trailhead/templates/x');
+  const b = convertToCodex('${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/y');
+  ok('convertToCodex maps the ~ config-dir expansion to CODEX_HOME', a === '${CODEX_HOME:-~/.codex}/trailhead/templates/x');
+  ok('convertToCodex maps the $HOME config-dir expansion to CODEX_HOME', b === '${CODEX_HOME:-$HOME/.codex}/hooks/y');
+  ok('convertToCodex leaves no CLAUDE_CONFIG_DIR behind', !/CLAUDE_CONFIG_DIR/.test(a + b));
+  const c = convertToCodex('config dir = `$CLAUDE_CONFIG_DIR` or `~/.claude`; `${CLAUDE_CONFIG_DIR}/x`');
+  ok('convertToCodex maps the bare config-dir forms to CODEX_HOME',
+    c === 'config dir = `$CODEX_HOME` or `~/.codex`; `${CODEX_HOME}/x`');
+  ok('convertToCodex leaves a longer variable name untouched',
+    convertToCodex('$CLAUDE_CONFIG_DIRX') === '$CLAUDE_CONFIG_DIRX');
+
+  // Ogni .md reale proiettato non deve contenere CLAUDE_CONFIG_DIR.
+  const root = path.join(__dirname, '../../plugins/trailhead');
+  const walk = (d) => fs.readdirSync(d, { withFileTypes: true }).flatMap((e) =>
+    e.isDirectory() ? walk(path.join(d, e.name)) : e.name.endsWith('.md') ? [path.join(d, e.name)] : []);
+  const files = ['skills', 'agents', 'commands'].flatMap((n) => walk(path.join(root, n)));
+  const leaks = files.filter((f) => /CLAUDE_CONFIG_DIR/.test(convertToCodex(fs.readFileSync(f, 'utf8'))));
+  ok('real plugin .md files were found', files.length > 0);
+  ok('no projected plugin .md keeps CLAUDE_CONFIG_DIR: ' + leaks.join(', '), leaks.length === 0);
+}
+
 // #248: the shared boundary blocks survive the Codex projection of every real agent.
 {
   const { parseSource } = require('../../scripts/sync-agent-blocks.js');

package/bin/lib/host-descriptor.js

@@ -65,6 +65,8 @@ const HOSTS = Object.freeze({
     label: 'Claude Code',
     configDirEnv: 'CLAUDE_CONFIG_DIR',
     configDirDefault: '.claude',
+    // Prefisso con cui l'host invoca un verbo trailhead (vedi commandForm).
+    commandPrefix: '/trailhead:',
     axes: Object.freeze({
       commandSurface: 'slash-file',
       subagentToolkit: 'full',
@@ -93,6 +95,7 @@ const HOSTS = Object.freeze({
     label: 'Codex',
     configDirEnv: 'CODEX_HOME',
     configDirDefault: '.codex',
+    commandPrefix: '$trailhead ',
     axes: Object.freeze({
       commandSurface: 'skill',
       subagentToolkit: 'full',
@@ -168,6 +171,15 @@ function hyphenateCommand(name) {
   return String(name).trim().replace(/^\//, '').replace(/:/g, '-');
 }
 
+// --- Helper: commandForm ------------------------------------------------------
+// Forma di invocazione di un verbo per l'host: la scrittura da usare in ogni
+// testo runtime, mai un literal `/trailhead:<verb>` hardcoded.
+//   commandForm('claude', 'update') -> '/trailhead:update'
+//   commandForm('codex', 'update')  -> '$trailhead update'
+function commandForm(host, verb) {
+  return `${resolveHost(host).commandPrefix}${verb}`;
+}
+
 // --- Helper: emitsAgentToml ---------------------------------------------------
 function emitsAgentToml(host) {
   return resolveHost(host).emitsAgentToml;
@@ -275,7 +287,7 @@ function updateNotice(host, cache) {
   const installed = String(cache.installed || '').trim();
   const ver = latest ? ` ${latest}` : '';
   const from = installed ? ` (you have ${installed})` : '';
-  return `Heads up: trailhead${ver} is available${from}. Run /trailhead:update to install it.`;
+  return `Heads up: trailhead${ver} is available${from}. Run ${commandForm(host, 'update')} to install it.`;
 }
 
 // --- Codex version floor gate (decision #27) --------------------------------
@@ -390,6 +402,7 @@ module.exports = {
   getHost,
   configDirFor,
   hyphenateCommand,
+  commandForm,
   emitsAgentToml,
   degradations,
   modelsCollapseNotice,

package/bin/lib/host-descriptor.test.js

@@ -8,6 +8,7 @@ const {
   getHost,
   configDirFor,
   hyphenateCommand,
+  commandForm,
   emitsAgentToml,
   degradations,
   modelsCollapseNotice,
@@ -127,6 +128,23 @@ ok('modelsCollapseNotice: codex namespace with only empty/nullish values does no
   return typeof msg === 'string' && msg.includes('plan') && !msg.includes('codex)');
 })());
 
+// --- commandForm ---
+ok('commandForm(claude, update) is the slash form', commandForm('claude', 'update') === '/trailhead:update');
+ok('commandForm(codex, update) is the dollar form', commandForm('codex', 'update') === '$trailhead update');
+ok('commandForm throws on an unknown host', (() => { try { commandForm('nope', 'x'); return false; } catch { return true; } })());
+
+// Drift guard: la lib degli hook ha la propria copia di commandForm (non puo'
+// richiedere bin/ una volta installata); le due devono restare identiche.
+{
+  const lib = require('../../plugins/trailhead/hooks/lib/model-defaults-review.js');
+  for (const host of ['claude', 'codex']) {
+    for (const verb of ['config', 'update']) {
+      ok(`commandForm drift: hook lib matches host-descriptor (${host}, ${verb})`,
+        lib.commandForm(host, verb) === commandForm(host, verb));
+    }
+  }
+}
+
 // --- updateNotice ---
 // Both hosts now have a hook bus (hookBus !== 'none'), so updateNotice never
 // fires for either: the SessionStart hook + (on Codex) its stdout

package/bin/lib/runtime-command-literals.test.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// Test statico: nessun literal di comando Claude (`/trailhead:<verb>` o `/trailhead`
+// nudo) dentro stringhe/template del codice runtime. Gli hook lib e i template
+// vengono copiati byte-per-byte su Codex e convertToCodex riscrive solo il
+// markdown, quindi un literal qui arriverebbe cosi' com'e' a un utente Codex.
+// Usare commandForm(host, verb) (host-descriptor o helper locale della lib).
+// Run: node runtime-command-literals.test.js. Nessun framework: assert semplici.
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const SCAN_DIRS = [
+  { dir: 'plugins/trailhead/hooks', skip: ['plugins/trailhead/hooks/mod'] },
+  { dir: 'plugins/trailhead/templates', skip: [] },
+  { dir: 'bin', skip: [] },
+];
+
+// Eccezioni motivate: file (relativo alla root) + sottostringa della riga.
+// Niente numeri di riga, cosi' le modifiche attorno non rompono il test.
+const ALLOWLIST = [
+  {
+    file: 'plugins/trailhead/templates/trailhead-dashboard.js',
+    contains: 'Regenerate any time with',
+    reason: 'corpo del dashboard: artefatto condiviso host-neutral scritto nell\'issue, non un messaggio runtime per host',
+  },
+  {
+    file: 'bin/trailhead.js',
+    contains: '(/trailhead:*)',
+    reason: 'banner dell\'installer Claude-only (il ramo Codex stampa il proprio banner)',
+  },
+  {
+    file: 'bin/trailhead.js',
+    contains: 'then run /trailhead to start',
+    reason: 'banner dell\'installer Claude-only',
+  },
+  {
+    file: 'bin/lib/codex-projection.js',
+    contains: 'Never \\`/trailhead:<verb>\\`',
+    reason: 'testo del SKILL.md Codex: nomina la forma Claude proprio per vietarla all\'agente',
+  },
+  {
+    file: 'bin/lib/host-descriptor.js',
+    contains: "commandPrefix: '/trailhead:'",
+    reason: 'dato del descriptor Claude da cui commandForm produce la forma Claude',
+  },
+  {
+    file: 'plugins/trailhead/hooks/lib/model-defaults-review.js',
+    contains: '`/trailhead:${verb}`',
+    reason: 'helper commandForm della lib: l\'unico punto che produce la forma Claude',
+  },
+];
+
+// `/trailhead:` (anche seguito da `${`, `*`, `<verb>` o concatenato) oppure
+// `/trailhead` nudo. Non conta dentro un path: non preceduto da parola, `.`,
+// `~`, `\`, `/`, `-` e non seguito da parola, `:`, `/`, `\`, `-`.
+const COMMAND_RE = /(?<![\w.~\\/-])\/trailhead(?::|(?![\w:/\\-]))/g;
+
+function listJs(dir, skip) {
+  const out = [];
+  for (const e of fs.readdirSync(path.join(ROOT, dir), { withFileTypes: true })) {
+    const rel = `${dir}/${e.name}`;
+    if (e.isDirectory()) {
+      if (e.name === 'node_modules' || skip.includes(rel)) continue;
+      out.push(...listJs(rel, skip));
+    } else if (e.name.endsWith('.js') && !e.name.endsWith('.test.js')) {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+// Scanner minimale a stati sull'intero file: marca i caratteri che stanno
+// dentro stringhe ('...', "...") e template (`...`, anche su piu' righe, con i
+// loro ${...}); commenti e literal regex sono saltati. Non e' un parser JS
+// completo: una regex e' riconosciuta dal carattere significativo precedente.
+const REGEX_PREV = new Set(['', '(', ',', '=', ':', '[', '!', '&', '|', '?', '{', '}', ';', '+', '-', '*', '%', '<', '>', '~', '^']);
+function literalMask(text) {
+  const mask = new Uint8Array(text.length);
+  let i = 0;
+  let prev = '';
+  while (i < text.length) {
+    const c = text[i];
+    const n = text[i + 1];
+    if (c === '/' && n === '/') {
+      while (i < text.length && text[i] !== '\n') i++;
+    } else if (c === '/' && n === '*') {
+      const end = text.indexOf('*/', i + 2);
+      i = end === -1 ? text.length : end + 2;
+    } else if (c === '"' || c === "'" || c === '`') {
+      mask[i] = 1;
+      i++;
+      while (i < text.length && text[i] !== c) {
+        if (text[i] === '\\') { mask[i] = 1; i++; }
+        if (c !== '`' && text[i] === '\n') break;
+        mask[i] = 1;
+        i++;
+      }
+      if (i < text.length) mask[i] = 1;
+      i++;
+      prev = c;
+    } else if (c === '/' && (REGEX_PREV.has(prev) || prev === 'return')) {
+      i++;
+      let inClass = false;
+      while (i < text.length && text[i] !== '\n' && (inClass || text[i] !== '/')) {
+        if (text[i] === '\\') i++;
+        else if (text[i] === '[') inClass = true;
+        else if (text[i] === ']') inClass = false;
+        i++;
+      }
+      i++;
+      prev = ')';
+    } else {
+      if (!/\s/.test(c)) {
+        const word = /[A-Za-z_$]/.test(c) ? text.slice(i).match(/^[\w$]+/)[0] : c;
+        prev = word === 'return' ? 'return' : word.length > 1 ? 'a' : c;
+        i += word.length;
+        continue;
+      }
+      i++;
+    }
+  }
+  return mask;
+}
+
+const used = new Set();
+
+function findViolations(rel, text) {
+  const out = [];
+  const mask = literalMask(text);
+  const lines = text.split('\n');
+  const starts = [];
+  let off = 0;
+  for (const l of lines) { starts.push(off); off += l.length + 1; }
+  for (const m of text.matchAll(COMMAND_RE)) {
+    if (!mask[m.index]) continue;
+    let ln = starts.findIndex((st, k) => k === starts.length - 1 || starts[k + 1] > m.index);
+    const line = lines[ln];
+    const idx = ALLOWLIST.findIndex((a) => a.file === rel && line.includes(a.contains));
+    if (idx >= 0) { used.add(idx); continue; }
+    out.push(`${rel}:${ln + 1}: ${line.trim()}`);
+  }
+  return out;
+}
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// Sanity del rilevatore: deve fermare il literal originale e ignorare i path.
+ok('detector flags the original review-offer literal',
+  findViolations('x.js', "  '3) open /trailhead:config to pick per key.',").length === 1);
+ok('detector flags a bare /trailhead in a literal',
+  findViolations('x.js', "console.log('run /trailhead to start');").length === 1);
+ok('detector ignores comment lines', findViolations('x.js', '// run /trailhead:update').length === 0);
+ok('detector ignores path segments',
+  findViolations('x.js', "path.join('skills/trailhead/hooks', 'refs/heads/trailhead/t1')").length === 0);
+ok('detector flags a concatenated literal', findViolations('x.js', "const c = '/trailhead:' + v;").length === 1);
+ok('detector flags a template literal with interpolation', findViolations('x.js', 'const c = `/trailhead:${v}`;').length === 1);
+ok('detector flags a literal on a later line of a multi-line template',
+  findViolations('x.js', 'const t = `first line\nrun /trailhead:config now`;').length === 1);
+ok('detector flags the glob and placeholder forms',
+  findViolations('x.js', "a('/trailhead:*'); b('/trailhead:<verb>');").length === 2);
+ok('detector ignores a regex literal with an escaped slash',
+  findViolations('x.js', "const R = /^refs\\/heads\\/trailhead\\/t(\\d+)$/; const q = /['\"]/;").length === 0);
+ok('detector ignores the host-neutral helper form',
+  findViolations('x.js', 'const c = commandForm(host, "config");').length === 0);
+
+// Le eccezioni in allowlist devono ancora corrispondere a qualcosa.
+for (const a of ALLOWLIST) {
+  ok(`allowlist file exists: ${a.file}`, fs.existsSync(path.join(ROOT, a.file)));
+  ok(`allowlist reason given: ${a.file}`, a.reason.length > 0);
+}
+
+const files = SCAN_DIRS.flatMap(({ dir, skip }) => listJs(dir, skip));
+ok('scan covers hook libs, templates and bin', files.length > 20);
+const violations = files.flatMap((rel) => findViolations(rel, fs.readFileSync(path.join(ROOT, rel), 'utf8')));
+assert.deepStrictEqual(violations, [],
+  `literal di comando Claude in codice runtime (usa commandForm):\n${violations.join('\n')}`);
+passed++;
+const unused = ALLOWLIST.filter((_, i) => !used.has(i)).map((a) => `${a.file}: ${a.contains}`);
+assert.deepStrictEqual(unused, [], `voci di allowlist mai usate (da rimuovere):\n${unused.join('\n')}`);
+passed++;
+
+console.log(`runtime-command-literals.test.js: ${passed} assertions passed`);

package/bin/needs-you-docs.test.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Docs test for #282: the needs-you label (an autonomous run parks a ticket for the
+// human) is documented where the run, the claim and the substrate depend on it.
+// Plain asserts, no framework. Run: node bin/needs-you-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const plugin = path.resolve(__dirname, '..', 'plugins', 'trailhead');
+const read = (rel) => fs.readFileSync(path.join(plugin, rel), 'utf8');
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const auto = read('skills/trailhead-work/references/auto.md');
+const work = read('skills/trailhead-work/SKILL.md');
+const substrate = read('skills/_shared/substrate.md');
+const commands = read('skills/_shared/substrate-commands.md');
+
+for (const needle of ['trailhead:needs-you', 'trailhead-needs-you.js park', '`NEEDS YOU`', 'needs-you ticket', 'queue skips it', 'does not reconsider it', 'surviving blocking review concern', 'stale-base stop', 'a failing UAT setup'.replace('a failing', 'failing')]) {
+  ok(`auto.md names: ${needle}`, auto.includes(needle));
+}
+ok('auto.md no longer says "set aside" / "set-aside"', !/set[- ]aside|sets? (?:it|that|such a|the) (?:ticket )?aside|sets? .{0,20} aside/i.test(auto));
+
+const claimStep = (work.match(/^2\. Choose the ticket\..*$/m) || [''])[0];
+const quickBullet = (work.match(/^- \*\*Same isolation setup as `work`\.\*\*.*$/m) || [''])[0];
+const CLEAR = 'node <templates>/trailhead-needs-you.js clear --issue <n> --repo <owner/name>';
+ok('work claim step clears needs-you with the helper', claimStep.includes(CLEAR));
+ok('quick isolation bullet clears needs-you with the helper', quickBullet.includes(CLEAR));
+ok('work claim step has the by-hand fallback', claimStep.includes('gh issue edit <n> --remove-label trailhead:needs-you'));
+ok('a failed clear is reported, never blocking the claim (work)', /failed `clear` is reported to the user in one line but never blocks the claim/.test(claimStep));
+ok('a failed clear is reported, never blocking the claim (quick)', /failed `clear` is reported to the user in one line but never blocks the claim/.test(quickBullet));
+
+ok('substrate.md documents the label, off every run, on the human frontier', /\*\*`trailhead:needs-you`\*\*[\s\S]{0,900}not a frontier exclusion for humans/.test(substrate) && substrate.includes('twenty-one labels'));
+ok('substrate-commands.md ensures the label idempotently', commands.includes('gh label create trailhead:needs-you --color D93F0B --description "Needs you: an autonomous run parked it for the human" --force'));
+ok('substrate-commands.md documents park and clear', commands.includes('trailhead-needs-you.js park --issue <n> --reason <text> --repo <owner/name>') && commands.includes('trailhead-needs-you.js clear --issue <n> --repo <owner/name>'));
+ok('substrate-commands.md first-use list has twenty-one labels', /all twenty-one:[^\n]*`trailhead:needs-you`/.test(commands));
+
+for (const [name, text] of [['auto.md', auto], ['SKILL.md', work], ['substrate.md', substrate], ['substrate-commands.md', commands]]) {
+  ok(`${name}: no em-dash`, !text.includes(String.fromCharCode(0x2014)));
+}
+console.log(`needs-you-docs.test.js: ${passed} checks passed`);

package/bin/pick-stress-test-docs.test.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// Docs test: the agent never offers or acts on its own pick unchecked. The stress-test rule is
+// stated once (choices.md) and pointed at by grilling, the delegate option, auto and the Plan;
+// the Plan carries a Done-when coverage check, decision Diverge re-checks a framed option set,
+// and inbox never closes or answers someone else's issue without the user's yes.
+// Run: node pick-stress-test-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const skills = path.join(__dirname, '..', 'plugins', 'trailhead', 'skills');
+const read = (rel) => fs.readFileSync(path.join(skills, rel), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const ANCHOR = 'Stress-test the pick before offering it';
+const DEFINITION = `**${ANCHOR}.**`;
+
+const walk = (dir) => fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+  e.isDirectory() ? walk(path.join(dir, e.name)) : [path.join(dir, e.name)]);
+const lineOf = (text, pred) => text.split('\n').find(pred);
+
+// 1. la definizione esiste una sola volta, in choices.md
+const defs = walk(skills).filter((f) => fs.readFileSync(f, 'utf8').includes(DEFINITION));
+ok('definition appears in exactly one file', defs.length === 1);
+ok('definition lives in choices.md', defs[0] === path.join(skills, '_shared', 'choices.md'));
+const choices = read('_shared/choices.md');
+ok('definition appears once', choices.split(DEFINITION).length === 2);
+
+// 2. la definizione porta i frammenti normativi
+const rule = lineOf(choices, (l) => l.includes(DEFINITION));
+for (const frag of [
+  'a recommended answer in grilling',
+  '`(Recommended)`',
+  'the delegate option',
+  'an option `auto` takes on its own',
+  'the edge case or failure mode where it breaks',
+  'checked against the code rather than assumed',
+  'the choices already settled',
+  'real holes, not manufactured doubt',
+  'One pass, no loop',
+  'present only that',
+  'Weak point:',
+  'still recommended because',
+  'conversation language',
+  'where no human sees it live',
+  'trivial or already-decided choice',
+]) ok(`rule carries: ${frag}`, rule.includes(frag));
+
+// 3. i call-site puntano alla regola senza ripeterla
+const pointer = (name, line) => {
+  ok(`${name} found`, !!line);
+  ok(`${name} references the anchor`, line.includes(ANCHOR));
+  ok(`${name} does not restate the rule`, !line.includes('manufactured doubt'));
+};
+const grilling = read('_shared/techniques/grilling.md');
+const gl = grilling.split('\n');
+const pickIdx = gl.findIndex((l) => l.startsWith('- **One question at a time, with your pick.**'));
+ok('grilling pick bullet found', pickIdx >= 0);
+pointer('grilling self-check bullet', gl[pickIdx + 1]);
+ok('grilling bullet keeps the per-question check', gl[pickIdx + 1].includes('by question number'));
+ok('grilling pick bullet points at the self-check', gl[pickIdx].includes('stress-tested per the next bullet'));
+pointer('delegate step 2', lineOf(choices, (l) => l.startsWith('2. The agent states **which option it would choose')));
+const auto = read('trailhead-work/references/auto.md');
+const autoLine = lineOf(auto, (l) => l.startsWith('- **Advisory / process choice**'));
+pointer('auto advisory choice', autoLine);
+ok('auto records the weak point', autoLine.includes('`Weak point:` line'));
+const engines = read('trailhead-work/references/ticket-engines.md');
+const plan = lineOf(engines, (l) => l.startsWith('2. **Plan**'));
+pointer('build Plan', plan);
+
+// 4. Plan: copertura del Done when prima di ready
+for (const frag of [
+  '**Coverage check before `ready`.**',
+  'every `Done when` criterion',
+  'a criterion no step delivers is a gap',
+  'return `needs_input`',
+  'the short inline plan too',
+]) ok(`plan carries: ${frag}`, plan.includes(frag));
+
+// 5. Diverge: un set di opzioni gia' inquadrato viene ricontrollato
+const diverge = lineOf(engines, (l) => l.startsWith('1. **Diverge'));
+ok('diverge found', !!diverge);
+ok('diverge no longer skips blindly', !diverge.includes('skip straight to grilling when it did.'));
+for (const frag of ['still current and complete', 'Decisions so far', 'status quo', '`OPTIONS` comment'])
+  ok(`diverge carries: ${frag}`, diverge.includes(frag));
+
+// 6. Inbox: nessuna chiusura o commento pubblico senza un si'
+const inbox = read('trailhead-chart/references/inbox.md');
+ok('inbox drops "on your own for clear ones"', !inbox.includes('on your own for clear ones'));
+const intro = lineOf(inbox, (l) => l.startsWith('For each issue in the first two sections'));
+for (const frag of ['propose a disposition', 'one list', 'explicit yes', 'never close', 'comment on', 'out-of-scope ruling'])
+  ok(`inbox intro carries: ${frag}`, intro.includes(frag));
+const dup = lineOf(inbox, (l) => l.startsWith('- **Duplicate.**'));
+for (const frag of ['what each one covers', 'partial overlap', 'not a duplicate'])
+  ok(`inbox duplicate carries: ${frag}`, dup.includes(frag));
+
+// 7. niente em-dash
+for (const rel of ['_shared/choices.md', '_shared/techniques/grilling.md', 'trailhead-work/references/auto.md',
+  'trailhead-work/references/ticket-engines.md', 'trailhead-chart/references/inbox.md'])
+  ok(`${rel} has no em-dash`, !read(rel).includes(String.fromCharCode(8212)));
+ok('this test has no em-dash', !fs.readFileSync(__filename, 'utf8').includes(String.fromCharCode(8212)));
+
+console.log(`pick-stress-test-docs.test.js: ${passed} checks passed`);

package/bin/report-status-docs.test.js

@@ -48,7 +48,7 @@ ok('the checker command with its technique flag and a report file',
 ok('the three templates dirs, in order',
   (() => {
     const a = para.indexOf('${CLAUDE_PLUGIN_ROOT}/templates/');
-    const b = para.indexOf('~/.claude/trailhead/templates/');
+    const b = para.indexOf('${CLAUDE_CONFIG_DIR:-~/.claude}/trailhead/templates/');
     const c = para.indexOf('~/.codex/skills/trailhead/templates/');
     return a !== -1 && b > a && c > b;
   })());

package/bin/trailhead.js

@@ -243,10 +243,10 @@ function claudePaths(configDir) {
     settings: path.join(configDir, 'settings.json'),
   };
 }
-// The five Bash guard modules. They are shipped, but only require()d by the
+// The six Bash guard modules. They are shipped, but only require()d by the
 // merged trailhead-bash-guards.js (one process per Bash call), never registered
 // on their own. Legacy installs registered each one; the installers strip those.
-const BASH_GUARD_MODULES = ['trailhead-commit-guard.js', 'trailhead-secret-guard.js', 'trailhead-install-guard.js', 'trailhead-search-guard.js', 'trailhead-body-guard.js'];
+const BASH_GUARD_MODULES = ['trailhead-commit-guard.js', 'trailhead-secret-guard.js', 'trailhead-install-guard.js', 'trailhead-search-guard.js', 'trailhead-body-guard.js', 'trailhead-labels-guard.js'];
 // Every hook script copied into the hooks dir (shipped runtime files).
 const HOOK_FILES = [...BASH_GUARD_MODULES, 'trailhead-bash-guards.js', 'trailhead-issue-injection-scanner.js', 'trailhead-secret-read-guard.js', 'trailhead-mockup-link-guard.js', 'trailhead-mockup-link-stop.js', 'trailhead-check-update.js'];
 // The registered entrypoints: the shipped files that must appear in
@@ -436,7 +436,7 @@ function installClaude(configDir, { useSymlink }) {
 
   const s = readJSON(P.settings);
   // Migration: an earlier install registered each Bash guard on its own; the
-  // merged entrypoint below replaces all five.
+  // merged entrypoint below replaces all six.
   stripLegacyBashGuards(s);
   const added = [
     addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-bash-guards.js')),

package/bin/trailhead.test.js

@@ -757,12 +757,12 @@ ok('source: both Pending-UAT guard lines reference the drive-mode ask', pendingU
 // auto.md mentions the ask, AND (plan-review addition) a single localized span
 // states its outcomes TOGETHER: takes it without the confirm gate, picks
 // AI-driven when any step is agent-performable, never fakes a human-only step,
-// and sets the ticket aside listing them in the run-end summary.
+// and routes the human-only steps to a follow-up opened before the parent closes (#281).
 const autoSourcePath = path.join(sourceSkillsDir, 'trailhead-work', 'references', 'auto.md');
 const autoSource = fs.readFileSync(autoSourcePath, 'utf8');
 ok('source: auto.md mentions the drive-mode ask', autoSource.includes('drive-mode ask'));
 ok('source: auto.md states the drive-mode-ask outcomes together (grouped, not scattered)',
-  /drive-mode ask[\s\S]{0,120}without the confirm gate[\s\S]{0,300}AI-driven[\s\S]{0,200}agent-performable[\s\S]{0,300}never fake[\s\S]{0,300}run-end summary/.test(autoSource));
+  /drive-mode ask[\s\S]{0,120}without the confirm gate[\s\S]{0,300}AI-driven[\s\S]{0,200}agent-performable[\s\S]{0,300}never fakes[\s\S]{0,1500}follow-up/.test(autoSource));
 
 // choices.md carries the call-site row for the drive-mode ask.
 const choicesSourcePath = path.join(sourceSkillsDir, '_shared', 'choices.md');
@@ -816,13 +816,12 @@ ok('source: configuration-reference.md acceptance.browser clause does NOT make t
 ok('source: configuration-reference.md acceptance.browser clause states the drive-mode ask always comes first',
   /\*\*acceptance\.browser\.\*\*[\s\S]{0,200}drive-mode ask[\s\S]{0,120}always comes first/.test(configReferenceSource));
 
-// The run-end summary's enumerated set-aside category list is missing the new
-// human-only-UAT-steps class (added by #178); it must be listed there too,
-// matching the wording already used for it at line 29 ("human-only steps").
+// Human-only UAT steps are no longer a set-aside reason (#281): the run-end summary
+// lists the UAT follow-ups opened this run instead.
 const runEndSummarySection = extractSection(autoSource, '## Run-end summary');
 ok('source: auto.md Run-end summary section exists', runEndSummarySection.length > 0);
-ok('source: auto.md Run-end summary "what remains" list includes human-only UAT steps',
-  /what remains[\s\S]{0,400}human-only UAT steps/.test(runEndSummarySection));
+ok('source: auto.md Run-end summary "what remains" lists the UAT follow-ups opened this run',
+  /what remains[\s\S]{0,900}UAT follow-ups opened this run/.test(runEndSummarySection));
 
 // --- #254: skip option at the drive-mode ask (a waiver, not a deferral) -----
 // The waiver's operational contract is single-sourced in the Drive-mode bullet
@@ -892,7 +891,7 @@ ok('README.md no-performable-step case asks human-driven or skip', /human-driven
 ok('README.md point 6 allows an explicit waiver', /never closes on a UAT nobody ran unless you explicitly waive it/.test(readmeSource));
 const siteAcceptanceSource = fs.readFileSync(path.join(repoRoot, 'site', 'src', 'content', 'docs', 'docs', 'acceptance-testing.md'), 'utf8');
 ok('docs: auto never-picks-skip antecedent is the auto run, in all three docs',
-  /listed in the run's summary; `\/trailhead:auto` never picks skip/.test(readmeSource) && /listed in the run's summary; `\/trailhead:auto` never picks skip/.test(siteAcceptanceSource) && /elencato nel riepilogo della run; `\/trailhead:auto` non sceglie mai skip/.test(readmeItSource));
+  /the parent ticket resolves; `\/trailhead:auto` never picks skip/.test(readmeSource) && /the parent ticket resolves; `\/trailhead:auto` never picks skip/.test(siteAcceptanceSource) && /il ticket genitore si risolve; `\/trailhead:auto` non sceglie mai skip/.test(readmeItSource));
 ok('README.md build row and acceptance.browser row name skip',
   /🔨 `build`[\s\S]{0,500}or skip/.test(readmeSource) && /`acceptance\.browser`[\s\S]{0,300}or skip/.test(readmeSource));
 ok('README.it.md acceptance testing section names the waiver (skip) recorded as unconfirmed',
@@ -913,10 +912,10 @@ ok('codex: hooks.json exists', fs.existsSync(codexHooksJsonPath));
 const codexHooksJson = JSON.parse(fs.readFileSync(codexHooksJsonPath, 'utf8'));
 const codexHooksJsonStr = JSON.stringify(codexHooksJson);
 ok('codex: hooks.json registers the merged Bash guards under PreToolUse', (codexHooksJson.hooks.PreToolUse || []).some((g) => g.matcher === 'Bash' &&
-  (g.hooks || []).some((h) => h.command.includes('trailhead-bash-guards.js') && h.command.endsWith(' --guards=commit,secret,install,body'))));
-ok('codex: hooks.json registers none of the per-guard scripts on their own', !/trailhead-(commit|secret|install|search|body)-guard\.js/.test(codexHooksJsonStr));
-ok('codex: the five guard modules the merged hook requires are still shipped (no search)',
-  ['commit', 'secret', 'install', 'body'].every((n) => fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', `trailhead-${n}-guard.js`))) &&
+  (g.hooks || []).some((h) => h.command.includes('trailhead-bash-guards.js') && h.command.endsWith(' --guards=commit,secret,install,body,labels'))));
+ok('codex: hooks.json registers none of the per-guard scripts on their own', !/trailhead-(commit|secret|install|search|body|labels)-guard\.js/.test(codexHooksJsonStr));
+ok('codex: the six guard modules the merged hook requires are still shipped (no search)',
+  ['commit', 'secret', 'install', 'body', 'labels'].every((n) => fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', `trailhead-${n}-guard.js`))) &&
   fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'trailhead-bash-guards.js')));
 ok('codex: hooks.json registers injection-scanner under PostToolUse', (codexHooksJson.hooks.PostToolUse || []).some((g) => (g.hooks || []).some((h) => h.command.includes('trailhead-issue-injection-scanner.js'))));
 ok('codex: hooks.json registers check-update under SessionStart', (codexHooksJson.hooks.SessionStart || []).some((g) => (g.hooks || []).some((h) => h.command.includes('trailhead-check-update.js'))));
@@ -1089,7 +1088,7 @@ ok('codex uninstall: cluster trailhead-view gone', !fs.existsSync(path.join(code
 ok('codex uninstall: hooks.json no longer contains trailhead commands', (() => {
   const h = JSON.parse(fs.readFileSync(codexHooksJsonPath, 'utf8'));
   const str = JSON.stringify(h);
-  return !str.includes('trailhead-bash-guards.js') && !/trailhead-(commit|secret|install|search|body)-guard\.js/.test(str) &&
+  return !str.includes('trailhead-bash-guards.js') && !/trailhead-(commit|secret|install|search|body|labels)-guard\.js/.test(str) &&
     !str.includes('trailhead-issue-injection-scanner.js') && !str.includes('trailhead-check-update.js');
 })());
 
@@ -1305,12 +1304,12 @@ ok('claude: settings.json exists', fs.existsSync(settingsPath));
 const settingsContent = fs.readFileSync(settingsPath, 'utf8');
 ok('claude: settings.json registers the merged Bash guards', settingsContent.includes('trailhead-bash-guards.js'));
 ok('claude: settings.json registers none of the per-guard scripts on their own',
-  !/trailhead-(commit|secret|install|search|body)-guard\.js/.test(settingsContent));
+  !/trailhead-(commit|secret|install|search|body|labels)-guard\.js/.test(settingsContent));
 ok('claude: exactly one PreToolUse/Bash trailhead-bash-guards registration', (() => {
   const s = JSON.parse(settingsContent);
   return (s.hooks.PreToolUse || []).flatMap((g) => g.hooks || []).filter((h) => h.command.includes('trailhead-bash-guards.js')).length === 1;
 })());
-ok('claude: hooks/trailhead-bash-guards.js and its five modules exist', ['bash-guards', 'commit-guard', 'secret-guard', 'install-guard', 'search-guard', 'body-guard']
+ok('claude: hooks/trailhead-bash-guards.js and its six modules exist', ['bash-guards', 'commit-guard', 'secret-guard', 'install-guard', 'search-guard', 'body-guard', 'labels-guard']
   .every((n) => fs.existsSync(path.join(claudeDir, 'hooks', `trailhead-${n}.js`))));
 // mockup-link-guard: Claude-only PreToolUse(AskUserQuestion) backstop for the
 // Prototype "link in the same message as the approval ask" rule.
@@ -1691,7 +1690,7 @@ const bashGuardCommands = (registry) => (registry.hooks.PreToolUse || [])
   ok('(#207) codex migration: exit 0', out.status === 0);
   const cmds = bashGuardCommands(JSON.parse(fs.readFileSync(hooksJsonFile, 'utf8')));
   ok('(#207) codex migration: only the merged entry remains', cmds.length === 1 &&
-    cmds[0].endsWith(' --guards=commit,secret,install,body'));
+    cmds[0].endsWith(' --guards=commit,secret,install,body,labels'));
   const once = fs.readFileSync(hooksJsonFile, 'utf8');
   runInstaller([`--codex`, `--dir=${mDir}`]);
   ok('(#207) codex install twice leaves the same hooks.json', fs.readFileSync(hooksJsonFile, 'utf8') === once);
@@ -2068,8 +2067,8 @@ ok('source: hooks.json keeps its command hooks next to the module (#202)',
 
 // --- #259: `trailhead:paused` label marks a paused ticket (pause adds, resume/claim drop) ---
 const firstUseLine = (substrateCommandsSource.match(/^1\. Create any missing labels.*$/m) || [''])[0];
-ok('source: first-use setup lists twenty labels including trailhead:paused and trailhead:uat',
-  /all twenty:/.test(firstUseLine) && firstUseLine.includes('`trailhead:paused`') && firstUseLine.includes('`trailhead:uat`'));
+ok('source: first-use setup lists twenty-one labels including trailhead:paused, trailhead:uat and trailhead:needs-you',
+  /all twenty-one:/.test(firstUseLine) && firstUseLine.includes('`trailhead:paused`') && firstUseLine.includes('`trailhead:uat`') && firstUseLine.includes('`trailhead:needs-you`'));
 ok('source: no stale "eighteen" or "nineteen" label count remains in the shared skills',
   !/eighteen|nineteen/.test(substrateCommandsSource) && !/eighteen|nineteen/.test(substrateSource));
 ok('source: substrate-commands.md ensures trailhead:paused idempotently',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcomigozzi/trailhead",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Start and drive large projects as a map of tickets on GitHub Issues. Map-based onboarding + a discuss→plan→execute→verify engine, all on the Issues. Installs the trailhead skill, commands, and hooks into your agent's config dir.",
   "bin": {
     "trailhead": "bin/trailhead.js"

package/plugins/trailhead/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trailhead",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Start and drive large projects as a map of tickets on GitHub Issues, resolving one at a time. Map-based onboarding + a discuss→plan→execute→verify engine with atomic commits, all on the Issues. Ships as a dispatcher plus cohesion-clustered skills over a shared core; depends on nothing beyond an authenticated gh CLI.",
   "author": {
     "name": "Marco Migozzi",

package/plugins/trailhead/agents/trailhead-code-review.md

@@ -19,7 +19,7 @@ Never `cd` (or `pushd`/`env -C`) into a directory first; the full rule is in `_s
 <!-- trailhead:agent-block reviewing -->
 **Return contract.** Return the complete report as your final message. Do not post it anywhere (no issue comment, no PR comment): the orchestrator posts the `VERIFY` comment after it checks the status line.
 - The first line of the report is the technique's `status:` line, verbatim: `status: <token>`, with nothing before it and no other `status:` line.
-- trailhead-verify: `<token>` is one of `met` | `gaps_found` | `inconclusive`.
-- trailhead-code-review: `<token>` is one of `clean` | `issues_found`, and line 2 is the counts line `critical: <n> · warning: <n> · info: <n>`.
+- trailhead-verify: `<token>` is one of `met` | `gaps_found` | `inconclusive`; each claim line carries `class: <met|unmet|partial|inconclusive>`, and `met` lists no `unmet`, `partial` or `inconclusive` claim.
+- trailhead-code-review: `<token>` is one of `clean` | `issues_found`, and line 2 is the counts line `critical: <n> · warning: <n> · info: <n>`; `clean` with a non-zero `critical` count requires a ledger line closing every Critical (`fixed`, `deferred` or `accepted`), none `open`.
 - Read-only: never Edit/Write, never commit.
 <!-- /trailhead:agent-block reviewing -->