@marcomigozzi/trailhead 0.8.1 → 0.10.0

package/bin/trailhead.js

@@ -213,14 +213,15 @@ function claudePaths(configDir) {
     settings: path.join(configDir, 'settings.json'),
   };
 }
-const HOOK_FILES = ['trailhead-commit-guard.js', 'trailhead-issue-injection-scanner.js', 'trailhead-secret-guard.js', 'trailhead-install-guard.js', 'trailhead-search-guard.js', 'trailhead-secret-read-guard.js', 'trailhead-check-update.js'];
+const HOOK_FILES = ['trailhead-commit-guard.js', 'trailhead-issue-injection-scanner.js', 'trailhead-secret-guard.js', 'trailhead-install-guard.js', 'trailhead-search-guard.js', 'trailhead-secret-read-guard.js', 'trailhead-body-guard.js', 'trailhead-check-update.js'];
 // Runtime libs the hook scripts require (trailhead-commit-guard.js does
 // require('./lib/commit-message-check.js'); trailhead-search-guard.js and
 // trailhead-secret-read-guard.js both do require('./lib/shell-scan.js'), #135
-// follow-up). Copied by name, never a recursive sweep: the Claude hooks/lib
-// dir is shared with other plugins, so we must not clobber a co-tenant's lib
-// nor ship our own *.test.js files.
-const HOOK_LIB_FILES = ['commit-message-check.js', 'shell-scan.js'];
+// follow-up; trailhead-body-guard.js and trailhead-secret-guard.js both do
+// require('./lib/gh-subcommand.js'), #153 follow-up). Copied by name, never a
+// recursive sweep: the Claude hooks/lib dir is shared with other plugins, so
+// we must not clobber a co-tenant's lib nor ship our own *.test.js files.
+const HOOK_LIB_FILES = ['commit-message-check.js', 'shell-scan.js', 'gh-subcommand.js'];
 
 // Copy the hook scripts and their runtime libs into a destination hooks dir
 // (Claude's ~/.claude/hooks or Codex's skills/trailhead/hooks). Shared by both
@@ -231,7 +232,7 @@ const HOOK_LIB_FILES = ['commit-message-check.js', 'shell-scan.js'];
 // live too, matching skills/commands. Never symlink the whole hooks/ dir: it is
 // shared with other plugins, so only the curated allowlist is touched. rmrf the
 // dest first so a reinstall over an existing file or symlink never hits EEXIST.
