@marcomigozzi/trailhead 0.9.0 → 0.11.0

package/bin/trailhead.test.js

@@ -54,7 +54,7 @@ function fakeBinDir(names) {
 
 // --- codex install -----------------------------------------------------------
 const codexDir = mktmp();
-runInstaller([`--codex`, `--dir=${codexDir}`]);
+const codexInstallOut = String(runInstaller([`--codex`, `--dir=${codexDir}`]));
 
 const skillMainPath = path.join(codexDir, 'skills', 'trailhead', 'SKILL.md');
 ok('codex: SKILL.md exists', fs.existsSync(skillMainPath));
@@ -85,6 +85,12 @@ ok('codex: commit-msg template projected', fs.existsSync(codexTemplate));
 ok('codex: commit-msg template is verbatim (not converted)',
   fs.readFileSync(codexTemplate, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-commit-msg'), 'utf8'));
 
+// #185: the commit-msg hook sync script ships wholesale with templates/ too.
+const codexCommitMsgSync = path.join(codexDir, 'skills', 'trailhead', 'templates', 'trailhead-commit-msg-sync.js');
+ok('codex: commit-msg-sync script projected', fs.existsSync(codexCommitMsgSync));
+ok('codex: commit-msg-sync script is byte-identical to source',
+  fs.readFileSync(codexCommitMsgSync, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-commit-msg-sync.js'), 'utf8'));
+
 ok('codex: no commands dir', !fs.existsSync(path.join(codexDir, 'commands')));
 ok('codex: no settings.json file', !fs.existsSync(path.join(codexDir, 'settings.json')));
 // #46: per-verb discoverability now projects one Codex SKILL per verb
@@ -206,11 +212,195 @@ ok('source: trailhead-chart SKILL.md config-offer points at the next-step block'
 // (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 off-map / 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 off-map \/ no-split alternative/.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));
+
+// --- #181: scope code review and verify to the ticket's own commits ---------
+// Source-level invariant: Code review and Goal-backward verification scope to
+// the commits carrying this ticket's `Refs: #<n>` trailer (the "Ticket diff"
+// rule), never a `<base>...HEAD` range, which under `git: main` sweeps in
+// other tickets' interleaved commits. code-review.md is canonical; verify.md
+// restates the same pinned command inline. Also a behavioral pin: run the
+// extracted command against a scratch repo with decoys, an interleaved
+// foreign commit, and a conflicting trunk-sync merge.
+const codeReviewSourcePath181 = path.join(sourceSkillsDir, '_shared', 'techniques', 'code-review.md');
+const codeReviewSource181 = fs.readFileSync(codeReviewSourcePath181, 'utf8');
+const verifySourcePath181 = path.join(sourceSkillsDir, '_shared', 'techniques', 'verify.md');
+const verifySource181 = fs.readFileSync(verifySourcePath181, 'utf8');
+const techniquesSourcePath181 = path.join(sourceSkillsDir, '_shared', 'techniques.md');
+const techniquesSource181 = fs.readFileSync(techniquesSourcePath181, 'utf8');
+const ticketEnginesSource181 = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-work', 'references', 'ticket-engines.md'), 'utf8');
+
+ok("code-review.md states the Ticket diff heading sentence",
+  codeReviewSource181.includes("**Ticket diff: review the ticket's own commits, never a range.**"));
+ok('code-review.md contains the exact per-commit read form',
+  codeReviewSource181.includes('git -C <repo> show --remerge-diff <sha>'));
+ok('code-review.md does NOT contain the old range-scoped diff', !codeReviewSource181.includes('git diff <base>...HEAD'));
+ok('code-review.md does NOT contain the old "pin a fixed point" phrasing', !codeReviewSource181.includes('pin a fixed point'));
+ok('code-review.md states an empty set is an error', /\*\*An empty set is an error\*\*/.test(codeReviewSource181));
+ok('code-review.md says the set is recomputed every round and every verify run',
+  codeReviewSource181.includes('Recompute the set on every review round and every verify run'));
+ok('code-review.md says the set is never collapsed into one span',
+  codeReviewSource181.includes('Never collapse the set into one'));
+ok('code-review.md mentions git: pr', codeReviewSource181.includes('git: pr'));
+ok('code-review.md mentions trailhead/t<n>', codeReviewSource181.includes('trailhead/t<n>'));
+
+const ticketDiffLogCmdRegex = /git -C <repo> log [^\n`]*HEAD/;
+const codeReviewCmdMatch181 = codeReviewSource181.match(ticketDiffLogCmdRegex);
+ok('code-review.md contains the pinned Ticket diff log command', !!codeReviewCmdMatch181);
+const codeReviewLogCmd181 = codeReviewCmdMatch181 ? codeReviewCmdMatch181[0] : '';
+
+ok('verify.md contains the same per-commit read form as code-review.md',
+  verifySource181.includes('git -C <repo> show --remerge-diff <sha>'));
+ok('verify.md references the Ticket diff', verifySource181.includes('**Ticket diff**'));
+ok('verify.md references code-review.md as canonical', verifySource181.includes('code-review.md'));
+ok('verify.md does NOT contain the old range-scoped diff', !verifySource181.includes('git diff <base>...HEAD'));
+
+const verifyCmdMatch181 = verifySource181.match(ticketDiffLogCmdRegex);
+ok('verify.md contains the pinned Ticket diff log command', !!verifyCmdMatch181);
+const verifyLogCmd181 = verifyCmdMatch181 ? verifyCmdMatch181[0] : '';
+ok('code-review.md and verify.md state the exact same log command',
+  codeReviewLogCmd181 !== '' && codeReviewLogCmd181 === verifyLogCmd181);
+
+const verifyStepLines181 = ticketEnginesSource181.split('\n').filter((l) => l.trim().startsWith('4. **Verify**'));
+ok('ticket-engines.md has exactly two Verify (step 4) lines', verifyStepLines181.length === 2);
+ok('both Verify step lines reference the Ticket diff', verifyStepLines181.every((l) => l.includes('**Ticket diff**')));
+ok('ticket-engines.md does NOT contain the old range-scoped diff', !ticketEnginesSource181.includes('git diff <base>...HEAD'));
+
+ok("techniques.md index row updates Code review to the ticket's own commits",
+  techniquesSource181.includes("review the ticket's own commits (its `Refs: #<n>` set) on 4 axes"));
+
+for (const [label, src] of [
+  ['code-review.md', codeReviewSource181],
+  ['verify.md', verifySource181],
+  ['ticket-engines.md', ticketEnginesSource181],
+  ['techniques.md', techniquesSource181],
+]) {
+  ok(`${label} has no em-dash`, !src.includes('\u2014'));
+}
+
+// --- #181 behavioral pin: build a scratch repo and run the extracted command -
+function gitEnv181(extra = {}) {
+  return {
+    ...process.env,
+    GIT_CONFIG_GLOBAL: '/dev/null',
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_AUTHOR_NAME: 'Trailhead Test',
+    GIT_AUTHOR_EMAIL: 'trailhead-test@example.com',
+    GIT_COMMITTER_NAME: 'Trailhead Test',
+    GIT_COMMITTER_EMAIL: 'trailhead-test@example.com',
+    LC_ALL: 'C',
+    ...extra,
+  };
+}
+function git181(dir, args, extraEnv = {}) {
+  return execFileSync('git', ['-C', dir, ...args], { env: gitEnv181(extraEnv), stdio: ['ignore', 'pipe', 'pipe'] }).toString();
+}
+function commit181(dir, message, dateStr) {
+  git181(dir, ['add', '-A']);
+  git181(dir, ['commit', '-m', message], { GIT_AUTHOR_DATE: dateStr, GIT_COMMITTER_DATE: dateStr });
+  return git181(dir, ['rev-parse', 'HEAD']).trim();
+}
+
+const t181Repo = mktmp();
+git181(t181Repo, ['init', '-b', 'main']);
+const fFile181 = path.join(t181Repo, 'f.txt');
+const D181 = (n) => `2026-01-01T00:00:${String(n).padStart(2, '0')}Z`;
+
+fs.writeFileSync(fFile181, 'a\n');
+const shaA181 = commit181(t181Repo, 'feat: a\n\nRefs: #18', D181(1));
+
+fs.writeFileSync(path.join(t181Repo, 'decoy-b.txt'), 'b\n');
+commit181(t181Repo, 'feat: b\n\nRefs: #181', D181(2));
+
+fs.writeFileSync(path.join(t181Repo, 'decoy-c.txt'), 'c\n');
+commit181(t181Repo, 'feat: c\n\nRefs: #1800', D181(3));
+
+fs.writeFileSync(path.join(t181Repo, 'decoy-d.txt'), 'd\n');
+commit181(t181Repo, 'feat: d\n\nmentions Refs: #18 inline\nRefs: #99', D181(4));
+
+fs.writeFileSync(fFile181, 'foreign\n');
+commit181(t181Repo, 'feat: foreign\n\nRefs: #99', D181(5));
+
+git181(t181Repo, ['checkout', '-b', 'side']);
+fs.writeFileSync(fFile181, 'side-edit\n');
+fs.writeFileSync(path.join(t181Repo, 'foreign.txt'), 'foreign-file\n');
+commit181(t181Repo, 'chore: side edit', D181(6));
+
+git181(t181Repo, ['checkout', 'main']);
+fs.writeFileSync(fFile181, 'main-edit\n');
+const shaF181 = commit181(t181Repo, 'fix: e\n\nRefs: #18', D181(7));
+
+let mergeConflicted181 = false;
+try {
+  git181(t181Repo, ['merge', 'side', '--no-commit', '--no-ff']);
+} catch {
+  mergeConflicted181 = true;
+}
+ok('#181 scratch repo: the trunk-sync merge actually conflicts on f.txt', mergeConflicted181);
+fs.writeFileSync(fFile181, 'RESOLVED\n');
+git181(t181Repo, ['add', 'f.txt', 'foreign.txt']);
+const shaMerge181 = commit181(t181Repo, 'merge: sync\n\nRefs: #18', D181(8));
+
+ok('#181 scratch repo: merge sha differs from the fix sha', shaMerge181 !== shaF181);
+
+function runShellGit181(cmd, extraEnv = {}) {
+  return execFileSync('sh', ['-c', cmd], { env: gitEnv181(extraEnv), stdio: ['ignore', 'pipe', 'pipe'] }).toString();
+}
+
+const substituted181 = (cmd, n) => cmd.replace(/<repo>/g, JSON.stringify(t181Repo)).replace(/<n>/g, String(n));
+
+const fixedPatternTypeEnv181 = {
+  GIT_CONFIG_COUNT: '1',
+  GIT_CONFIG_KEY_0: 'grep.patternType',
+  GIT_CONFIG_VALUE_0: 'fixed',
+};
+
+const out18_181 = runShellGit181(substituted181(codeReviewLogCmd181, 18), fixedPatternTypeEnv181);
+const lines18_181 = out18_181.split('\n').filter((l) => l.length > 0);
+ok('#181 log command returns exactly [a, f, merge] oldest-first for #18, even under grep.patternType=fixed',
+  lines18_181.length === 3 && lines18_181[0] === shaA181 && lines18_181[1] === shaF181 && lines18_181[2] === shaMerge181);
+
+const out7_181 = runShellGit181(substituted181(codeReviewLogCmd181, 7), fixedPatternTypeEnv181);
+ok('#181 log command returns empty output for a ticket with no commits', out7_181.trim() === '');
+
+const remergeCmd181 = 'git -C <repo> show --remerge-diff <sha>'
+  .replace('<repo>', JSON.stringify(t181Repo))
+  .replace('<sha>', shaMerge181);
+const remergeOut181 = runShellGit181(remergeCmd181);
+ok('#181 --remerge-diff on the merge shows the resolution hunk', remergeOut181.includes('RESOLVED'));
+ok('#181 --remerge-diff on the merge does NOT show the foreign file the merge pulled in cleanly',
+  !remergeOut181.includes('foreign.txt'));
+
 // --- #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
@@ -255,6 +445,167 @@ const ticketEnginesSource = fs.readFileSync(path.join(sourceSkillsDir, 'trailhea
 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));
@@ -271,6 +622,14 @@ ok('codex: skills/trailhead/hooks/lib/commit-message-check.js exists (commit-gua
   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));
@@ -378,7 +737,7 @@ ok('codex uninstall: hooks.json no longer contains trailhead commands', (() => {
 
 // --- claude regression --------------------------------------------------------
 const claudeDir = mktmp();
-runInstaller([`--claude`, `--dir=${claudeDir}`]);
+const claudeInstallOut = String(runInstaller([`--claude`, `--dir=${claudeDir}`]));
 
 const claudeSkillPath = path.join(claudeDir, 'skills', 'trailhead', 'SKILL.md');
 ok('claude: skills/trailhead/SKILL.md exists', fs.existsSync(claudeSkillPath));
@@ -406,6 +765,12 @@ ok('claude: hooks/lib/commit-message-check.js exists (commit-guard require targe
   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')));
+
+// #185: the commit-msg hook sync script ships wholesale with templates/ too.
+const claudeCommitMsgSync = path.join(claudeDir, 'trailhead', 'templates', 'trailhead-commit-msg-sync.js');
+ok('claude: commit-msg-sync script projected', fs.existsSync(claudeCommitMsgSync));
+ok('claude: commit-msg-sync script is byte-identical to source',
+  fs.readFileSync(claudeCommitMsgSync, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-commit-msg-sync.js'), 'utf8'));
 // 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.
@@ -663,6 +1028,225 @@ try {
 ok('unknown flag after a valid flag: still rejected', unknownAfterValidRejected);
 ok('unknown flag after a valid flag: installs nothing', nothingInstalledUnder(unknownAfterValidDir));
 
+// --- #185: teamwork.md/substrate-commands.md/trailhead-work SKILL.md point at
+// the commit-msg-sync script instead of the old manual copy/chmod steps -------
+ok('source: teamwork.md no longer says an existing hook is never replaced',
+  !teamworkSource.includes('an existing hook is never replaced'));
+ok('source: teamwork.md no longer says reinstalled by hand',
+  !teamworkSource.includes("until it's reinstalled by hand"));
+for (const [label, src] of [
+  ['teamwork.md', teamworkSource],
+  ['substrate-commands.md', substrateCommandsSource],
+  ['trailhead-work/SKILL.md', workSkillSource],
+]) {
+  ok(`source: ${label} references trailhead-commit-msg-sync.js`, src.includes('trailhead-commit-msg-sync.js'));
+  ok(`source: ${label} has no em-dash`, !src.includes('—'));
+}
+
+// --- #182 ---------------------------------------------------------------------
+// A broken install fails loudly (verifyInstall names the gap and the run exits
+// non-zero, printing no "✓ trailhead installed"); a clean one still prints ✓.
+// brokenPkg copies bin/ + plugins/ into a fresh tmp root (so __dirname-relative
+// PKG/SRC resolution in trailhead.js still lines up) and applies a mutation
+// that breaks one source artifact; runPkg drives that copy (or the real repo)
+// through execFileSync without throwing on a non-zero exit.
+function brokenPkg(mutate) {
+  const pkgDir = mktmp();
+  fs.cpSync(path.join(repoRoot, 'bin'), path.join(pkgDir, 'bin'), { recursive: true });
+  fs.cpSync(path.join(repoRoot, 'plugins'), path.join(pkgDir, 'plugins'), { recursive: true });
+  if (mutate) mutate(pkgDir);
+  return pkgDir;
+}
+function runPkg(pkgDir, args, env) {
+  try {
+    const stdout = execFileSync(process.execPath, [path.join(pkgDir, 'bin', 'trailhead.js'), ...args], {
+      cwd: pkgDir, stdio: 'pipe', env: env || process.env,
+    });
+    return { status: 0, stdout: String(stdout), stderr: '' };
+  } catch (e) {
+    return { status: e.status, stdout: String(e.stdout || ''), stderr: String(e.stderr || '') };
+  }
+}
+
+// (a) no engine agents at all: both hosts refuse and print no success line.
+{
+  const noAgentsPkg = brokenPkg((p) => fs.rmSync(path.join(p, 'plugins', 'trailhead', 'agents'), { recursive: true, force: true }));
+  const claudeOut = runPkg(noAgentsPkg, ['--claude', `--dir=${mktmp()}`]);
+  ok('(a) claude, no agents: non-zero exit', claudeOut.status !== 0);
+  ok('(a) claude, no agents: stderr names agents', claudeOut.stderr.includes('agents'));
+  ok('(a) claude, no agents: stdout has no ✓ trailhead installed', !claudeOut.stdout.includes('✓ trailhead installed'));
+  const codexOut = runPkg(noAgentsPkg, ['--codex', `--dir=${mktmp()}`]);
+  ok('(a) codex, no agents: non-zero exit', codexOut.status !== 0);
+  ok('(a) codex, no agents: stderr names agents', codexOut.stderr.includes('agents'));
+  ok('(a) codex, no agents: stdout has no ✓ trailhead installed', !codexOut.stdout.includes('✓ trailhead installed'));
+}
+
+// (b) a cluster's SKILL.md is missing from the source.
+{
+  const pkg = brokenPkg((p) => fs.rmSync(path.join(p, 'plugins', 'trailhead', 'skills', 'trailhead-view', 'SKILL.md'), { force: true }));
+  const out = runPkg(pkg, ['--claude', `--dir=${mktmp()}`]);
+  ok('(b) missing cluster SKILL.md: non-zero exit', out.status !== 0);
+  ok('(b) missing cluster SKILL.md: stderr names trailhead-view/SKILL.md', out.stderr.includes('trailhead-view/SKILL.md'));
+}
+
+// (c) the shared core is missing a file.
+{
+  const pkg = brokenPkg((p) => fs.rmSync(path.join(p, 'plugins', 'trailhead', 'skills', '_shared', 'substrate.md'), { force: true }));
+  const out = runPkg(pkg, ['--claude', `--dir=${mktmp()}`]);
+  ok('(c) missing _shared/substrate.md: non-zero exit', out.status !== 0);
+  ok('(c) missing _shared/substrate.md: stderr names _shared/substrate.md', out.stderr.includes('_shared/substrate.md'));
+}
+
+// (d) a hook script source is missing, fresh dir: named cleanly, no ENOENT stack.
+const missingBodyGuardPkg = brokenPkg((p) => fs.rmSync(path.join(p, 'plugins', 'trailhead', 'hooks', 'trailhead-body-guard.js'), { force: true }));
+{
+  const out = runPkg(missingBodyGuardPkg, ['--claude', `--dir=${mktmp()}`]);
+  ok('(d) missing hook source, fresh dir: non-zero exit', out.status !== 0);
+  ok('(d) missing hook source, fresh dir: stderr names trailhead-body-guard.js', out.stderr.includes('trailhead-body-guard.js'));
+  ok('(d) missing hook source, fresh dir: no ENOENT stack', !out.stderr.includes('ENOENT'));
+}
+
+// (e) reinstalling that same broken package over a prior clean install removes
+// the stale hook file rather than leaving it behind, on both hosts.
+{
+  const xDir = mktmp();
+  runInstaller([`--claude`, `--dir=${xDir}`]);
+  const out = runPkg(missingBodyGuardPkg, ['--claude', `--dir=${xDir}`]);
+  ok('(e) claude reinstall over an old install: non-zero exit', out.status !== 0);
+  ok('(e) claude reinstall: stderr names trailhead-body-guard.js', out.stderr.includes('trailhead-body-guard.js'));
+  ok('(e) claude reinstall: the stale hook file is gone', !fs.existsSync(path.join(xDir, 'hooks', 'trailhead-body-guard.js')));
+
+  const wDir = mktmp();
+  runInstaller([`--codex`, `--dir=${wDir}`]);
+  const outCodex = runPkg(missingBodyGuardPkg, ['--codex', `--dir=${wDir}`]);
+  ok('(e) codex reinstall over an old install: non-zero exit', outCodex.status !== 0);
+  ok('(e) codex reinstall: stderr names trailhead-body-guard.js', outCodex.stderr.includes('trailhead-body-guard.js'));
+  ok('(e) codex reinstall: the stale hook file is gone', !fs.existsSync(path.join(wDir, 'skills', 'trailhead', 'hooks', 'trailhead-body-guard.js')));
+}
+
+// (f) a stale Claude registration in settings.json (target gone).
+{
+  const yDir = mktmp();
+  runInstaller([`--claude`, `--dir=${yDir}`]);
+  const settingsPath = path.join(yDir, 'settings.json');
+  const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  settings.hooks.PreToolUse.push({ matcher: 'Bash', hooks: [
+    { type: 'command', command: `node "${path.join(yDir, 'hooks', 'trailhead-gone-guard.js')}"` },
+  ] });
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  const out = runPkg(repoRoot, [`--claude`, `--dir=${yDir}`]);
+  ok('(f) stale Claude registration: non-zero exit', out.status !== 0);
+  ok('(f) stale Claude registration: stderr names the stale target', out.stderr.includes('trailhead-gone-guard.js'));
+}
+
+// (g) a stale generic Codex registration in hooks.json (target gone).
+{
+  const wgDir = mktmp();
+  runInstaller([`--codex`, `--dir=${wgDir}`]);
+  const hooksJsonPath = path.join(wgDir, 'hooks.json');
+  const hooksJson = JSON.parse(fs.readFileSync(hooksJsonPath, 'utf8'));
+  hooksJson.hooks.PreToolUse.push({ matcher: 'Bash', hooks: [
+    { type: 'command', command: `node "${path.join(wgDir, 'skills', 'trailhead', 'hooks', 'trailhead-gone-guard.js')}"` },
+  ] });
+  fs.writeFileSync(hooksJsonPath, JSON.stringify(hooksJson, null, 2));
+  const out = runPkg(repoRoot, [`--codex`, `--dir=${wgDir}`]);
+  ok('(g) stale Codex registration: non-zero exit', out.status !== 0);
+  ok('(g) stale Codex registration: stderr names the stale target', out.stderr.includes('trailhead-gone-guard.js'));
+  ok('(g) stale Codex registration: stderr names hooks.json', out.stderr.includes('hooks.json'));
+}
+
+// (h) the pre-#169 search-guard registration migrates away silently on reinstall.
+// May already pass before the installer wires verifyInstall in (no check exists
+// yet to trip on it); it stays here to pin the migration's intent regardless.
+{
+  const zDir = mktmp();
+  runInstaller([`--codex`, `--dir=${zDir}`]);
+  const hooksJsonPath = path.join(zDir, 'hooks.json');
+  const hooksJson = JSON.parse(fs.readFileSync(hooksJsonPath, 'utf8'));
+  hooksJson.hooks.PreToolUse.push({ matcher: 'Bash', hooks: [
+    { type: 'command', command: `node "${path.join(zDir, 'skills', 'trailhead', 'hooks', 'trailhead-search-guard.js')}"` },
+  ] });
+  fs.writeFileSync(hooksJsonPath, JSON.stringify(hooksJson, null, 2));
+  const out = runPkg(repoRoot, [`--codex`, `--dir=${zDir}`]);
+  ok('(h) pre-#169 search-guard migration: exit 0', out.status === 0);
+  ok('(h) pre-#169 search-guard migration: prints ✓', out.stdout.includes('✓'));
+  const afterHooksJson = fs.readFileSync(hooksJsonPath, 'utf8');
+  ok('(h) pre-#169 search-guard migration: the stale entry is gone', !afterHooksJson.includes('trailhead-search-guard.js'));
+}
+
+// (i) an unresolved env var on a registered target warns instead of failing.
+{
+  const vDir = mktmp();
+  runInstaller([`--claude`, `--dir=${vDir}`]);
+  const settingsPath = path.join(vDir, 'settings.json');
+  const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  settings.hooks.PreToolUse.push({ matcher: 'Bash', hooks: [
+    { type: 'command', command: 'node "${TRAILHEAD_T182_UNSET}/hooks/trailhead-x-guard.js"' },
+  ] });
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  // Delete the key outright (never set it to undefined), so the child process
+  // never receives a literal "undefined" string for it.
+  const envWithoutVar = { ...process.env };
+  delete envWithoutVar.TRAILHEAD_T182_UNSET;
+  const out = runPkg(repoRoot, [`--claude`, `--dir=${vDir}`], envWithoutVar);
+  ok('(i) unresolved env var: exit 0', out.status === 0);
+  ok('(i) unresolved env var: prints ✓', out.stdout.includes('✓'));
+  ok('(i) unresolved env var: stdout warns ⚠ unverified', out.stdout.includes('⚠ unverified'));
+  ok('(i) unresolved env var: stdout names the unresolved variable', out.stdout.includes('TRAILHEAD_T182_UNSET'));
+}
+
+// (j) regression: the existing clean installs at the top of this file still
+// print ✓ with no ⚠ unverified.
+ok('(j) claude clean install: prints ✓ trailhead installed', claudeInstallOut.includes('✓ trailhead installed'));
+ok('(j) claude clean install: no ⚠ unverified', !claudeInstallOut.includes('⚠ unverified'));
+ok('(j) codex clean install: prints ✓ trailhead installed', codexInstallOut.includes('✓ trailhead installed'));
+ok('(j) codex clean install: no ⚠ unverified', !codexInstallOut.includes('⚠ unverified'));
+
+// --- #183: severity counts and per-finding disposition gate on Resolve -------
+// Code review classifies findings as Critical/Warning/Info, but only Criticals
+// gated resolution and Warnings/Info were never tracked to a decision. Pin the
+// counts line under `status:`, the disposition vocabulary, and the Resolve gate
+// that requires every counted finding to carry one before a ticket can close.
+const codeReviewSourcePath183 = path.join(sourceSkillsDir, '_shared', 'techniques', 'code-review.md');
+const codeReviewSource183 = fs.readFileSync(codeReviewSourcePath183, 'utf8');
+const ticketEnginesSource183 = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-work', 'references', 'ticket-engines.md'), 'utf8');
+
+ok('code-review.md states the counts format right under the status tag',
+  codeReviewSource183.includes('critical: <n> · warning: <n> · info: <n>'));
+ok('code-review.md says the counts line sits right under the status tag',
+  /right under[^.]*`status:`/.test(codeReviewSource183) || /`status:`[^.]*right under/.test(codeReviewSource183));
+
+ok('code-review.md names the fixed disposition', codeReviewSource183.includes('`fixed`'));
+ok('code-review.md names the deferred disposition', codeReviewSource183.includes('`deferred → <ticket>`'));
+ok('code-review.md names the accepted disposition', codeReviewSource183.includes('`accepted: <one-line reason>`'));
+ok('code-review.md names the transient open disposition', codeReviewSource183.includes('`open`'));
+
+ok('code-review.md says finding IDs are stable across rounds',
+  /stable/i.test(codeReviewSource183) && /across (every|fix-and-re-review) round/i.test(codeReviewSource183));
+ok('code-review.md says the counts are cumulative', codeReviewSource183.includes('cumulative'));
+ok('code-review.md says no finding reaches Resolve with open or without a disposition',
+  /no finding reaches Resolve with[^.]*`open`[^.]*without a disposition/.test(codeReviewSource183));
+
+ok('code-review.md no longer defers Warnings/Info as "noted for the caller to weigh"',
+  !codeReviewSource183.includes('noted for the caller to weigh'));
+
+const verifyStepLines183 = ticketEnginesSource183.split('\n').filter((l) => l.trim().startsWith('4. **Verify**'));
+ok('ticket-engines.md has exactly two Verify (step 4) lines', verifyStepLines183.length === 2);
+ok('both Verify step lines mention the counts line',
+  verifyStepLines183.every((l) => l.includes('counts line')));
+
+const resolveStepLines183 = ticketEnginesSource183.split('\n').filter((l) => l.trim().startsWith('5. **Resolve**'));
+ok('ticket-engines.md has exactly two Resolve (step 5) lines', resolveStepLines183.length === 2);
+ok('both Resolve step lines carry the Disposition gate',
+  resolveStepLines183.every((l) => l.includes('**Disposition gate (before the close)**')));
+
+for (const [label, src] of [
+  ['code-review.md', codeReviewSource183],
+  ['ticket-engines.md', ticketEnginesSource183],
+]) {
+  ok(`${label} has no em-dash (#183)`, !src.includes('\u2014'));
+}
+
 // --- cleanup -------------------------------------------------------------------
 for (const d of tmpDirs) {
   fs.rmSync(d, { recursive: true, force: true });