@marcomigozzi/trailhead 0.16.1 → 0.17.0

package/bin/report-status-docs.test.js

@@ -35,16 +35,18 @@ ok('the paragraph sits next to "Reviews never block the session"',
   start !== -1 && neverBlock !== -1 && Math.abs(start - neverBlock) < 2500 && start > neverBlock);
 const para = start === -1 ? '' : techniques.slice(start, techniques.indexOf('\n| Technique |', start));
 const lc = para.toLowerCase();
+ok('an inline grill round writes no report, so it is not checked',
+  para.includes('An inline `grill` round writes no report') && lc.includes('only a dispatched `trailhead-grill` report is checked'));
 ok('the paragraph section was found and is bounded', para.length > 1000 && !para.includes('| **Grilling**'));
 
 ok('it MUST run on every engine-agent report, the two reviews included', /MUST run on every/.test(para)
   && para.includes('Code review') && para.includes('Goal-backward verification'));
 ok('it names every technique it covers',
-  ['plan', 'executor', 'fix', 'debug', 'research', 'codebase-map'].every((t) => para.includes(t)) && lc.includes('every engine-agent report'));
+  ['plan', 'executor', 'fix', 'debug', 'research', 'codebase-map', 'grill'].every((t) => para.includes(t)) && lc.includes('every engine-agent report'));
 ok('the checker line carries fields and body', para.includes('{"action","verdict","problem","report","fields","body"}'));
 ok('it covers subagent, inline and the lean inline pass', lc.includes('subagent') && lc.includes('inline') && lc.includes('lean inline pass'));
 ok('the checker command with its technique flag and a report file',
-  para.includes('node <templates>/trailhead-report-status.js --technique <verify|code-review|plan|executor|fix|debug|research|codebase-map> --file <that dir>/report.md'));
+  para.includes('node <templates>/trailhead-report-status.js --technique <verify|code-review|plan|executor|fix|debug|research|codebase-map|grill> --file <that dir>/report.md'));
 ok('the three templates dirs, in order',
   (() => {
     const a = para.indexOf('${CLAUDE_PLUGIN_ROOT}/templates/');
@@ -52,6 +54,12 @@ ok('the three templates dirs, in order',
     const c = para.indexOf('~/.codex/skills/trailhead/templates/');
     return a !== -1 && b > a && c > b;
   })());
+ok('a background agent is checked straight from its task output file, no temp dir',
+  para.includes('--task-output <that output file>') && lc.includes('once the agent has finished') && lc.includes('no temp dir, no copy and no cleanup'));
+ok('the temp-dir route is for any other report', lc.includes('any other report (inline, foreground, or a host without that file)'));
+ok('each step is its own Bash call, never bash -c, never chained',
+  lc.includes('its own bash call') && para.includes('never wrapped in `bash -c` / `sh -c`') && lc.includes('never chained')
+  && lc.includes('cannot statically check'));
 ok('the plugin root dir is skipped when unset', lc.includes('skipped when unset'));
 ok('a private temp dir from mktemp -d, once per report', para.includes('`mktemp -d`') && lc.includes('once') && lc.includes('0700'));
 ok('the raw report is written to report.md at the literal printed path with the Write tool',

package/bin/session-trust-docs.test.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// Docs test for #333: the in-session trust rule accepts the same labellers as the label guard
+// (github-actions[bot], TRAILHEAD_LABEL_ALLOWLIST logins, write+ collaborators). Plain asserts.
+// Run: node bin/session-trust-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const root = path.resolve(__dirname, '..');
+const skills = path.join(root, 'plugins', 'trailhead', 'skills');
+const tw = fs.readFileSync(path.join(skills, '_shared', 'teamwork.md'), 'utf8');
+const inbox = fs.readFileSync(path.join(skills, 'trailhead-chart', 'references', 'inbox.md'), 'utf8');
+const s = tw.indexOf('## Trust & provenance');
+const e = tw.indexOf('**Repo-side enforcement');
+const trust = s < 0 || e < s ? '' : tw.slice(s, e);
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+ok('teamwork.md has the trust section', trust !== '');
+ok('bot is a trusted labeller', /`github-actions\[bot\]`[^]*trusted/i.test(trust));
+ok('bot why: GITHUB_TOKEN events trigger no workflow', /GITHUB_TOKEN[^]*(trigger|run)s? no workflow[^]*guard/i.test(trust));
+ok('allowlist read command', trust.includes('gh variable get TRAILHEAD_LABEL_ALLOWLIST'));
+ok('allowlist: not found means empty', /not found[^]*(means|->|is) empty/i.test(trust));
+ok('allowlist: other failure means unknown, not empty', /any other failure[^]*unknown/i.test(trust) && /unknown, not empty/i.test(trust));
+ok('allowlist compare: comma-separated, trimmed, case-insensitive', /comma-separated[^]*trimmed[^]*case-insensitive/i.test(trust));
+ok('unknown allowlist: held off frontier, provenance not checkable', /unknown[^]*held? off the frontier[^]*provenance not checkable/i.test(trust));
+ok('never labelled unverified on a guess', /never[^.]*`trailhead:unverified`[^.]*guess/i.test(trust));
+ok('failed permission lookup is unresolved too', /permission lookup (failed|fails)/i.test(trust) && /`404`[^]*real answer/i.test(trust));
+ok('per-label provenance: latest labeled event of every label', /every `trailhead:\*` label[^]*latest `labeled` event[^]*all[^.]*trusted/i.test(trust));
+ok('one trusted label does not vouch for another', /does not vouch for another/i.test(trust));
+ok('still quarantines other non-write labellers', /`read`\/`none`[^]*not trusted/i.test(trust) && trust.includes('`trailhead:unverified`'));
+ok('session and guard agree', /never strips/i.test(trust));
+ok('inbox: session applies unverified, guard strips', /`trailhead:unverified`[^.]*applied by a session[^]*guard Action strips/i.test(inbox));
+ok('inbox: rogue means outside the trusted labellers', /trusted labellers[^]*Trust rule|Trust rule[^]*trusted labellers/i.test(inbox) && /teamwork\.md#trust--provenance/.test(inbox));
+ok('inbox: jq includes quarantined issues', /\| any\(startswith\("trailhead:"\)\) \| not\) or \(\[\.labels\[\]\.name\] \| any\(\. == "trailhead:unverified"\)\)/.test(inbox));
+ok('no em-dash', !tw.includes(String.fromCharCode(0x2014)) && !inbox.includes(String.fromCharCode(0x2014)));
+console.log(`session-trust-docs.test.js: ${passed} checks passed`);

package/bin/surfaced-scope-docs.test.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Docs test: un ticket aperto a metà lavoro va sulla mappa corrente (o su quella giusta)
+// se il tema è suo; altrimenti si chiede fra mappe aperte e whiteboard, mai whiteboard
+// in silenzio; dopo la creazione si dice dove è stato aperto. I rimandi puntano al file.
+// Plain asserts, no framework. Run: node bin/surfaced-scope-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const root = path.resolve(__dirname, '..');
+const read = (rel) => fs.readFileSync(path.join(root, rel), 'utf8');
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+const EM = String.fromCharCode(0x2014);
+
+const SK = 'plugins/trailhead/skills';
+const REF = 'Scope that surfaces while working a ticket';
+
+// La regola condivisa
+const rule = read(`${SK}/_shared/surfaced-scope.md`);
+ok('rule: titled after the referenced name', rule.startsWith(`# ${REF}`));
+ok('rule: do it, split it, or capture it', /\*\*`split`\*\* X/.test(rule) && /capture and continue/.test(rule));
+ok('rule: Surfaced from lineage line', /`Surfaced from: /.test(rule));
+ok('rule: current map first when the topic is its own', /1\. \*\*The current map[^\n]*no ask/.test(rule));
+ok('rule: another open map when the topic clearly is its', /2\. \*\*Another open map[^\n]*no ask/.test(rule));
+ok('rule: otherwise ask, listing every open map and the whiteboard', /3\. \*\*Otherwise, ask\.\*\*[^\n]*AskUserQuestion[^\n]*every open map[^\n]*whiteboard/.test(rule));
+ok('rule: never the whiteboard silently while a map is open', /Never route to the whiteboard without this ask while any map is open/.test(rule));
+ok('rule: no map open falls to the whiteboard', /4\. \*\*No map open → whiteboard, no ask\*\*/.test(rule));
+ok('rule: auto defers an ask case instead of guessing', /autonomous run[^\n]*rule 3[^\n]*Pending follow-up guard/.test(rule));
+ok('rule: announce the ticket and where it landed', /## Say what you opened, and where/.test(rule) && /\*\*where it landed\*\*/.test(rule));
+ok('rule: no em-dash', !rule.includes(EM));
+
+// Ogni rimando al nome porta al file (nessun rimando orfano)
+const referrers = [
+  `${SK}/_shared/session-handoff.md`,
+  `${SK}/_shared/techniques/code-review.md`,
+  `${SK}/trailhead-work/SKILL.md`,
+  `${SK}/trailhead-work/references/ticket-engines.md`,
+];
+for (const rel of referrers) {
+  const text = read(rel);
+  const lines = text.split('\n').filter((l) => l.includes(REF));
+  ok(`${rel}: mentions the rule`, lines.length > 0);
+  ok(`${rel}: every mention links surfaced-scope.md`, lines.every((l) => /surfaced-scope\.md/.test(l)));
+  ok(`${rel}: no "served by the capture cluster" dangling pointer`, lines.every((l) => !/served by the capture cluster/.test(l)));
+}
+
+// Capture e UAT seguono la stessa regola
+const capture = read(`${SK}/trailhead-capture/references/capture.md`);
+// #330: capture.md no longer links the full core; it states the routing inline and
+// capture-core.md carries drift markers on the surfaced-scope.md rules it restates.
+ok('capture: a mid-ticket capture states the surfaced-scope routing inline', /\*\*A capture fired mid-ticket\*\*[^\n]*the current map[^\n]*Surfaced from:/.test(capture));
+ok('capture-core: surfaced-scope.md rules are drift-stamped', /<!-- core: surfaced-scope\.md \|/.test(read(`${SK}/_shared/capture-core.md`)));
+const uat = read(`${SK}/_shared/techniques/acceptance-testing.md`);
+ok('uat: the failing-step follow-up lands per surfaced-scope.md', /On a failing step[^\n]*surfaced-scope\.md/.test(uat));
+
+console.log(`surfaced-scope-docs.test.js: ${passed} checks passed`);

package/bin/trailhead.js

@@ -160,7 +160,9 @@ function readCodexModels(codexHome) {
     const globalCfg = readJSON(path.join(codexHome, 'trailhead', 'config.json')) || {};
     const globalCodex = globalCfg.models && typeof globalCfg.models === 'object' && typeof globalCfg.models.codex === 'object' && globalCfg.models.codex ? globalCfg.models.codex : {};
     const projectCodex = projectCfg.models && typeof projectCfg.models === 'object' && typeof projectCfg.models.codex === 'object' && projectCfg.models.codex ? projectCfg.models.codex : {};
-    return { ...globalCodex, ...projectCodex };
+    // #323: una layer con plan ma senza grill implica grill = plan, prima del merge.
+    const { withImplicitGrill } = require(path.join(SRC, 'hooks', 'lib', 'model-defaults-review.js'));
+    return { ...withImplicitGrill(globalCodex), ...withImplicitGrill(projectCodex) };
   } catch {
     return {};
   }
@@ -263,7 +265,7 @@ const ENTRYPOINT_FILES = HOOK_FILES.filter((f) => !BASH_GUARD_MODULES.includes(f
 // require('./lib/mockup-link.js')). Copied by name, never a recursive
 // sweep: the Claude hooks/lib dir is shared with other plugins, so we must
 // not clobber a co-tenant's lib nor ship our own *.test.js files.
-const HOOK_LIB_FILES = ['commit-message-check.js', 'shell-scan.js', 'gh-subcommand.js', 'body-sources.js', 'unmodelled.js', 'model-defaults-review.js', 'model-defaults.json', 'mockup-link.js'];
+const HOOK_LIB_FILES = ['commit-message-check.js', 'shell-scan.js', 'gh-subcommand.js', 'body-sources.js', 'unmodelled.js', 'model-defaults-review.js', 'model-defaults.json', 'inherit-session.js', 'model-route.js', 'mockup-link.js', 'gh-auth-preflight.js'];
 // search-guard is Claude-Code-specific (#169), and so is mockup-link-guard
 // (it gates the AskUserQuestion tool, which Codex lacks): excluded from both
 // the Codex hook copy and the Codex verify spec's expected hookFiles, so a
@@ -686,12 +688,12 @@ function installCodex(configDir, { useSymlink }) {
     featureManual = true;
   }
 
-  // Per-technique agent registry: project ALL 8 committed agents
+  // Per-technique agent registry: project ALL 9 committed agents
   // (readAgentDefs, sourced from plugins/trailhead/agents/*.md) as
   // trailhead-<technique>.toml under the real ~/.codex/agents/ dir, uniformly.
-  // A keyed technique (plan/execute/research/review/debug/verify/codebase-map)
+  // A keyed technique (plan/execute/research/review/debug/verify/codebase-map/grill)
   // carries its models.codex.<key> pin (merged project + global config) when
-  // set, else is pin-less; the 1 keyless agent (fix) is always pin-less.
+  // set, else is pin-less; fix tracks the models.codex.execute pin.
   // Sweep only trailhead's own files first, so a stale pin from a prior
   // install (or a removed technique) never lingers, without touching the
   // user's other custom-agent TOMLs.

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
@@ -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,8 @@ 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/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 +993,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 +1032,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 +1045,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 +1058,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 +1066,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');
@@ -1108,7 +1129,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 +1150,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 +1211,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`)));
 }
@@ -1315,6 +1341,7 @@ ok('claude: hooks/trailhead-bash-guards.js and its six modules exist', ['bash-gu
 // 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/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 +1417,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));

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcomigozzi/trailhead",
-  "version": "0.16.1",
+  "version": "0.17.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.17.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-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. Illustrate each option: what it optimizes and what it sacrifices. 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, 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 -->