-function copyHookScripts(destHooksDir, { useSymlink = false } = {}) {
+function copyHookScripts(destHooksDir, { useSymlink = false, exclude = [] } = {}) {
   ensure(destHooksDir);
   const put = (src, dest) => {
     rmrf(dest);
@@ -242,7 +243,7 @@ function copyHookScripts(destHooksDir, { useSymlink = false } = {}) {
       fs.chmodSync(dest, 0o755);
     }
   };
-  for (const f of HOOK_FILES) put(path.join(SRC, 'hooks', f), path.join(destHooksDir, f));
+  for (const f of HOOK_FILES.filter((f) => !exclude.includes(f))) put(path.join(SRC, 'hooks', f), path.join(destHooksDir, f));
   if (HOOK_LIB_FILES.length) {
     const libDest = path.join(destHooksDir, 'lib');
     ensure(libDest);
@@ -329,6 +330,7 @@ function uninstallClaude(configDir) {
   stripHook(s, 'PreToolUse', 'trailhead-install-guard.js');
   stripHook(s, 'PreToolUse', 'trailhead-search-guard.js');
   stripHook(s, 'PreToolUse', 'trailhead-secret-read-guard.js');
+  stripHook(s, 'PreToolUse', 'trailhead-body-guard.js');
   stripHook(s, 'PostToolUse', 'trailhead-issue-injection-scanner.js');
   stripHook(s, 'SessionStart', 'trailhead-check-update.js');
   writeJSON(P.settings, s);
@@ -375,6 +377,7 @@ function installClaude(configDir, { useSymlink }) {
     addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-secret-guard.js')),
     addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-install-guard.js')),
     addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-search-guard.js')),
+    addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-body-guard.js')),
     addHook(s, 'PreToolUse', 'Read|Bash', hookCmd('trailhead-secret-read-guard.js')),
     addHook(s, 'PostToolUse', 'Bash', hookCmd('trailhead-issue-injection-scanner.js')),
     addHook(s, 'SessionStart', '', hookCmd('trailhead-check-update.js')),
@@ -572,9 +575,12 @@ function installCodex(configDir, { useSymlink }) {
   const pkgVersion = (readJSON(path.join(SRC, '.claude-plugin', 'plugin.json')).version || '').trim();
   if (pkgVersion) fs.writeFileSync(L.versionFile, pkgVersion + '\n');
 
-  // Hooks: copy the 4 guard scripts into the skill dir and register them in
-  // ~/.codex/hooks.json (same shape as Claude's settings.json hooks block).
-  copyHookScripts(L.hooksScriptsDir, { useSymlink });
+  // Hooks: copy the guard scripts this host actually uses into the skill dir
+  // and register them in ~/.codex/hooks.json (same shape as Claude's
+  // settings.json hooks block). search-guard is excluded: it is
+  // Claude-Code-specific (see codexHookEntries), so it is neither copied nor
+  // registered here.
+  copyHookScripts(L.hooksScriptsDir, { useSymlink, exclude: ['trailhead-search-guard.js'] });
   const h = readJSON(L.hooksJson);
   for (const e of codexHookEntries(L.hooksScriptsDir)) addHook(h, e.event, e.matcher, e.command);
   writeJSON(L.hooksJson, h);
@@ -679,8 +685,13 @@ function uninstallCodex(configDir) {
     stripHook(h, 'PreToolUse', 'trailhead-commit-guard.js');
     stripHook(h, 'PreToolUse', 'trailhead-secret-guard.js');
     stripHook(h, 'PreToolUse', 'trailhead-install-guard.js');
+    // search-guard is no longer projected to Codex (#169: it is
+    // Claude-Code-specific), so it is never registered by a current install;
+    // this strip is retained only to clean up a stale entry left by a
+    // pre-#169 install that did register it.
     stripHook(h, 'PreToolUse', 'trailhead-search-guard.js');
     stripHook(h, 'PreToolUse', 'trailhead-secret-read-guard.js');
+    stripHook(h, 'PreToolUse', 'trailhead-body-guard.js');
     stripHook(h, 'PostToolUse', 'trailhead-issue-injection-scanner.js');
     stripHook(h, 'SessionStart', 'trailhead-check-update.js');
     writeJSON(L.hooksJson, h);

package/bin/trailhead.test.js

@@ -134,6 +134,315 @@ for (const cl of ['trailhead', 'trailhead-chart', 'trailhead-work', 'trailhead-v
   ok(`source: ${cl}/SKILL.md does NOT duplicate the core-list signature line`, !fs.readFileSync(path.join(sourceSkillsDir, cl, 'SKILL.md'), 'utf8').includes(loadFirstSignature));
 }
 
+// --- #146: single-sourced ticket-language directive (anti-drift) -------------
+// The standing ticket-language rule (write Issue prose + commit bodies in
+// config.ticket.language, decoupled from the chat language) lives in ONE place,
+// _shared/ticket-language.md; it is listed in the load contract's six-file core
+// and REFERENCED (never restated) by the engine references. Mirrors the #139
+// load-first invariant so the directive can't silently drift.
+ok('codex: _shared/ticket-language.md projected', fs.existsSync(path.join(codexDir, 'skills', '_shared', 'ticket-language.md')));
+for (const cl of ['trailhead', 'trailhead-chart', 'trailhead-work', 'trailhead-view', 'trailhead-capture', 'trailhead-manage']) {
+  ok(`codex: ${cl}/../_shared/ticket-language.md resolves as a sibling`, fs.existsSync(path.join(codexDir, 'skills', cl, '..', '_shared', 'ticket-language.md')));
+}
+// The single source states the rule's substance: the canonical config key AND
+// the decoupling clause (the heart of the rule), not merely a heading.
+const ticketLangSourcePath = path.join(sourceSkillsDir, '_shared', 'ticket-language.md');
+const ticketLangSource = fs.readFileSync(ticketLangSourcePath, 'utf8');
+const ticketLangKey = '`config.ticket.language`';
+const ticketLangDecoupling = '**independent of the language the agent converses in**';
+ok('source: ticket-language.md states the rule (config.ticket.language + decoupling clause)',
+  ticketLangSource.includes(ticketLangKey) && ticketLangSource.includes(ticketLangDecoupling));
+// The load contract lists it in the six-file core (item 2), by path reference.
+const loadFirstSource = fs.readFileSync(loadFirstSourcePath, 'utf8');
+ok('source: load-first.md references ../_shared/ticket-language.md', loadFirstSource.includes('../_shared/ticket-language.md'));
+// The engine references point AT the single source (path reference), not restate it.
+const ticketLangAutoSource = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-work', 'references', 'auto.md'), 'utf8');
+const ticketLangCaptureSource = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-capture', 'references', 'capture.md'), 'utf8');
+ok('source: auto.md references ticket-language.md', ticketLangAutoSource.includes('ticket-language.md'));
+ok('source: capture.md references ticket-language.md', ticketLangCaptureSource.includes('ticket-language.md'));
+// Source-level anti-drift: the substantive decoupling clause lives in EXACTLY
+// one file across the whole skills tree, _shared/ticket-language.md. A global
+// single-occurrence scan (not an enumerated per-file list) so any future doc
+// that restates the verbatim directive is caught, including reachable
+// shared-core references beyond the load contract and the two engine references
+// (e.g. configuration-reference.md, choices.md). The legitimate paraphrases in
+// configuration-reference.md/capture.md reword the rule and do not match this
+// bolded verbatim clause, so they don't trip the scan.
+const mdFilesUnder = (dir) => fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+  const full = path.join(dir, e.name);
+  return e.isDirectory() ? mdFilesUnder(full) : (e.name.endsWith('.md') ? [full] : []);
+});
+const ticketLangClauseFiles = mdFilesUnder(sourceSkillsDir).filter((f) => fs.readFileSync(f, 'utf8').includes(ticketLangDecoupling));
+ok('source: ticket-language clause appears in exactly one skills-tree file', ticketLangClauseFiles.length === 1);
+ok('source: that one file is _shared/ticket-language.md', ticketLangClauseFiles.length === 1 && path.basename(ticketLangClauseFiles[0]) === 'ticket-language.md');
+
+// --- #147: chart's close anchors the next step to /trailhead:work -----------
+// Source-level invariant: charting.md renders a codified next-step block at the
+// chart/adopt close, led by /clear, anchored to /trailhead:work (the map-frontier
+// verb) with /trailhead:quick only as the off-map alternative, single-sourced
+// once in Mode 1 step 6 with Mode 1-bis reaching it via "As Mode 1, steps 4-6".
+const chartingSource = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-chart', 'references', 'charting.md'), 'utf8');
+ok('source: charting.md close carries a codified next-step block', /Next-step block \(the close of chart/.test(chartingSource));
+// Structural: the rendered blockquote must LEAD with a standalone /clear bullet
+// (guards the "never demote /clear to a trailing parenthetical" regression #147 exists for).
+ok('source: charting.md next-step block leads with a standalone /clear bullet', /> \*\*Prossimo passo:\*\*\n> - `\/clear`/.test(chartingSource));
+// Structural: /trailhead:work is the primary bullet, carrying the number (name in prose).
+ok('source: charting.md next-step block makes /trailhead:work the primary move with the number', /`\/trailhead:work <numero>` per lavorare \*\*<nome/.test(chartingSource));
+// Structural: /trailhead:quick is demoted to the last "in alternativa ... fuori mappa" bullet.
+ok('source: charting.md next-step block demotes /trailhead:quick to the off-map alternative bullet', /> - in alternativa `\/trailhead:quick[^\n]*fuori mappa/.test(chartingSource));
+ok('source: charting.md next-step block presents several independent tickets as a set to choose from', chartingSource.includes('set to choose from'));
+ok('source: charting.md next-step block frames quick as the off-map alternative', chartingSource.includes('only as the off-map alternative'));
+ok('source: charting.md single-sources the block via the "As Mode 1, steps 4-6" reference', /As Mode 1, steps 4[–-]6/.test(chartingSource));
+const chartSkillSource = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-chart', 'SKILL.md'), 'utf8');
+ok('source: trailhead-chart SKILL.md config-offer points at the next-step block', chartSkillSource.includes('next-step block') && chartSkillSource.includes('/trailhead:work'));
+
+// --- #149: capture confirmation anchors the next step to /trailhead:work -----
+// Source-level invariant, mirroring #147 for chart: capture.md's confirmation-line
+// rule names /trailhead:work as the anchor (full engine, keeps the map record) and
+// demotes /trailhead:quick to the off-map / no-split alternative, offered alongside,
+// never in its place. Localized + ordered assertions (not broad substrings): the anchor
+// clause precedes the quick-demotion clause within the Confirmation line. Targets the
+// capture confirmation line specifically, NOT a blanket /trailhead:quick ban
+// (session-handoff.md legitimately offers /trailhead:quick <n> for the next loose ticket).
+const captureSource = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-capture', 'references', 'capture.md'), 'utf8');
+ok('source: capture.md confirmation anchors the next step to /trailhead:work', /[Aa]nchor the next step to `\/trailhead:work <n>`, always/.test(captureSource));
+ok('source: capture.md demotes /trailhead:quick to only the no-split alternative, after the work anchor',
+  /[Aa]nchor the next step to `\/trailhead:work <n>`[\s\S]{0,400}`\/trailhead:quick <n>` is \*\*only\*\* the no-split alternative/.test(captureSource));
+ok('source: capture.md says quick is offered alongside work, never in its place', captureSource.includes('never in its place'));
+ok('source: capture.md keeps /trailhead:work the anchor even for a whiteboard capture', /whiteboard[\s\S]{0,200}the anchor stays `\/trailhead:work <n>`/.test(captureSource));
+
+// --- #179: `quick <n>` on a map ticket is never "off the map" ----------------
+// Source-level invariant: `quick <n>` on an EXISTING ticket does not leave the
+// map (it keeps its trailhead:map-<n> label and sub-issue edge, and dependent-
+// unblocking still runs); "off the map" describes only `quick "<text>"`, which
+// opens a NEW whiteboard ticket. capture.md, session-handoff.md, and
+// trailhead-work/SKILL.md must no longer carry the old "that same work done
+// off the map" phrasing, nor describe `quick <n>` itself as off the map.
+const sessionHandoffSource = fs.readFileSync(path.join(sourceSkillsDir, '_shared', 'session-handoff.md'), 'utf8');
+const workSkillSourceFor179 = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-work', 'SKILL.md'), 'utf8');
+const offMapQuickN = /`?quick <n>`?[^.\n]{0,80}off the map/i;
+// The explicit "never describe ... as off the map" clause legitimately puts
+// `quick <n>` near "off the map" in the same sentence, so strip it before
+// running the negative proximity check below.
+const neverDescribeClause = /[Nn]ever describe `quick <n>`[^\n]*?off the map\.?/;
+const sessionHandoffMinusClause = sessionHandoffSource.replace(neverDescribeClause, '');
+ok('source: capture.md drops the old "that same work done off the map" phrasing', !captureSource.includes('that same work done off the map'));
+ok('source: session-handoff.md drops the old "that same work done off the map" phrasing', !sessionHandoffSource.includes('that same work done off the map'));
+ok('source: trailhead-work SKILL.md drops the old "that same work done off the map" phrasing', !workSkillSourceFor179.includes('that same work done off the map'));
+ok('source: capture.md never describes quick <n> as off the map', !offMapQuickN.test(captureSource));
+ok('source: session-handoff.md never describes quick <n> as off the map (outside the explicit never-clause)', !offMapQuickN.test(sessionHandoffMinusClause));
+ok('source: trailhead-work SKILL.md never describes quick <n> as off the map', !offMapQuickN.test(workSkillSourceFor179));
+ok('source: session-handoff.md explicitly says never to describe quick <n> on a map ticket as off the map',
+  neverDescribeClause.test(sessionHandoffSource));
+ok('source: capture.md says a map ticket stays on its map', /a map ticket stays on its map/.test(captureSource));
+const ticketEnginesSourceFor179 = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-work', 'references', 'ticket-engines.md'), 'utf8');
+ok('source: ticket-engines.md never labels quick generically as off-map', !/`quick`[^.\n]{0,40}off-map/.test(ticketEnginesSourceFor179));
+
+// --- #151: eager edge drop at close (superseded / out-of-scope only) ---------
+// Source-level invariant: closing a ticket as trailhead:superseded or
+// trailhead:out-of-scope drops its native sub-issue edge at close (reusing the
+// 404-tolerant DELETE from #150), while a genuinely-resolved close leaves the
+// edge in place (it feeds GitHub's native progress bar; /trailhead:prune is its
+// only shedder). Asserts the canonical rule, every operative close site, and a
+// NEGATIVE invariant on the resolved-close path.
+const substrateCommandsSource = fs.readFileSync(path.join(sourceSkillsDir, '_shared', 'substrate-commands.md'), 'utf8');
+ok('source: substrate-commands.md documents the eager edge drop at close (superseded / out-of-scope only)',
+  /[Ee]ager edge drop at close \(superseded \/ out-of-scope only\)/.test(substrateCommandsSource));
+ok('source: substrate-commands.md fixes the label -> DELETE -> close ordering for the eager drop',
+  /apply the state label first, then DELETE the edge, then `gh issue close`/.test(substrateCommandsSource));
+ok('source: substrate-commands.md eager drop excludes resolved closes (progress bar / prune)',
+  // Proximity-scoped so each conjunct is load-bearing on the NEW paragraph's own
+  // text, not on the pre-existing "progress bar" mentions elsewhere in the file.
+  /Only these two closes shed eagerly[\s\S]{0,300}progress bar/.test(substrateCommandsSource) &&
+  /Resolved edges stay[\s\S]{0,160}`\/trailhead:prune`'s job/.test(substrateCommandsSource));
+
+const substrateSource = fs.readFileSync(path.join(sourceSkillsDir, '_shared', 'substrate.md'), 'utf8');
+ok('source: substrate.md out-of-scope label notes the edge is dropped at close',
+  /`trailhead:out-of-scope`[\s\S]{0,260}native sub-issue edge is dropped at close/.test(substrateSource));
+ok('source: substrate.md superseded label notes the edge is dropped at close',
+  /`trailhead:superseded`[\s\S]{0,260}native sub-issue edge is dropped at close/.test(substrateSource));
+
+const teamworkSource = fs.readFileSync(path.join(sourceSkillsDir, '_shared', 'teamwork.md'), 'utf8');
+ok('source: teamwork.md supersede close drops the native sub-issue edge',
+  /Supersede the original[\s\S]{0,400}drop its native sub-issue edge from the map/.test(teamworkSource));
+
+const workSkillSource = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-work', 'SKILL.md'), 'utf8');
+ok('source: trailhead-work SKILL.md out-of-scope close drops the native sub-issue edge',
+  /out of scope\*\* \(label, then \*\*drop its native sub-issue edge\*\*/.test(workSkillSource));
+
+const inboxSource = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-chart', 'references', 'inbox.md'), 'utf8');
+ok('source: inbox.md out-of-scope close drops the native sub-issue edge',
+  /`trailhead:out-of-scope`, \*\*drop its native sub-issue edge\*\*/.test(inboxSource));
+ok('source: inbox.md dropped-fog close drops any native sub-issue edge',
+  /drop any native sub-issue edge to reclaim a slot/.test(inboxSource));
+
+// NEGATIVE invariant: the resolved-close paths (build/bug Resolve) must NOT
+// carry an eager edge-drop instruction; resolved edges stay for the progress bar.
+const ticketEnginesSource = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-work', 'references', 'ticket-engines.md'), 'utf8');
+ok('source: ticket-engines.md resolved-close path does NOT drop the native sub-issue edge',
+  !/drop (its|any) native sub-issue edge/.test(ticketEnginesSource));
+
+// --- #178: drive-mode ask (AI-driven vs human-driven) at every UAT start -----
+// Single-sourced in techniques/acceptance-testing.md as the "Drive mode" bullet;
+// every other call-site (ticket-engines.md, auto.md, choices.md) references it
+// by name ("drive-mode ask") rather than restating its clauses. Extract the
+// bullet's own span (its marker line through the end of its indented `  - `
+// sub-bullets) and pin each clause inside that span, mirroring the #139/#146
+// source-level anti-drift style.
+function extractBulletSpan(source, markerLine) {
+  const lines = source.split('\n');
+  const startIdx = lines.findIndex((l) => l.includes(markerLine));
+  if (startIdx === -1) return '';
+  let endIdx = startIdx + 1;
+  while (endIdx < lines.length && lines[endIdx].startsWith('  - ')) endIdx++;
+  return lines.slice(startIdx, endIdx).join('\n');
+}
+const driveModeMarker = '- **Drive mode: ask who drives the UAT.**';
+const acceptanceTestingSourcePath = path.join(sourceSkillsDir, '_shared', 'techniques', 'acceptance-testing.md');
+const acceptanceTestingSource = fs.readFileSync(acceptanceTestingSourcePath, 'utf8');
+const driveModeSpan = extractBulletSpan(acceptanceTestingSource, driveModeMarker);
+ok('source: acceptance-testing.md carries the Drive-mode bullet', driveModeSpan.length > 0);
+for (const phrase of [
+  '**before any step runs**',
+  '**wait for an explicit answer**',
+  '**silence or an ambiguous reply re-asks**',
+  '**One-path skip**',
+  '**state the reason in one line**',
+  'VERIFY',
+  'only for the steps it cannot perform',
+  'runs unchanged',
+  '**in both modes**',
+  'acceptance.browser: off',
+  'without the confirm gate',
+]) {
+  ok(`source: acceptance-testing.md Drive-mode span pins "${phrase}"`, driveModeSpan.includes(phrase));
+}
+// The three start paths.
+ok('source: Drive-mode span names build/bug Verify as a start path', driveModeSpan.includes('Verify'));
+ok("source: Drive-mode span names the Pending-UAT guard's option (a) as a start path", driveModeSpan.includes('Pending-UAT guard'));
+ok('source: Drive-mode span names a UAT follow-up (UAT of:) as a start path', driveModeSpan.includes('UAT of:'));
+// The three performability classes.
+ok('source: Drive-mode span names the physical-device/hardware performability class', driveModeSpan.includes('a physical device or hardware'));
+ok('source: Drive-mode span names the credentials/accounts performability class', driveModeSpan.includes('credentials or accounts it does not hold'));
+ok('source: Drive-mode span names the human sensory-judgement performability class', driveModeSpan.includes('a human sensory judgement'));
+
+// The "Pending UAT must stay tracked" bullet references the ask for BOTH (a)
+// run-now and (b) the follow-up (grouped: two mentions in the same bullet).
+const pendingUatBulletMarker = '**Pending UAT must stay tracked: a closed ticket is not tracking.**';
+const pendingUatLine = acceptanceTestingSource.split('\n').find((l) => l.includes(pendingUatBulletMarker)) || '';
+ok('source: Pending-UAT bullet exists', pendingUatLine.length > 0);
+ok('source: Pending-UAT bullet references the drive-mode ask for both (a) and the follow-up',
+  (pendingUatLine.match(/drive-mode ask/g) || []).length >= 2);
+
+// Single-source anti-drift: the bullet's own signature phrase appears in
+// exactly one file across the whole skills tree (mirrors #146).
+const driveModeSignature = 'ask who drives the UAT';
+const driveModeSignatureFiles = mdFilesUnder(sourceSkillsDir).filter((f) => fs.readFileSync(f, 'utf8').includes(driveModeSignature));
+ok('source: "ask who drives the UAT" signature appears in exactly one skills-tree file', driveModeSignatureFiles.length === 1);
+ok('source: that one file is techniques/acceptance-testing.md', driveModeSignatureFiles.length === 1 && driveModeSignatureFiles[0] === acceptanceTestingSourcePath);
+
+// The Codex install projects acceptance-testing.md with the Drive-mode bullet.
+ok('codex: skills/_shared/techniques/acceptance-testing.md is projected with the Drive-mode bullet',
+  fs.readFileSync(path.join(codexDir, 'skills', '_shared', 'techniques', 'acceptance-testing.md'), 'utf8').includes(driveModeMarker));
+
+// --- #178 (2/4): route UAT follow-ups by pointer, engines through the ask ----
+// A new type-independent section, keyed on the `UAT of:` pointer rather than
+// the ticket's type label, must sit before the first per-type `## `decision``
+// heading (work/quick/auto all dispatch through this file).
+function extractSection(source, headingMarker) {
+  const start = source.indexOf(headingMarker);
+  if (start === -1) return '';
+  const rest = source.slice(start + headingMarker.length);
+  const nextHeadingIdx = rest.search(/\n## /);
+  return headingMarker + (nextHeadingIdx === -1 ? rest : rest.slice(0, nextHeadingIdx));
+}
+const uatFollowupHeadingMarker = '## UAT follow-ups (any type)';
+const decisionHeadingMarker = '## `decision`';
+ok('source: ticket-engines.md has the "UAT follow-ups (any type)" section', ticketEnginesSource.includes(uatFollowupHeadingMarker));
+ok('source: the UAT follow-ups section precedes the first `decision` heading',
+  ticketEnginesSource.indexOf(uatFollowupHeadingMarker) !== -1 &&
+  ticketEnginesSource.indexOf(uatFollowupHeadingMarker) < ticketEnginesSource.indexOf(decisionHeadingMarker));
+const uatFollowupSection = extractSection(ticketEnginesSource, uatFollowupHeadingMarker);
+for (const phrase of ['UAT of:', 'whatever its type label', 'trailhead:seed', '`VERIFY` comment on the follow-up', 'acceptance-testing.md']) {
+  ok(`source: the UAT follow-ups section contains "${phrase}"`, uatFollowupSection.includes(phrase));
+}
+
+// Both the build and bug engines' Verify step, and both Resolve steps'
+// Pending-UAT guard, must route through the drive-mode ask by name (the
+// single source stays acceptance-testing.md; these reference it).
+const verifyStepLines = ticketEnginesSource.split('\n').filter((l) => l.trim().startsWith('4. **Verify**'));
+ok('source: ticket-engines.md carries both the build and bug Verify step lines', verifyStepLines.length === 2);
+ok('source: both Verify step lines reference the drive-mode ask', verifyStepLines.length === 2 && verifyStepLines.every((l) => l.includes('drive-mode ask')));
+
+const pendingUatGuardLines = ticketEnginesSource.split('\n').filter((l) => l.includes('Pending-UAT guard (before the close)'));
+ok('source: ticket-engines.md carries both build and bug Pending-UAT guard lines', pendingUatGuardLines.length === 2);
+ok('source: both Pending-UAT guard lines reference the drive-mode ask', pendingUatGuardLines.length === 2 && pendingUatGuardLines.every((l) => l.includes('drive-mode ask')));
+
+// 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.
+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));
+
+// choices.md carries the call-site row for the drive-mode ask.
+const choicesSourcePath = path.join(sourceSkillsDir, '_shared', 'choices.md');
+const choicesSource = fs.readFileSync(choicesSourcePath, 'utf8');
+ok('source: choices.md call-site table carries the drive-mode ask row', /\|[^\n]*[Dd]rive-mode ask[^\n]*\|/.test(choicesSource));
+
+// --- #178 (3/4): acceptance.browser off keeps AI-driven UAT via commands ----
+const configReferencePath = path.join(sourceSkillsDir, '_shared', 'configuration-reference.md');
+const configReferenceSource = fs.readFileSync(configReferencePath, 'utf8');
+ok('source: configuration-reference.md acceptance.browser explanation clarifies off still runs AI-driven checks via commands',
+  /\*\*acceptance\.browser\.\*\*[\s\S]{0,1000}`off`[\s\S]{0,300}AI-driven[\s\S]{0,300}commands/.test(configReferenceSource));
+ok('source: configuration-reference.md guided-setup menu no longer labels the off option "Guided UAT only"',
+  !configReferenceSource.includes('Guided UAT only'));
+ok('source: configuration-reference.md guided-setup menu relabels the off option "No browser"',
+  /Acceptance testing[\s\S]{0,200}No browser/.test(configReferenceSource));
+
+// --- #178 (4/4): mirror the UAT drive-mode ask in READMEs and /docs ---------
+const readmeSource = fs.readFileSync(path.join(repoRoot, 'README.md'), 'utf8');
+const readmeItSource = fs.readFileSync(path.join(repoRoot, 'README.it.md'), 'utf8');
+const ticketTypesSource = fs.readFileSync(path.join(repoRoot, 'site', 'src', 'content', 'docs', 'docs', 'ticket-types.md'), 'utf8');
+const workflowSource = fs.readFileSync(path.join(repoRoot, 'site', 'src', 'content', 'docs', 'docs', 'workflow.md'), 'utf8');
+const configurationMdxSource = fs.readFileSync(path.join(repoRoot, 'site', 'src', 'content', 'docs', 'docs', 'configuration.mdx'), 'utf8');
+
+ok('README.md build row frames acceptance testing as asking who drives', /🔨 `build`[\s\S]{0,400}who drives/.test(readmeSource));
+ok('README.md worked example frames the login-flow acceptance as AI-driven', /asked who drives[\s\S]{0,100}AI-driven/.test(readmeSource));
+ok('README.md acceptance.browser row says off still runs AI-driven checks', /`acceptance\.browser`[\s\S]{0,400}AI-driven/.test(readmeSource));
+
+ok('README.it.md build row frames acceptance testing as asking who drives (chi guida)', /🔨 `build`[\s\S]{0,400}chi guida/.test(readmeItSource));
+ok('README.it.md worked example frames the login-flow acceptance as AI-driven', /chi guida[\s\S]{0,100}AI-driven/.test(readmeItSource));
+ok('README.it.md acceptance.browser row says off still runs AI-driven checks', /`acceptance\.browser`[\s\S]{0,400}AI-driven/.test(readmeItSource));
+
+ok('site ticket-types.md build row frames acceptance testing as asking who drives', /`build`[\s\S]{0,400}who drives/.test(ticketTypesSource));
+ok('site workflow.md worked example frames the login-flow acceptance as AI-driven', /asked who drives[\s\S]{0,100}AI-driven/.test(workflowSource));
+ok('site configuration.mdx acceptance.browser row says off still runs AI-driven checks', /`acceptance\.browser`[\s\S]{0,400}AI-driven/.test(configurationMdxSource));
+
+// --- #178 fix: keep the drive-mode ask ahead of URL resolution --------------
+// Code review found the acceptance.browser clause made the drive-mode ask
+// CONDITIONAL on URL resolution ("fall back to the drive-mode ask ... only
+// when none can be determined"), contradicting the single source
+// (acceptance-testing.md: the ask fires before any step runs, always) and
+// conflating it with the URL-not-found fallback (ask for the URL, or guided
+// UAT). The clause must instead state the ask always comes first and never
+// gate it on URL detection.
+ok('source: configuration-reference.md acceptance.browser clause does NOT make the drive-mode ask conditional on URL resolution',
+  !configReferenceSource.includes('fall back to the drive-mode ask'));
+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").
+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));
+
 // --- codex hooks (#29) --------------------------------------------------------
 const codexHooksJsonPath = path.join(codexDir, 'hooks.json');
 ok('codex: hooks.json exists', fs.existsSync(codexHooksJsonPath));
@@ -148,6 +457,16 @@ ok('codex: hooks.json registers check-update under SessionStart', (codexHooksJso
 ok('codex: skills/trailhead/hooks/trailhead-secret-guard.js exists', fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'trailhead-secret-guard.js')));
 ok('codex: skills/trailhead/hooks/lib/commit-message-check.js exists (commit-guard require target)',
   fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'commit-message-check.js')));
+ok('codex: skills/trailhead/hooks/lib/gh-subcommand.js exists (body-guard/secret-guard require target, #153)',
+  fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'gh-subcommand.js')));
+// #169: search-guard is Claude-Code-specific (it only prevents arming
+// Claude's Read() deny rule under bypass permissions, a mechanism Codex
+// lacks), so it must neither be registered nor copied on a Codex install.
+ok('codex: hooks.json does NOT register search-guard under any event', !codexHooksJsonStr.includes('trailhead-search-guard.js'));
+ok('codex: skills/trailhead/hooks/trailhead-search-guard.js does NOT exist',
+  !fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'trailhead-search-guard.js')));
+ok('codex: skills/trailhead/hooks/lib/shell-scan.js still exists (secret-read-guard require target)',
+  fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'shell-scan.js')));
 
 const codexConfigTomlPath = path.join(codexDir, 'config.toml');
 ok('codex: config.toml exists', fs.existsSync(codexConfigTomlPath));
