@marcomigozzi/trailhead 0.16.1 → 0.18.0

package/bin/trailhead.test.js

@@ -60,6 +60,11 @@ const MODEL_DEFAULTS_LIB_CANDIDATES = [
   '../trailhead/hooks/lib/model-defaults-review.js',
 ];
 function assertModelDefaultsLibLayout(label, sharedDir) {
+  // #323: model-route.js is resolved with the same two-path lookup (grilling.md).
+  const routeResolved = MODEL_DEFAULTS_LIB_CANDIDATES
+    .map((c) => path.join(sharedDir, c.replace('model-defaults-review.js', 'model-route.js')))
+    .find((p) => fs.existsSync(p));
+  ok(`${label}: documented model-route.js lib path resolves`, !!routeResolved);
   const resolved = MODEL_DEFAULTS_LIB_CANDIDATES
     .map((c) => path.join(sharedDir, c))
     .find((p) => fs.existsSync(p));
@@ -234,7 +239,9 @@ ok('codex: trailhead-work/../_shared/substrate.md resolves', fs.existsSync(path.
 ok('codex: _shared/load-first.md projected', fs.existsSync(path.join(codexDir, 'skills', '_shared', 'load-first.md')));
 for (const cl of ['trailhead', 'trailhead-chart', 'trailhead-work', 'trailhead-view', 'trailhead-capture', 'trailhead-manage']) {
   ok(`codex: ${cl}/../_shared/load-first.md resolves as a sibling`, fs.existsSync(path.join(codexDir, 'skills', cl, '..', '_shared', 'load-first.md')));
-  ok(`codex: ${cl} SKILL.md references ../_shared/load-first.md`, fs.readFileSync(path.join(codexDir, 'skills', cl, 'SKILL.md'), 'utf8').includes('../_shared/load-first.md'));
+  // #330: the capture cluster loads the compact capture-core.md instead.
+  const want = cl === 'trailhead-capture' ? '../_shared/capture-core.md' : '../_shared/load-first.md';
+  ok(`codex: ${cl} SKILL.md references ${want}`, fs.readFileSync(path.join(codexDir, 'skills', cl, 'SKILL.md'), 'utf8').includes(want));
 }
 // Source-level anti-drift: the shared core-list signature line lives ONLY in
 // _shared/load-first.md, never duplicated back into a cluster SKILL.md.
@@ -293,7 +300,8 @@ ok('source: load-first.md references ../_shared/ticket-language.md', loadFirstSo
 const ticketLangAutoSource = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-work', 'references', 'auto.md'), 'utf8');
 const ticketLangCaptureSource = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-capture', 'references', 'capture.md'), 'utf8');
 ok('source: auto.md references ticket-language.md', ticketLangAutoSource.includes('ticket-language.md'));
-ok('source: capture.md references ticket-language.md', ticketLangCaptureSource.includes('ticket-language.md'));
+// #330: capture.md points at the compact capture-core.md, which is drift-stamped against ticket-language.md.
+ok('source: capture.md references capture-core.md for the ticket language', ticketLangCaptureSource.includes('ticket language rule in `capture-core.md`') && /<!-- core: ticket-language\.md \|/.test(fs.readFileSync(path.join(sourceSkillsDir, '_shared', 'capture-core.md'), 'utf8')));
 // Source-level anti-drift: the substantive decoupling clause lives in EXACTLY
 // one file across the whole skills tree, _shared/ticket-language.md. A global
 // single-occurrence scan (not an enumerated per-file list) so any future doc
@@ -463,7 +471,7 @@ ok('both Verify step lines reference the Ticket diff', verifyStepLines181.every(
 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"));
+  techniquesSource181.includes("review the ticket's own commits (its `Refs: #<n>` set) on 5 axes"));
 
 for (const [label, src] of [
   ['code-review.md', codeReviewSource181],
@@ -912,7 +920,7 @@ ok('codex: hooks.json exists', fs.existsSync(codexHooksJsonPath));
 const codexHooksJson = JSON.parse(fs.readFileSync(codexHooksJsonPath, 'utf8'));
 const codexHooksJsonStr = JSON.stringify(codexHooksJson);
 ok('codex: hooks.json registers the merged Bash guards under PreToolUse', (codexHooksJson.hooks.PreToolUse || []).some((g) => g.matcher === 'Bash' &&
-  (g.hooks || []).some((h) => h.command.includes('trailhead-bash-guards.js') && h.command.endsWith(' --guards=commit,secret,install,body,labels'))));
+  (g.hooks || []).some((h) => h.command.includes('trailhead-bash-guards.js') && h.command.endsWith(' --guards=commit,secret,install,body,labels,test'))));
 ok('codex: hooks.json registers none of the per-guard scripts on their own', !/trailhead-(commit|secret|install|search|body|labels)-guard\.js/.test(codexHooksJsonStr));
 ok('codex: the six guard modules the merged hook requires are still shipped (no search)',
   ['commit', 'secret', 'install', 'body', 'labels'].every((n) => fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', `trailhead-${n}-guard.js`))) &&
@@ -941,6 +949,10 @@ ok('codex: skills/trailhead/hooks/lib/body-sources.js exists (secret-guard requi
   fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'body-sources.js')));
 ok('codex: skills/trailhead/hooks/lib/unmodelled.js exists (guards require target, #227)',
   fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'unmodelled.js')));
+ok('codex: skills/trailhead/hooks/lib/inherit-session.js exists (required by model-route and model-defaults-review, #323)',
+  fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'inherit-session.js')));
+ok('codex: skills/trailhead/hooks/lib/model-route.js exists (grilling routing helper, #323)',
+  fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'model-route.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)',
@@ -960,6 +972,10 @@ ok('codex: skills/trailhead/hooks/trailhead-mockup-link-stop.js exists',
   fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'trailhead-mockup-link-stop.js')));
 ok('codex: skills/trailhead/hooks/lib/mockup-link.js exists (mockup-link-stop require target)',
   fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'mockup-link.js')));
