@marcomigozzi/trailhead 0.10.0 → 0.11.1

package/bin/trailhead.test.js

@@ -52,9 +52,42 @@ function fakeBinDir(names) {
   return dir;
 }
 
+// #187: the pinned-model review's documented lib path (see load-first.md) is
+// relative to a skills/_shared/ dir; assert it actually resolves on every
+// install layout, survives realpathSync, and its check/ack CLI round-trips.
+const MODEL_DEFAULTS_LIB_CANDIDATES = [
+  '../../hooks/lib/model-defaults-review.js',
+  '../trailhead/hooks/lib/model-defaults-review.js',
+];
+function assertModelDefaultsLibLayout(label, sharedDir) {
+  const resolved = MODEL_DEFAULTS_LIB_CANDIDATES
+    .map((c) => path.join(sharedDir, c))
+    .find((p) => fs.existsSync(p));
+  ok(`${label}: documented model-defaults-review.js lib path resolves`, !!resolved);
+  if (!resolved) return;
+  ok(`${label}: resolved lib path still resolves after realpathSync`,
+    fs.existsSync(fs.realpathSync(resolved)));
+
+  const tmpProject = mktmp();
+  fs.mkdirSync(path.join(tmpProject, '.trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(tmpProject, '.trailhead', 'config.json'),
+    JSON.stringify({ models: { plan: 'claude-opus-4-8' } }));
+
+  const noticeOut = String(execFileSync(process.execPath, [resolved, 'check', tmpProject], { encoding: 'utf8' }));
+  ok(`${label}: CLI check prints a notice`, noticeOut.trim().length > 0 && noticeOut.includes('models.plan'));
+
+  execFileSync(process.execPath, [resolved, 'ack', tmpProject], { encoding: 'utf8' });
+  const afterAckOut = String(execFileSync(process.execPath, [resolved, 'check', tmpProject], { encoding: 'utf8' }));
+  ok(`${label}: CLI check prints nothing after CLI ack`, afterAckOut === '');
+}
+
+// Source/plugin layout itself (not an installed copy), so drift is caught
+// even before an install is exercised.
+assertModelDefaultsLibLayout('source', path.join(repoRoot, 'plugins', 'trailhead', 'skills', '_shared'));
+
 // --- 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 +118,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,8 +245,8 @@ 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 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 offers /trailhead:quick as the lighter alternative, after the work anchor',
+  /[Aa]nchor the next step to `\/trailhead:work <n>`[\s\S]{0,400}`\/trailhead:quick <n>` is the \*\*lighter 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));
 
@@ -238,6 +277,180 @@ 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));
 
+// --- quick is the lighter path, never "just without splitting" --------------
+// Source-level invariant: wherever a next-step suggestion characterizes quick,
+// it names what quick is for (the lighter path: always size-triaged, offers to
+// skip the heavy steps on a small change, no map book-keeping), with no-split
+// as a side note. The old "only the no-split alternative" / "same work as
+// work, without split" framing made agents tell users quick merely avoids
+// splitting.
+const dispatcherSourceForQuick = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead', 'SKILL.md'), 'utf8');
+ok('source: capture.md drops the "only the no-split alternative" framing', !/only\*\* the no-split alternative/.test(captureSource));
+ok('source: session-handoff.md drops the "as the no-split alternative" framing', !sessionHandoffSource.includes('as the no-split alternative'));
+ok('source: dispatcher SKILL.md drops the "as the no-split alternative" framing', !dispatcherSourceForQuick.includes('as the no-split alternative'));
+ok('source: session-handoff.md example drops "lo stesso lavoro di `work`, senza split"', !sessionHandoffSource.includes('lo stesso lavoro di `work`, senza split'));
+ok('source: capture.md says quick offers to skip the heavy steps on a small change', /quick <n>`[\s\S]{0,400}skip the heavy steps/.test(captureSource));
+ok('source: capture.md forbids describing quick as merely avoiding a split', /never as merely "without splitting"/.test(captureSource));
+ok('source: session-handoff.md forbids describing quick as merely avoiding a split', /never as merely "without splitting"/.test(sessionHandoffSource));
+ok('source: session-handoff.md example renders quick as the lighter path', /> - oppure `\/trailhead:quick[^\n]*percorso leggero/.test(sessionHandoffSource));
+
+// --- #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
@@ -459,6 +672,10 @@ 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')));
+ok('codex: skills/trailhead/hooks/lib/model-defaults-review.js exists (check-update require target, #186)',
+  fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'model-defaults-review.js')));
+ok('codex: skills/trailhead/hooks/lib/model-defaults.json exists (#186)',
+  fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'model-defaults.json')));
 // #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.