@@ -271,11 +590,18 @@ ok('claude: trailhead-work/../_shared/load-first.md resolves', fs.existsSync(pat
 for (const cl of ['trailhead', 'trailhead-chart', 'trailhead-work', 'trailhead-view', 'trailhead-capture', 'trailhead-manage']) {
   ok(`claude: ${cl} SKILL.md references ../_shared/load-first.md`, fs.readFileSync(path.join(claudeDir, 'skills', cl, 'SKILL.md'), 'utf8').includes('../_shared/load-first.md'));
 }
+
+// #146: single-sourced ticket-language directive, projected on Claude too.
+ok('claude: skills/_shared/ticket-language.md exists', fs.existsSync(path.join(claudeDir, 'skills', '_shared', 'ticket-language.md')));
+ok('claude: trailhead-work/../_shared/ticket-language.md resolves', fs.existsSync(path.join(claudeDir, 'skills', 'trailhead-work', '..', '_shared', 'ticket-language.md')));
+
 ok('claude: commands/trailhead/work.md exists', fs.existsSync(path.join(claudeDir, 'commands', 'trailhead', 'work.md')));
 ok('claude: commands/trailhead/auto.md exists', fs.existsSync(path.join(claudeDir, 'commands', 'trailhead', 'auto.md')));
 ok('claude: hooks/trailhead-commit-guard.js exists', fs.existsSync(path.join(claudeDir, 'hooks', 'trailhead-commit-guard.js')));
 ok('claude: hooks/lib/commit-message-check.js exists (commit-guard require target)',
   fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'commit-message-check.js')));