+ok('codex: skills/trailhead/hooks/lib/gh-auth-preflight.js exists (check-update require target)',
+  fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'gh-auth-preflight.js')));
+ok('codex: skills/trailhead/hooks/lib/trailhead-git-env.js exists (check-update require target)',
+  fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'trailhead-git-env.js')));
 ok('codex: skills/trailhead/hooks/trailhead-mockup-link-guard.js does NOT exist',
   !fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'trailhead-mockup-link-guard.js')));
 ok('codex: skills/trailhead/hooks/lib/shell-scan.js still exists (secret-read-guard require target)',
@@ -979,8 +995,15 @@ const noPinFixTomlPath = path.join(codexAgentsDirPath, 'trailhead-fix.toml');
 const noPinMapTomlPath = path.join(codexAgentsDirPath, 'trailhead-codebase-map.toml');
 ok('codex: trailhead-fix.toml is projected with no models.codex.* set', fs.existsSync(noPinFixTomlPath));
 ok('codex: trailhead-codebase-map.toml is projected with no models.codex.* set', fs.existsSync(noPinMapTomlPath));
-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')));
+// #325: fix non ha chiave propria, porta lo stesso pin di execute (la config del
+// repo puo' impostarlo, quindi si confrontano le due righe model, qualunque sia).
+const modelLine325 = (f) => (fs.readFileSync(f, 'utf8').match(/^model = .*$/m) || [''])[0];
+const effortLine325 = (f) => (fs.readFileSync(f, 'utf8').match(/^model_reasoning_effort = .*$/m) || [''])[0];
+const executeTomlPath325 = path.join(codexAgentsDirPath, 'trailhead-execute.toml');
+ok('codex: trailhead-fix.toml carries the same model pin as trailhead-execute.toml (fix tracks execute, #325)',
+  fs.existsSync(noPinFixTomlPath) && fs.existsSync(executeTomlPath325) &&
+  modelLine325(noPinFixTomlPath) === modelLine325(executeTomlPath325) &&
+  effortLine325(noPinFixTomlPath) === effortLine325(executeTomlPath325));
 
 assertModelDefaultsLibLayout('codex copy', path.join(codexDir, 'skills', '_shared'));
 
@@ -1011,7 +1034,7 @@ ok('codex copy: templates is a regular dir (not a symlink)',
 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
+// With NO models.codex.* set, a codex install still projects all 9 agents
 // uniformly, pin-less (uniform projection, #88), never zero. Install from an
 // isolated cwd whose .trailhead/config.json sets no models.codex.*, not
 // repoRoot (whose own config now pins models.codex.*, so it would project
@@ -1024,11 +1047,11 @@ fs.writeFileSync(
 );
 const unsetCodexHomeDir = mktmp();
 runInstaller([`--codex`, `--dir=${unsetCodexHomeDir}`], { cwd: unsetProjectDir });
-ok('codex: all 8 trailhead-*.toml exist under agents/ even with models.codex.* unset', (() => {
+ok('codex: all 9 trailhead-*.toml exist under agents/ even with models.codex.* unset', (() => {
   const dir = path.join(unsetCodexHomeDir, 'agents');
   if (!fs.existsSync(dir)) return false;
   const tomls = fs.readdirSync(dir).filter((f) => /^trailhead-.*\.toml$/.test(f));
-  return tomls.length === 8;
+  return tomls.length === 9;
 })());
 ok('codex: every trailhead-*.toml is pin-less when models.codex.* is unset', (() => {
   const dir = path.join(unsetCodexHomeDir, 'agents');
@@ -1037,7 +1060,7 @@ ok('codex: every trailhead-*.toml is pin-less when models.codex.* is unset', (()
 })());
 
 // #250: the reviewing block (single source scripts/agent-blocks.md) is projected
-// verbatim into the two reviewing agents' TOMLs and into none of the other six.
+// verbatim into the two reviewing agents' TOMLs and into none of the other seven.
 {
   const sync250 = require(path.join(repoRoot, 'scripts', 'sync-agent-blocks.js'));
   const reviewingBlock250 = sync250.parseSource(fs.readFileSync(path.join(repoRoot, 'scripts', 'agent-blocks.md'), 'utf8')).reviewing;
@@ -1045,7 +1068,7 @@ ok('codex: every trailhead-*.toml is pin-less when models.codex.* is unset', (()
   const agentsDir250 = path.join(unsetCodexHomeDir, 'agents');
   const reviewingNames250 = new Set(['trailhead-verify', 'trailhead-review']); // the code-review agent projects as trailhead-review.toml
   const tomls250 = fs.readdirSync(agentsDir250).filter((f) => /^trailhead-.*\.toml$/.test(f));
-  ok('#250: all 8 TOMLs are checked', tomls250.length === 8);
+  ok('#250: all 9 TOMLs are checked', tomls250.length === 9);
   for (const f of tomls250) {
     const name = f.replace(/\.toml$/, '');
     const text = fs.readFileSync(path.join(agentsDir250, f), 'utf8');
@@ -1065,6 +1088,15 @@ ok('codex migration: stale prompts/trailhead.md swept on install', !fs.existsSyn
 ok('codex migration: stale prompts/trailhead-work.md swept on install', !fs.existsSync(path.join(migCodexDir, 'prompts', 'trailhead-work.md')));
 ok('codex migration: per-verb skill projected in its place', fs.existsSync(path.join(migCodexDir, 'skills', 'trailhead-work', 'SKILL.md')));
 
+// La config globale di Codex sta nella cartella del vecchio motore: un aggiornamento non deve cancellarla.
+const keepCodexDir = mktmp();
+fs.mkdirSync(path.join(keepCodexDir, 'trailhead', 'references'), { recursive: true });
+fs.writeFileSync(path.join(keepCodexDir, 'trailhead', 'references', 'old.md'), 'stale engine\n');
+fs.writeFileSync(path.join(keepCodexDir, 'trailhead', 'config.json'), '{"testing":{"full":"npm test"}}\n');
+runInstaller([`--codex`, `--dir=${keepCodexDir}`]);
+ok('codex install: global config survives', fs.existsSync(path.join(keepCodexDir, 'trailhead', 'config.json')));
+ok('codex install: old engine files still swept', !fs.existsSync(path.join(keepCodexDir, 'trailhead', 'references')));
+
 // codex migration: a stale trailhead-owned skill dir (pre-split monolith /
 // removed cluster) is swept on reinstall; a co-tenant skill is preserved.
 const migCodexSkillDir = mktmp();
@@ -1108,7 +1140,8 @@ ok('claude: cluster ../_shared/ reference resolves', fs.existsSync(path.join(cla
 ok('claude: skills/_shared/load-first.md exists', fs.existsSync(path.join(claudeDir, 'skills', '_shared', 'load-first.md')));
 ok('claude: trailhead-work/../_shared/load-first.md resolves', fs.existsSync(path.join(claudeDir, 'skills', 'trailhead-work', '..', '_shared', 'load-first.md')));
 for (const cl of ['trailhead', 'trailhead-chart', 'trailhead-work', 'trailhead-view', 'trailhead-capture', 'trailhead-manage']) {
-  ok(`claude: ${cl} SKILL.md references ../_shared/load-first.md`, fs.readFileSync(path.join(claudeDir, 'skills', cl, 'SKILL.md'), 'utf8').includes('../_shared/load-first.md'));
+  const want = cl === 'trailhead-capture' ? '../_shared/capture-core.md' : '../_shared/load-first.md';
+  ok(`claude: ${cl} SKILL.md references ${want}`, fs.readFileSync(path.join(claudeDir, 'skills', cl, 'SKILL.md'), 'utf8').includes(want));
 }
 
 // #146: single-sourced ticket-language directive, projected on Claude too.
@@ -1128,6 +1161,10 @@ ok('claude: hooks/lib/body-sources.js exists (secret-guard require target, #210)
   fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'body-sources.js')));
 ok('claude: hooks/lib/unmodelled.js exists (guards require target, #227)',
   fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'unmodelled.js')));
+ok('claude: hooks/lib/inherit-session.js exists (required by model-route and model-defaults-review, #323)',
+  fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'inherit-session.js')));
+ok('claude: hooks/lib/model-route.js exists (grilling routing helper, #323)',
+  fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'model-route.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)',
@@ -1185,7 +1222,7 @@ ok('claude: SKILL.md does not start with the codex adapter header', !fs.readFile
 // falls back to running inline on the session model, so the per-technique
 // config.models.* split silently never applies.
 const claudeAgentsDir = path.join(claudeDir, 'agents');
-const expectedAgents = ['trailhead-plan', 'trailhead-executor', 'trailhead-research', 'trailhead-code-review', 'trailhead-debug', 'trailhead-fix', 'trailhead-codebase-map'];
+const expectedAgents = ['trailhead-plan', 'trailhead-executor', 'trailhead-research', 'trailhead-code-review', 'trailhead-debug', 'trailhead-fix', 'trailhead-codebase-map', 'trailhead-grill'];
 for (const a of expectedAgents) {
   ok(`claude: agents/${a}.md placed`, fs.existsSync(path.join(claudeAgentsDir, `${a}.md`)));
 }
@@ -1309,12 +1346,14 @@ ok('claude: exactly one PreToolUse/Bash trailhead-bash-guards registration', (()
   const s = JSON.parse(settingsContent);
   return (s.hooks.PreToolUse || []).flatMap((g) => g.hooks || []).filter((h) => h.command.includes('trailhead-bash-guards.js')).length === 1;
 })());
-ok('claude: hooks/trailhead-bash-guards.js and its six modules exist', ['bash-guards', 'commit-guard', 'secret-guard', 'install-guard', 'search-guard', 'body-guard', 'labels-guard']
+ok('claude: hooks/trailhead-bash-guards.js and its seven modules exist', ['bash-guards', 'commit-guard', 'secret-guard', 'install-guard', 'search-guard', 'body-guard', 'labels-guard', 'test-guard']
   .every((n) => fs.existsSync(path.join(claudeDir, 'hooks', `trailhead-${n}.js`))));
 // mockup-link-guard: Claude-only PreToolUse(AskUserQuestion) backstop for the
 // Prototype "link in the same message as the approval ask" rule.
 ok('claude: hooks/trailhead-mockup-link-guard.js exists', fs.existsSync(path.join(claudeDir, 'hooks', 'trailhead-mockup-link-guard.js')));
 ok('claude: hooks/lib/mockup-link.js exists (mockup-link-guard require target)', fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'mockup-link.js')));
+ok('claude: hooks/lib/gh-auth-preflight.js exists (check-update require target)', fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'gh-auth-preflight.js')));
+ok('claude: hooks/lib/trailhead-git-env.js exists (check-update require target)', fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'trailhead-git-env.js')));
 ok('claude: hooks/trailhead-mockup-link-stop.js does NOT exist (Codex-only twin)', !fs.existsSync(path.join(claudeDir, 'hooks', 'trailhead-mockup-link-stop.js')));
 ok('claude: settings.json does NOT register mockup-link-stop', !settingsContent.includes('trailhead-mockup-link-stop.js'));
 ok('claude: settings.json registers mockup-link-guard under PreToolUse/AskUserQuestion',
@@ -1390,6 +1429,21 @@ const pinConfigTomlPath = path.join(pinCodexHomeDir, 'config.toml');
 ok('codex: config.toml enables multi_agent_v2 when a models.codex.* pin is projected',
   fs.existsSync(pinConfigTomlPath) && fs.readFileSync(pinConfigTomlPath, 'utf8').includes('multi_agent_v2 = true'));
 
+// #323: a project layer that sets plan but not grill grills on that plan, even when
+// the global layer pins grill (the implicit-grill rule applies per layer, before the merge).
+{
+  const pd = mktmp();
+  fs.mkdirSync(path.join(pd, '.trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(pd, '.trailhead', 'config.json'), JSON.stringify({ models: { codex: { plan: 'gpt-5.6-sol' } } }));
+  const ch = mktmp();
+  fs.mkdirSync(path.join(ch, 'trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(ch, 'trailhead', 'config.json'), JSON.stringify({ models: { codex: { grill: 'gpt-5.6-luna' } } }));
+  runInstaller([`--codex`, `--dir=${ch}`], { cwd: pd });
+  const grillToml = fs.readFileSync(path.join(ch, 'agents', 'trailhead-grill.toml'), 'utf8');
+  ok('codex: project plan with no project grill beats a global grill pin in trailhead-grill.toml',
+    grillToml.includes('model = "gpt-5.6-sol"') && !grillToml.includes('gpt-5.6-luna'));
+}
+
 // Uninstall must sweep the projected TOML too, without a --dir= cwd dependency.
 runInstaller([`--codex`, `--dir=${pinCodexHomeDir}`, '--uninstall']);
 ok('codex uninstall: trailhead-execute.toml is gone', !fs.existsSync(pinnedTomlPath));
@@ -1690,7 +1744,7 @@ const bashGuardCommands = (registry) => (registry.hooks.PreToolUse || [])
   ok('(#207) codex migration: exit 0', out.status === 0);
   const cmds = bashGuardCommands(JSON.parse(fs.readFileSync(hooksJsonFile, 'utf8')));
   ok('(#207) codex migration: only the merged entry remains', cmds.length === 1 &&
-    cmds[0].endsWith(' --guards=commit,secret,install,body,labels'));
+    cmds[0].endsWith(' --guards=commit,secret,install,body,labels,test'));
   const once = fs.readFileSync(hooksJsonFile, 'utf8');
   runInstaller([`--codex`, `--dir=${mDir}`]);
   ok('(#207) codex install twice leaves the same hooks.json', fs.readFileSync(hooksJsonFile, 'utf8') === once);
@@ -2067,8 +2121,8 @@ ok('source: hooks.json keeps its command hooks next to the module (#202)',
 
 // --- #259: `trailhead:paused` label marks a paused ticket (pause adds, resume/claim drop) ---
 const firstUseLine = (substrateCommandsSource.match(/^1\. Create any missing labels.*$/m) || [''])[0];
-ok('source: first-use setup lists twenty-one labels including trailhead:paused, trailhead:uat and trailhead:needs-you',
-  /all twenty-one:/.test(firstUseLine) && firstUseLine.includes('`trailhead:paused`') && firstUseLine.includes('`trailhead:uat`') && firstUseLine.includes('`trailhead:needs-you`'));
+ok('source: first-use setup lists twenty-two labels including trailhead:paused, trailhead:uat, trailhead:needs-you and trailhead:needs-info',
+  /all twenty-two:/.test(firstUseLine) && firstUseLine.includes('`trailhead:paused`') && firstUseLine.includes('`trailhead:uat`') && firstUseLine.includes('`trailhead:needs-you`') && firstUseLine.includes('`trailhead:needs-info`'));
 ok('source: no stale "eighteen" or "nineteen" label count remains in the shared skills',
   !/eighteen|nineteen/.test(substrateCommandsSource) && !/eighteen|nineteen/.test(substrateSource));
 ok('source: substrate-commands.md ensures trailhead:paused idempotently',

package/bin/unblock-docs.test.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// Docs test for #322: resolving any ticket (map or whiteboard, via work or quick) unblocks
+// its dependents, as a step independent of the map-only `Decisions so far` book-keeping.
+// Plain asserts, no framework. Run: node bin/unblock-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const skills = path.resolve(__dirname, '..', 'plugins', 'trailhead', 'skills');
+const read = (p) => fs.readFileSync(path.join(skills, p), 'utf8');
+const engines = read('trailhead-work/references/ticket-engines.md');
+const work = read('trailhead-work/SKILL.md');
+const commands = read('_shared/substrate-commands.md');
+const HELPER = 'trailhead-unblock.js --issue <n> --repo <owner/name>';
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const resolveLine = (section) => {
+  const start = engines.indexOf(section);
+  const m = /^5\. \*\*Resolve\*\*.*$/m.exec(engines.slice(start));
+  return m ? m[0] : '';
+};
+const unblockClause = (line) => {
+  const i = line.indexOf('**Unblock dependents');
+  if (i < 0) return '';
+  // the clause ends at the next bold step (the handoff), not at a fixed window
+  const end = line.indexOf('**Session handoff**', i);
+  return line.slice(i, end < 0 ? undefined : end);
+};
+
+for (const section of ['## `build`', '## `bug`']) {
+  const line = resolveLine(section);
+  const clause = unblockClause(line);
+  ok(`engines ${section}: Resolve has an Unblock dependents clause`, clause !== '');
+  ok(`engines ${section}: names the helper`, clause.includes(HELPER));
+  ok(`engines ${section}: applies to map and whiteboard tickets alike`, /whiteboard/.test(clause) && /map/.test(clause));
+  ok(`engines ${section}: keeps the by-hand fallback`, clause.includes('--remove-label "trailhead:blocked"'));
+  ok(`engines ${section}: independent of the map-only Decisions so far update`, /independent of the map-only `Decisions so far` update/.test(clause));
+  ok(`engines ${section}: runs right after the close`, /^\*\*Unblock dependents[^*]*\*\*\s*Right after the close/.test(clause) && line.indexOf('gh issue close') < line.indexOf('**Unblock dependents'));
+  ok(`engines ${section}: fallback names the blocked_by endpoint`, clause.includes('dependencies/blocked_by'));
+}
+
+const step5 = (/^5\. Record the resolution.*$/m.exec(work) || [''])[0];
+ok('SKILL.md step 5: unblock is its own sentence naming the helper', /\.\s+Unblocking is a separate step[^]*\*\*unblock dependents\*\*/.test(step5) && step5.includes('trailhead-unblock.js'));
+ok('SKILL.md step 5: holds for whiteboard tickets too', /whiteboard/.test(step5));
+
+const bullet = (/^- \*\*No map narrative book-keeping\.\*\*.*$/m.exec(work) || [''])[0];
+ok('SKILL.md quick bullet exists', bullet !== '');
+ok('SKILL.md quick bullet: unblocking is among the steps that still hold', /Everything else holds:[^.]*unblocking dependents/.test(bullet) && bullet.includes('trailhead-unblock.js'));
+ok('SKILL.md quick bullet: no map-only exception', !bullet.includes('Exception, `quick <n>` on a *map* ticket'));
+
+ok('substrate-commands.md: unblock block names the helper as default', /Unblock:[\s\S]{0,400}trailhead-unblock\.js --issue <n> --repo <owner\/name>/.test(commands));
+ok('substrate-commands.md: keeps the raw gh command as fallback', /Unblock:[\s\S]{0,700}gh issue edit <(?:n|dep)> --remove-label "trailhead:blocked"/.test(commands));
+ok('substrate-commands.md: cookbook comment names the helper', /# unblock[^\n]*trailhead-unblock\.js/.test(commands));
+ok('no em-dash', ![engines, work, commands].some((s) => s.includes(String.fromCharCode(0x2014))));
+console.log(`unblock-docs.test.js: ${passed} checks passed`);

package/bin/yes-accepts-recommended-docs.test.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Docs test for #358: in grilling a plain "yes" always accepts the recommended answer.
+// The rule is defined once (Grilling technique); the grill return contract states it for the agent.
+// Run: node yes-accepts-recommended-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const repo = path.join(__dirname, '..');
+const plugin = path.join(repo, 'plugins', 'trailhead');
+const read = (...rel) => fs.readFileSync(path.join(...rel), 'utf8');
+const line = (text, start) => text.split('\n').find((l) => l.startsWith(start));
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const DEFINITION = '**A yes accepts the recommendation.**';
+const walk = (dir) => fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+  e.isDirectory() ? walk(path.join(dir, e.name)) : [path.join(dir, e.name)]);
+
+// 1. defined exactly once, in the Grilling technique
+const techniquePath = path.join(plugin, 'skills', '_shared', 'techniques', 'grilling.md');
+const defs = walk(plugin).filter((f) => read(f).includes(DEFINITION));
+ok('definition appears in exactly one file', defs.length === 1);
+ok('definition lives in grilling.md', defs[0] === techniquePath);
+
+// 2. the definition carries the normative fragments, on the one-question bullet
+const technique = read(techniquePath);
+const rule = line(technique, '- **One question at a time, with your pick.**');
+ok('rule sits on the one-question bullet', rule.includes(DEFINITION));
+for (const frag of [
+  'a plain "yes" accepts your pick',
+  'never an open "should we A or B?" followed by a recommendation',
+  'exactly one meaning',
+  'A play-back',
+]) ok(`rule carries: ${frag}`, rule.includes(frag));
+
+// 3. the relay never rewords the question out of the rule
+const relay = line(technique, '   - `question`: relay');
+ok('relay names the rule', relay.includes('**A yes accepts the recommendation**'));
+
+// 4. the return contract states it, in the source block and in the synced agent
+for (const [name, text] of [
+  ['agent-blocks.md', read(repo, 'scripts', 'agent-blocks.md')],
+  ['trailhead-grill.md', read(plugin, 'agents', 'trailhead-grill.md')],
+]) {
+  const q = line(text, '- `question:` the one numbered question');
+  const r = line(text, '- `recommended:` your pick');
+  ok(`${name}: question is worded so a yes accepts the pick`, q.includes('a plain "yes" accepts `recommended:`'));
+  ok(`${name}: question bans the open form`, q.includes('never an open "should we A or B?"'));
+  ok(`${name}: recommended is what a yes accepts`, r.includes('what a plain "yes" accepts'));
+}
+
+console.log(`yes-accepts-recommended-docs: ${passed} assertions passed`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcomigozzi/trailhead",
-  "version": "0.16.1",
+  "version": "0.18.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.16.1",
+  "version": "0.18.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/agents/trailhead-code-review.md

@@ -7,7 +7,7 @@ tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
 
 trailhead's code-review subagent. Review the ticket's diff adversarially on the Code review technique's axes, verifying each finding before reporting. Do not defer to a convention or a settled-decision memory.
 
-The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/code-review.md`); follow that, not any embedded copy. Read-only by policy: it reviews and returns the report (the orchestrator posts it as the `VERIFY` comment), it must never Edit/Write or commit. Model-agnostic by design: the engine passes the `config.models.review` model as the spawn-time override, so config stays authoritative.
+The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/code-review.md`); follow that, not any embedded copy. Read-only by policy: it reviews and returns the report (the orchestrator posts it as the `VERIFY` comment), it must never Edit/Write or commit. Model-agnostic by design: the engine passes the `config.models.review` model as the spawn-time override, so config stays authoritative. A pipeline-touching diff also loads `code-review-pipeline.md`, at the path the spawn names. Read the repo's standards files, at the paths the spawn names, for the Standards & spec axis, and cite the file for each standards finding.
 
 <!-- trailhead:agent-block common -->
 **Search-command hygiene.** Prefer the Grep and Read tools; use absolute paths and `git -C <abs>`.
@@ -22,4 +22,5 @@ Never `cd` (or `pushd`/`env -C`) into a directory first; the full rule is in `_s
 - trailhead-verify: `<token>` is one of `met` | `gaps_found` | `inconclusive`; each claim line carries `class: <met|unmet|partial|inconclusive>`, and `met` lists no `unmet`, `partial` or `inconclusive` claim.
 - trailhead-code-review: `<token>` is one of `clean` | `issues_found`, and line 2 is the counts line `critical: <n> · warning: <n> · info: <n>`; `clean` with a non-zero `critical` count requires a ledger line closing every Critical (`fixed`, `deferred` or `accepted`), none `open`.
 - Read-only: never Edit/Write, never commit.
+- When the orchestrator passes a test record (`test record: ...`, the full-suite outcome of Verify), read it and never re-run the full suite (a focused test to probe one finding is fine); with no record passed, test as today (without `testing.full` no test record is passed).
 <!-- /trailhead:agent-block reviewing -->

package/plugins/trailhead/agents/trailhead-codebase-map.md

@@ -7,7 +7,7 @@ tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
 
 trailhead's codebase-map reader subagent. Map ONE non-overlapping facet of the repo for the distilled `trailhead:codebase` issue; do not read another reader's territory.
 
-The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/codebase-map.md`); follow that, not any embedded copy. Read-only by policy: read-only by construction. Model-agnostic by design: the engine passes the session model at spawn (no dedicated model key), so config stays authoritative.
+The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/codebase-map.md`); follow that, not any embedded copy. Read-only by policy: read-only by construction. Model-agnostic by design: the engine passes the `config.models.codebase-map` model as the spawn-time override, so config stays authoritative.
 
 <!-- trailhead:agent-block common -->
 **Search-command hygiene.** Prefer the Grep and Read tools; use absolute paths and `git -C <abs>`.

package/plugins/trailhead/agents/trailhead-grill.md

@@ -0,0 +1,41 @@
+---
+name: trailhead-grill
+color: yellow
+description: "trailhead grill subagent: one read-only Grilling round, returned as a question or a holistic review."
+tools: Read, Grep, Glob, WebFetch, WebSearch, TodoWrite
+---
+
+trailhead's grill subagent. Run one round of Grilling for the orchestrator: read the code facts the question needs, then return either the next numbered question with your recommended answer, or the holistic review of the settled choices. You are read-only: you never talk to the user and never answer on their behalf; the orchestrator relays your question and re-dispatches you with the answer.
+
+The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/grilling.md`); follow its round bullets and the `Return contract` below, not any embedded copy. The orchestrator-facing section of that file is not yours. The orchestrator passes the ticket body, the relevant decisions, the tickets the subject names and the Q&A so far; a fact you cannot reach goes under `facts` as `not looked up:`. Model-agnostic by design: the engine passes the `config.models.grill` model as the spawn-time override, so config stays authoritative.
+
+<!-- trailhead:agent-block common -->
+**Search-command hygiene.** Prefer the Grep and Read tools; use absolute paths and `git -C <abs>`.
+Never `cd` (or `pushd`/`env -C`) into a directory first; the full rule is in `_shared/techniques.md`.
+
+**Boundaries.** Never `git push`. Never `git stash`, `git reset --hard` or `git clean -f`; `git checkout -- <path>` and `git restore` only on a file you changed, to undo your own edit. Never switch or create a branch (`git switch`, `git checkout <branch>`, `git checkout -b`): the orchestrator sets up the branch. Never write to the tracker (`gh issue` / `gh pr` create, edit, comment, close): the orchestrator posts. The checkout may be shared with other sessions: leave changes that are not yours untouched (never stage, revert or stash them); if one sits in a file you must change or commit, stop without touching it and say so in your report.
+<!-- /trailhead:agent-block common -->
+
+<!-- trailhead:agent-block grilling -->
+**Return contract.** Return the complete report as your final message. Do not post it anywhere (no issue comment, no PR comment): the orchestrator posts what it records. Never commit. Read-only: never Edit/Write.
+- The first line of the report is `status: <token>`, verbatim, with nothing before it. It is the only line starting with `status:`: status text anywhere in the body is quoted in a code fence or a blockquote, or reworded.
+- statuses: `question` | `review`.
+- required fields: `settled`, `frontier`, `amendments`, `conflicts`.
+- optional fields: `question`, `recommended`, `areas`, `facts`.
+- invariant: `question` => `question` non-empty.
+- invariant: `question` => `recommended` non-empty.
+- invariant: `question` => `amendments` none.
+- invariant: `question` => `conflicts` none.
+- invariant: `review` => `frontier` none.
+- invariant: `review` => `question` none.
+- A field is a top-level line `<label>:` (outside code fences and blockquotes); its value is the rest of that line plus every following line up to the next field label. An empty value or `none` means none.
+- Fields are the end of the report: nothing after the last field.
+- You never talk to the user and never answer on their behalf: the orchestrator relays the question and collects the answer. The recommended answer is only your pick.
+- `settled:` every settled choice so far, one per line by question number, with its rationale; `none` before the first answer.
+- `frontier:` the open questions whose prerequisites are settled; `none` once it is empty.
+- `question:` the one numbered question to ask now, worded around your pick so a plain "yes" accepts `recommended:` and has no other meaning; never an open "should we A or B?" followed by a recommendation. Illustrate each option (its label, a one-line summary, its trade-off) so the relay can render them per **The ask is answerable from the chat alone**; never a reference to the ticket in place of the options. Offer defer in prose when the question is blocked on a prerequisite. Play back the user's understanding when it closes a branch.
+- `recommended:` your pick, what a plain "yes" accepts, stress-tested, ending with a `Weak point:` line (not a field label, so a review may carry one per fix). Never the delegate option.
+- `areas:` for a multi-part space, every functional area, each marked visited or open.
+- `facts:` what you looked up, with `file:line` or a URL. A fact you could not reach is written as `not looked up: <what>`; the orchestrator fetches it for the next round.
+- `amendments:` / `conflicts:` the holistic review. Each item names its question numbers; each conflict carries its fix, or one line saying where it goes. Both are `none` when nothing is found, and always `none` on a `question` round.
+<!-- /trailhead:agent-block grilling -->

package/plugins/trailhead/agents/trailhead-plan.md

@@ -26,6 +26,6 @@ Never `cd` (or `pushd`/`env -C`) into a directory first; the full rule is in `_s
 - invariant: `needs_input` => `questions` non-empty.
 - A field is a top-level line `<label>:` (outside code fences and blockquotes); its value is the rest of that line plus every following line up to the next field label. An empty value or `none` means none.
 - With `needs_input`, fields are the end of the report: nothing after the last field.
-- `ready`: the rest of the report is the PLAN (the `body`): the steps, the seams, the files touched and the verification criteria. It is posted verbatim, so write nothing in it that is not the PLAN.
+- `ready`: the rest of the report is the PLAN (the `body`): the steps, the seams (one line each, `<seam>: catches <what a test here fails on>; misses <what gets through it>`), the files touched and the verification criteria. It is posted verbatim, so write nothing in it that is not the PLAN.
 - `needs_input`: `questions:` holds the blocking questions only; no PLAN.
 <!-- /trailhead:agent-block plan -->

package/plugins/trailhead/agents/trailhead-verify.md

@@ -22,4 +22,5 @@ Never `cd` (or `pushd`/`env -C`) into a directory first; the full rule is in `_s
 - trailhead-verify: `<token>` is one of `met` | `gaps_found` | `inconclusive`; each claim line carries `class: <met|unmet|partial|inconclusive>`, and `met` lists no `unmet`, `partial` or `inconclusive` claim.
 - trailhead-code-review: `<token>` is one of `clean` | `issues_found`, and line 2 is the counts line `critical: <n> · warning: <n> · info: <n>`; `clean` with a non-zero `critical` count requires a ledger line closing every Critical (`fixed`, `deferred` or `accepted`), none `open`.
 - Read-only: never Edit/Write, never commit.
+- When the orchestrator passes a test record (`test record: ...`, the full-suite outcome of Verify), read it and never re-run the full suite (a focused test to probe one finding is fine); with no record passed, test as today (without `testing.full` no test record is passed).
 <!-- /trailhead:agent-block reviewing -->

package/plugins/trailhead/hooks/lib/audit-walk.test.js

@@ -798,5 +798,67 @@ function cli(args) {
   ok('attribute merge replacing a tracked line: merge is not a producer', !shas(c).includes(m));
 }
 
+// --- facets: freshness of the codebase issue's facets -------------------------
+{
+  const facetsRun = (dir, body) => {
+    const file = path.join(dir, '.git', 'facets-body.md');
+    fs.writeFileSync(file, body);
+    let text = '';
+    const code = walk.main(['facets', '--repo', dir, '--body-file', file], { stdout: { write: (t) => { text += t; } } });
+    return { code, out: JSON.parse(text) };
+  };
+  const facet = (name, sha, ...cited) => `## ${name}\n\n${sha ? `_as of ${sha}_\n\n` : ''}${cited.map((c) => `- \`${c}\` is here`).join('\n')}\n\n`;
+  const byName = (r, name) => r.out.facets.find((f) => f.name === name);
+
+  const dir = mkrepo();
+  const c1 = commit(dir, {
+    'src/a.js': 'a\n', 'src/b.js': 'b\n', 'lib/old.js': 'o\n', 'lib/mv.js': 'm\n',
+    'docs/x.md': 'x\n', 'star/[ab].txt': 's\n', 'star/a.txt': 'plain\n',
+  }, 'feat: base');
+  const s1 = c1.slice(0, 7);
+  const body = '# Codebase\n\n' + [
+    facet('Fresh', s1, 'docs/x.md'),
+    facet('Edited', s1, 'src/a.js:3-9', 'docs/x.md'),
+    facet('Gone', s1, 'lib/old.js'),
+    facet('Moved', s1, 'lib/mv.js'),
+    facet('Unstamped', null, 'src/b.js'),
+    facet('Rewritten', 'deadbeef', 'src/b.js'),
+    facet('Nothing', s1, 'no/such.js', '/etc/passwd', '../x', '-rf', ':x', 'a b', 'plain words'),
+    facet('Glob', s1, 'star/[ab].txt'),
+    facet('Dir', s1, 'src/'),
+  ].join('') + '## Fenced\n\n```\n## Not a facet\n```\n';
+  commit(dir, { 'src/a.js': 'a2\n', 'lib/old.js': null, 'star/[ab].txt': 's2\n' }, 'fix: edits');
+  git(dir, ['mv', 'lib/mv.js', 'lib/moved.js']);
+  const c2 = finishCommit(dir, ['commit', '-q'], 'refactor: rename', {});
+  const r = facetsRun(dir, body);
+  eq('facets: exit 0 and head', [r.code, r.out.head], [0, c2]);
+  eq('facets: fresh facet is current', [byName(r, 'Fresh').status, byName(r, 'Fresh').changed], ['current', []]);
+  eq('facets: edited cited file (with :line suffix) is stale', [byName(r, 'Edited').status, byName(r, 'Edited').changed, byName(r, 'Edited').paths], ['stale', ['src/a.js'], ['src/a.js', 'docs/x.md']]);
+  eq('facets: deleted cited file is stale', [byName(r, 'Gone').status, byName(r, 'Gone').changed], ['stale', ['lib/old.js']]);
+  eq('facets: renamed cited file is stale', byName(r, 'Moved').status, 'stale');
+  eq('facets: no stamp is unstamped', [byName(r, 'Unstamped').status, byName(r, 'Unstamped').sha], ['unstamped', null]);
+  eq('facets: unknown stamp is unresolved', byName(r, 'Rewritten').status, 'unresolved');
+  eq('facets: unsafe and missing tokens are ignored, nothing resolved is no-paths', [byName(r, 'Nothing').status, byName(r, 'Nothing').paths], ['no-paths', []]);
+  eq('facets: glob characters match literally and a real change reads stale', [byName(r, 'Glob').status, byName(r, 'Glob').changed], ['stale', ['star/[ab].txt']]);
+  eq('facets: trailing slash is stripped', [byName(r, 'Dir').status, byName(r, 'Dir').paths], ['stale', ['src']]);
+  ok('facets: a fenced ## is not a facet', !r.out.facets.some((f) => f.name === 'Not a facet'));
+  eq('facets: fenced section is listed as unstamped', byName(r, 'Fenced').status, 'unstamped');
+
+  // A stamp that is a real commit but not an ancestor of HEAD is unresolved.
+  git(dir, ['checkout', '-q', '-b', 'side', c1]);
+  const side = commit(dir, { 'side.txt': 's\n' }, 'feat: side');
+  git(dir, ['checkout', '-q', 'main']);
+  const o = facetsRun(dir, facet('Side', side.slice(0, 7), 'src/b.js'));
+  eq('facets: a stamp off HEAD history is unresolved', byName(o, 'Side').status, 'unresolved');
+
+  // Usage errors exit 2 with {"error":...}.
+  let text = '';
+  const bad = walk.main(['facets', '--repo', dir], { stdout: { write: (t) => { text += t; } } });
+  ok('facets: --body-file is required', bad === 2 && JSON.parse(text).error);
+  text = '';
+  const missing = walk.main(['facets', '--repo', dir, '--body-file', '/nonexistent/body.md'], { stdout: { write: (t) => { text += t; } } });
+  ok('facets: unreadable body file is a fatal error', missing === 2 && JSON.parse(text).error);
+}
+
 cleanup();
 console.log(`✓ audit-walk: ${passed} assertions passed`);