@@ -485,6 +702,8 @@ ok('codex: trailhead-codebase-map.toml is projected with no models.codex.* set',
 ok('codex: trailhead-fix.toml is pin-less (no model = line) with no models.codex.* set',
   fs.existsSync(noPinFixTomlPath) && !/^model = /m.test(fs.readFileSync(noPinFixTomlPath, 'utf8')));
 
+assertModelDefaultsLibLayout('codex copy', path.join(codexDir, 'skills', '_shared'));
+
 // --- codex --symlink: link verbatim artifacts (hooks + templates), keep skills projected ---
 const codexSymDir = mktmp();
 runInstaller([`--codex`, `--symlink`, `--dir=${codexSymDir}`]);
@@ -509,6 +728,8 @@ ok('codex copy: hooks are regular files (not symlinks)',
 ok('codex copy: templates is a regular dir (not a symlink)',
   !fs.lstatSync(path.join(codexDir, 'skills', 'trailhead', 'templates')).isSymbolicLink());
 
+assertModelDefaultsLibLayout('codex symlink', path.join(codexSymDir, 'skills', '_shared'));
+
 // --- codex agent TOML projection (#38, #88) -------------------------------------
 // With NO models.codex.* set, a codex install still projects all 8 agents
 // uniformly, pin-less (uniform projection, #88), never zero. Install from an
@@ -574,7 +795,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 +823,16 @@ 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')));
+ok('claude: hooks/lib/model-defaults-review.js exists (check-update require target, #186)',
+  fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'model-defaults-review.js')));
+ok('claude: hooks/lib/model-defaults.json exists (#186)',
+  fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'model-defaults.json')));
+
+// #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.
@@ -631,6 +862,8 @@ ok('claude: agent file registers its subagent name in frontmatter',
 ok('claude: agents are real files on a copy install (not symlinks)',
   !fs.lstatSync(path.join(claudeAgentsDir, 'trailhead-plan.md')).isSymbolicLink());
 
+assertModelDefaultsLibLayout('claude copy', path.join(claudeDir, 'skills', '_shared'));
+
 // --- claude --symlink: dev install links hooks live too (not just skills/commands) ---
 const symDir = mktmp();
 runInstaller([`--claude`, `--symlink`, `--dir=${symDir}`]);
@@ -664,6 +897,8 @@ ok('claude symlink: agent symlink resolves into the package source',
 ok('claude copy: hooks/trailhead-secret-guard.js is a regular file (not a symlink)',
   !fs.lstatSync(path.join(claudeDir, 'hooks', 'trailhead-secret-guard.js')).isSymbolicLink());
 
+assertModelDefaultsLibLayout('claude symlink', path.join(symDir, 'skills', '_shared'));
+
 // --- claude migration: reinstall over an old layout sweeps stale skill dirs ---
 // An old install may carry a pre-split monolith (skills/trailhead-monolith) or a
 // removed cluster (skills/trailhead-legacy) the current install no longer ships.
@@ -859,6 +1094,267 @@ 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('—'));
+}
+
+// --- #189: script mancante / errore node -> fallback che ispeziona la hooks dir
+// invece di dichiarare alla cieca "git non applica le regole" ------------------
+ok('source: teamwork.md fallback resolves the hooks dir via rev-parse --git-path hooks',
+  teamworkSource.includes('git -C <working-root> rev-parse --git-path hooks'));
+ok('source: teamwork.md fallback classifies by the trailhead header line',
+  teamworkSource.includes('// trailhead commit-msg hook (git).'));
+ok('source: teamwork.md fallback checks the executable bit (test -x)',
+  teamworkSource.includes('test -x'));
+ok('source: teamwork.md fallback reads only the first 5 lines',
+  teamworkSource.includes('first 5 lines'));
+ok('source: teamwork.md fallback treats a symlinked commit-msg as foreign',
+  teamworkSource.includes('symlinked `commit-msg`'));
+for (const [label, src] of [
+  ['trailhead-work/SKILL.md', workSkillSource],
+  ['substrate-commands.md', substrateCommandsSource],
+]) {
+  ok(`source: ${label} mentions the missing-script hooks-dir fallback`,
+    src.includes('rev-parse --git-path hooks') && /missing script or a node error|script is missing or node errors/.test(src));
+  ok(`source: ${label} has no em-dash (#189)`, !src.includes('—'));
+}
+ok('source: teamwork.md has no em-dash (#189)', !teamworkSource.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'));
+}
+
+// --- plan-review: "run until it converges" option at the rounds-exhausted ask ---
+const planReviewSourceConv = fs.readFileSync(path.join(sourceSkillsDir, '_shared', 'techniques', 'plan-review.md'), 'utf8');
+const planReviewStep4 = planReviewSourceConv.split('\n').find((l) => l.startsWith('4. **Record and decide.**')) || '';
+ok('plan-review.md step 4 still offers another bounded review cycle', planReviewStep4.includes('run another review cycle'));
+ok('plan-review.md step 4 offers running until the plan converges', /\(d\) \*\*run until it converges\*\*/.test(planReviewStep4));
+ok('plan-review.md converge option stops when no blocking concern remains', /run until it converges[\s\S]{0,400}no blocking concern remains/.test(planReviewStep4));
+ok('plan-review.md converge option has a no-progress guard that returns to this checkpoint',
+  /run until it converges[\s\S]{0,600}no progress[\s\S]{0,300}back to this checkpoint/.test(planReviewStep4));
+ok('plan-review.md step 4 has no em-dash', !planReviewStep4.includes('\u2014'));
+
+// --- code-review: "run until it converges" option at the rounds-exhausted ask ---
+const codeReviewSourceConv = fs.readFileSync(path.join(sourceSkillsDir, '_shared', 'techniques', 'code-review.md'), 'utf8');
+const codeReviewBoundary = codeReviewSourceConv.split('\n').find((l) => l.startsWith('**Converge on the blockers')) || '';
+ok('code-review.md boundary ask still offers another 2 review rounds', codeReviewBoundary.includes('run another 2 review rounds'));
+ok('code-review.md boundary ask offers running until it converges', /\(c\) \*\*run until it converges\*\*/.test(codeReviewBoundary));
+ok('code-review.md converge option stops when no Critical remains', /run until it converges[\s\S]{0,400}no Critical remains/.test(codeReviewBoundary));
+ok('code-review.md converge option has a no-progress guard that returns to this checkpoint',
+  /run until it converges[\s\S]{0,600}no progress[\s\S]{0,300}back to this checkpoint/.test(codeReviewBoundary));
+ok('code-review.md boundary ask has no em-dash', !codeReviewBoundary.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.1",
   "description": "Start and drive large projects as a map of tickets on GitHub Issues. Map-based onboarding + a discuss→plan→execute→verify engine, all on the Issues. Installs the trailhead skill, commands, and hooks into your agent's config dir.",
   "bin": {
     "trailhead": "bin/trailhead.js"

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

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