+ok('claude: hooks/lib/gh-subcommand.js exists (body-guard/secret-guard require target, #153)',
+  fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'gh-subcommand.js')));
 // Regression: the commit-guard does require('./lib/commit-message-check.js'), so
 // it only loads if the lib was copied alongside it. Run it with a benign Bash
 // payload and assert it does not crash with a missing-module error.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcomigozzi/trailhead",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "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.8.1",
+  "version": "0.10.0",
   "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/commands/prune.md

@@ -0,0 +1,6 @@
+---
+description: Prune a map's closed and orphan sub-issue edges to reclaim slots under GitHub's 100-cap (references kept)
+argument-hint: "[map]"
+---
+
+Invoke the `trailhead` skill for the **prune** action: call the Skill tool with skill name `trailhead-manage` and arguments `prune $ARGUMENTS`, then **read the skill's `references/pruning.md` and follow it**: that file holds the prune protocol (resolve the target map, read the sub-issue count, reconcile the map's native edges bidirectionally, preview and confirm, then apply, keeping every reference). Do not re-implement the behaviour here. The skill is the single source of truth.

package/plugins/trailhead/commands/quick.md

@@ -1,5 +1,5 @@
 ---
-description: Work one ticket whole, off the map (whiteboard); grills only if needed, never splits
+description: Work one ticket whole, never splits: a new whiteboard ticket from text, or an existing one; grills only if needed
 argument-hint: "[ticket | \"text\"]"
 ---
 

