@marcomigozzi/trailhead 0.10.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
@@ -238,6 +244,163 @@ ok('source: capture.md says a map ticket stays on its map', /a map ticket stays
 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
@@ -574,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));
@@ -602,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.
@@ -859,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 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcomigozzi/trailhead",
-  "version": "0.10.0",
+  "version": "0.11.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.10.0",
+  "version": "0.11.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/hooks/lib/commit-message-check.js

@@ -5,13 +5,18 @@
 //   - templates/trailhead-commit-msg    (host-independent git commit-msg hook,
 //     installed into .git/hooks at repo first-use so it runs on ANY host)
 // Two rules: NEVER a Co-Authored-By trailer; a Conventional Commits subject
-// (<type>(scope)?: subject) of at most 72 chars.
+// (<type>(scope)?: subject) of at most 72 chars. Plus a conditional third rule:
+// while a ticket is active (a caller passes opts.ticket, resolved from the
+// .trailhead/session-ticket marker), the message must carry a matching
+// `Refs: #<n>` trailer, so every commit made while resolving a ticket threads
+// into that ticket's timeline.
 // Pure and dependency-free: takes a commit message string, returns a verdict.
 
 const TYPES = 'feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert';
 const CONVENTIONAL = new RegExp(`^(${TYPES})(\\([^)]+\\))?!?:\\s.+`);
 const CO_AUTHORED = /co-authored-by\s*:/i;
 const SCISSORS = '# ------------------------ >8';
+const REFS_LINE = /^\s*refs\s*:(.*)$/i;
 
 // The message region: everything before git's --verbose scissors line (the
 // block after it is the diff, not the message). Everything else is kept, so a
@@ -39,11 +44,46 @@ function subjectOf(raw, opts = {}) {
   return '';
 }
 
+// parseSessionTicket(text) -> ticket number | null
+// Parses the first line of a .trailhead/session-ticket marker (`#<n> <title>`).
+// Strips a leading BOM and any trailing \r before matching, so a marker read
+// with either line-ending convention parses the same way. Anything else
+// (empty text, no leading '#', a non-digit, a leading zero, or trailing
+// characters glued to the digits) is not a valid marker and yields null.
+function parseSessionTicket(text) {
+  const raw = String(text == null ? '' : text).replace(/^/, '');
+  const firstLine = raw.split('\n')[0].replace(/\r$/, '');
+  const m = firstLine.match(/^#([1-9]\d*)(?:\s|$)/);
+  return m ? Number(m[1]) : null;
+}
+
+// hasRefsFor(message, n) -> boolean
+// Scans the message region (see messageRegion) for a `Refs:` trailer line
+// whose value contains `#<n>` not immediately followed by another word
+// character (so `#184` matches but `#18` and `#184abc` do not). A `#`-leading
+// line never counts: it is a git comment in a commit-msg file, and a
+// `# Refs: ...` line is not a trailer in a literal `-m` string either.
+function hasRefsFor(message, n) {
+  const target = new RegExp('#' + n + '(?![\\w])');
+  for (const line of messageRegion(message).split('\n')) {
+    if (line.trim().startsWith('#')) continue;
+    const m = line.match(REFS_LINE);
+    if (m && target.test(m[1])) return true;
+  }
+  return false;
+}
+
 // checkCommitMessage(message, opts?) -> { ok: true } | { ok: false, code, reason }
 // opts.stripComments is forwarded to subjectOf (see there): the git commit-msg
 // hook uses the default (file semantics); the PreToolUse `-m` guard passes false.
+// opts.ticket activates the Refs rule when it is a positive integer (the
+// ticket resolved from a live .trailhead/session-ticket marker); any other
+// value (undefined, a non-integer, a string, 0, negative) leaves the rule off,
+// it never blocks by mistake. When active it applies even to an empty
+// message, closing a `--allow-empty-message` bypass.
 function checkCommitMessage(message, opts = {}) {
   const region = messageRegion(message);
+  const ticketActive = Number.isInteger(opts.ticket) && opts.ticket > 0;
 
   if (CO_AUTHORED.test(region)) {
     return {
@@ -68,7 +108,23 @@ function checkCommitMessage(message, opts = {}) {
       reason: 'trailhead: commit subject must be 72 characters or less.',
     };
   }
+  if (ticketActive && !hasRefsFor(message, opts.ticket)) {
+    return {
+      ok: false,
+      code: 'REFS_TRAILER_MISSING',
+      reason: `trailhead: this commit is on ticket #${opts.ticket} (per .trailhead/session-ticket) but has no "Refs: #${opts.ticket}" trailer. Add "Refs: #${opts.ticket}" as the last line of the message and commit again. If this commit is not part of ticket #${opts.ticket}, remove the stale .trailhead/session-ticket marker first.`,
+    };
+  }
   return { ok: true };
 }
 
-module.exports = { checkCommitMessage, subjectOf, messageRegion, TYPES, CONVENTIONAL, CO_AUTHORED };
+module.exports = {
+  checkCommitMessage,
+  subjectOf,
+  messageRegion,
+  parseSessionTicket,
+  hasRefsFor,
+  TYPES,
+  CONVENTIONAL,
+  CO_AUTHORED,
+};