package/plugins/trailhead/hooks/hooks.json

@@ -19,6 +19,10 @@
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/trailhead-search-guard.js\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/trailhead-body-guard.js\""
           }
         ]
       },

package/plugins/trailhead/hooks/lib/gh-subcommand.js

@@ -0,0 +1,102 @@
+'use strict';
+// gh-subcommand.js: shared gh-subcommand detector, extracted from
+// trailhead-body-guard.js's ghBodyWrite and trailhead-secret-guard.js's
+// ghIssueWrite (#153 follow-up), so both guards share ONE token walk instead
+// of drifting copies.
+//
+// Bug fixed here (#153): the original inline walk only treated `-R`/`--repo`
+// as a two-token (value-taking) global gh flag. Any OTHER two-token global
+// flag (e.g. `gh --hostname h issue edit 5 --body ""`) desynced the walk:
+// after skipping `--hostname`, the index landed on its value `h`, which is
+// not a `-`-prefixed flag so the loop stopped there, and `h` was mistaken for
+// the subcommand. The write became invisible to both guards (a missed
+// empty-body block in body-guard, an unscanned secret in secret-guard).
+//
+// Follow-up fix (#153): a first pass tolerated a stray value token after any
+// unknown flag UNLESS that token was itself a flag or a subcommand keyword
+// (issue/pr/api). That guard reintroduced the exact same desync whenever the
+// flag's VALUE literally equalled a subcommand keyword, e.g.
+// `gh --hostname api issue edit 5` mis-resolved `sub` to `api` (the flag
+// value), hiding the real `issue edit` write again.
+//
+// Fix: drop the keyword-based guard entirely and model flag arity instead.
+// gh's only value-taking global flag before a subcommand is -R/--repo; a
+// small, explicit set of global flags are boolean (take no value). Every
+// OTHER flag token is treated as value-taking, so its value can never be
+// mistaken for the subcommand - including when that value happens to equal
+// a subcommand keyword like `issue`/`pr`/`api`.
+//
+// Second follow-up fix (#153): treating every unknown flag as value-taking
+// reopened the MIRROR case - an unknown BOOLEAN flag directly before the
+// subcommand (e.g. `gh --foo issue edit 5`) now gets treated as value-taking
+// and swallows the subcommand itself as if it were the flag's value, landing
+// `sub` on the verb (`edit`) instead of `issue`. The two failure directions
+// (a flag's VALUE colliding with a subcommand keyword, vs. an unknown
+// BOOLEAN flag consuming the subcommand) cannot both be resolved by a
+// positional walk alone: `gh --X <tok> issue edit` and `gh --X issue edit`
+// are structurally ambiguous without knowing --X's arity in advance, and gh
+// itself rejects unknown flags so neither shape occurs with the real `gh`
+// binary. But the guard defends against any `gh`-named binary, so it must
+// not depend on that.
+//
+// Design principle: keep the value-taking primary walk (it is correct for
+// every KNOWN two-token flag, e.g. -R/--repo, and for the common case of an
+// unknown two-token flag), then ADD a fail-safe fallback that scans forward
+// for a recognized write-subcommand keyword whenever the walk did not land
+// on one. Erring toward DETECTION (scanning/considering a write) is the safe
+// direction for a security guard; under-detection (missing a real write) is
+// the dangerous one. The downstream verb gate in each guard still prevents a
+// stray keyword token in a genuinely non-write command from being
+// misclassified as a write.
+//
+// Self-contained. No requires.
+
+// gh's boolean global flags (take NO value). gh's only value-taking global
+// flag before a subcommand is -R/--repo; every other flag token here is
+// treated as value-taking, so an unknown two-token global flag's value can
+// never be mistaken for the subcommand (#153) - including when that value
+// happens to equal a subcommand keyword like `issue`/`pr`/`api`.
+const BOOLEAN_GLOBAL_FLAGS = new Set(['-h', '--help', '--version']);
+
+// The subcommands the guards care about; used by the fail-safe fallback
+// below to recover from an unknown boolean flag swallowing the subcommand.
+const WRITE_SUBCOMMANDS = new Set(['issue', 'pr', 'api']);
+
+// Parse a raw shell command string and locate the gh subcommand/verb.
+// Returns { sub, verb } (verb may be undefined) or null when this is not a
+// gh invocation at all.
+function parseGhSubcommand(cmd) {
+  const toks = String(cmd).trim().split(/\s+/);
+  let i = 0;
+  while (i < toks.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(toks[i])) i++; // env prefix
+  if (i >= toks.length || !/(^|\/)gh$/.test(toks[i])) return null;         // the gh binary
+  const start = i + 1; // first token after `gh`
+  i = start;
+  // Primary positional walk. -R/--repo (and any non-boolean, non-glued flag)
+  // is treated as value-taking: consume one following non-flag token so an
+  // unknown two-token global flag's value cannot shift the subcommand (#153).
+  while (i < toks.length && toks[i].startsWith('-')) {
+    const flag = toks[i];
+    i++; // the flag token itself
+    if (flag.includes('=') || BOOLEAN_GLOBAL_FLAGS.has(flag)) continue; // no separate value
+    if (i < toks.length && !toks[i].startsWith('-')) i++;               // consume its value
+  }
+  let sub = toks[i];
+  let verb = toks[i + 1];
+  // Fail-safe fallback: if the walk did NOT land on a recognized write
+  // subcommand, an unknown *boolean* flag before the subcommand may have
+  // consumed the subcommand itself as if it were the flag's value (the mirror
+  // of the value-collision case). Scan forward for the first recognized
+  // subcommand keyword and use it. Over-detection is the safe direction for a
+  // guard; under-detection (missing a real write) is the dangerous one (#153).
+  // The downstream guards still gate on the verb, so a stray keyword token in a
+  // non-write command does not become a spurious write.
+  if (!WRITE_SUBCOMMANDS.has(sub)) {
+    for (let j = start; j < toks.length; j++) {
+      if (WRITE_SUBCOMMANDS.has(toks[j])) { sub = toks[j]; verb = toks[j + 1]; break; }
+    }
+  }
+  return { sub, verb };
+}
+
+module.exports = { parseGhSubcommand, BOOLEAN_GLOBAL_FLAGS, WRITE_SUBCOMMANDS };