@marcomigozzi/trailhead 0.16.0 → 0.17.0

package/bin/lib/runtime-command-literals.test.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// Test statico: nessun literal di comando Claude (`/trailhead:<verb>` o `/trailhead`
+// nudo) dentro stringhe/template del codice runtime. Gli hook lib e i template
+// vengono copiati byte-per-byte su Codex e convertToCodex riscrive solo il
+// markdown, quindi un literal qui arriverebbe cosi' com'e' a un utente Codex.
+// Usare commandForm(host, verb) (host-descriptor o helper locale della lib).
+// Run: node runtime-command-literals.test.js. Nessun framework: assert semplici.
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const SCAN_DIRS = [
+  { dir: 'plugins/trailhead/hooks', skip: ['plugins/trailhead/hooks/mod'] },
+  { dir: 'plugins/trailhead/templates', skip: [] },
+  { dir: 'bin', skip: [] },
+];
+
+// Eccezioni motivate: file (relativo alla root) + sottostringa della riga.
+// Niente numeri di riga, cosi' le modifiche attorno non rompono il test.
+const ALLOWLIST = [
+  {
+    file: 'plugins/trailhead/templates/trailhead-dashboard.js',
+    contains: 'Regenerate any time with',
+    reason: 'corpo del dashboard: artefatto condiviso host-neutral scritto nell\'issue, non un messaggio runtime per host',
+  },
+  {
+    file: 'bin/trailhead.js',
+    contains: '(/trailhead:*)',
+    reason: 'banner dell\'installer Claude-only (il ramo Codex stampa il proprio banner)',
+  },
+  {
+    file: 'bin/trailhead.js',
+    contains: 'then run /trailhead to start',
+    reason: 'banner dell\'installer Claude-only',
+  },
+  {
+    file: 'bin/lib/codex-projection.js',
+    contains: 'Never \\`/trailhead:<verb>\\`',
+    reason: 'testo del SKILL.md Codex: nomina la forma Claude proprio per vietarla all\'agente',
+  },
+  {
+    file: 'bin/lib/host-descriptor.js',
+    contains: "commandPrefix: '/trailhead:'",
+    reason: 'dato del descriptor Claude da cui commandForm produce la forma Claude',
+  },
+  {
+    file: 'plugins/trailhead/hooks/lib/model-defaults-review.js',
+    contains: '`/trailhead:${verb}`',
+    reason: 'helper commandForm della lib: l\'unico punto che produce la forma Claude',
+  },
+];
+
+// `/trailhead:` (anche seguito da `${`, `*`, `<verb>` o concatenato) oppure
+// `/trailhead` nudo. Non conta dentro un path: non preceduto da parola, `.`,
+// `~`, `\`, `/`, `-` e non seguito da parola, `:`, `/`, `\`, `-`.
+const COMMAND_RE = /(?<![\w.~\\/-])\/trailhead(?::|(?![\w:/\\-]))/g;
+
+function listJs(dir, skip) {
+  const out = [];
+  for (const e of fs.readdirSync(path.join(ROOT, dir), { withFileTypes: true })) {
+    const rel = `${dir}/${e.name}`;
+    if (e.isDirectory()) {
+      if (e.name === 'node_modules' || skip.includes(rel)) continue;
+      out.push(...listJs(rel, skip));
+    } else if (e.name.endsWith('.js') && !e.name.endsWith('.test.js')) {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+// Scanner minimale a stati sull'intero file: marca i caratteri che stanno
+// dentro stringhe ('...', "...") e template (`...`, anche su piu' righe, con i
+// loro ${...}); commenti e literal regex sono saltati. Non e' un parser JS
+// completo: una regex e' riconosciuta dal carattere significativo precedente.
+const REGEX_PREV = new Set(['', '(', ',', '=', ':', '[', '!', '&', '|', '?', '{', '}', ';', '+', '-', '*', '%', '<', '>', '~', '^']);
+function literalMask(text) {
+  const mask = new Uint8Array(text.length);
+  let i = 0;
+  let prev = '';
+  while (i < text.length) {
+    const c = text[i];
+    const n = text[i + 1];
+    if (c === '/' && n === '/') {
+      while (i < text.length && text[i] !== '\n') i++;
+    } else if (c === '/' && n === '*') {
+      const end = text.indexOf('*/', i + 2);
+      i = end === -1 ? text.length : end + 2;
+    } else if (c === '"' || c === "'" || c === '`') {
+      mask[i] = 1;
+      i++;
+      while (i < text.length && text[i] !== c) {
+        if (text[i] === '\\') { mask[i] = 1; i++; }
+        if (c !== '`' && text[i] === '\n') break;
+        mask[i] = 1;
+        i++;
+      }
+      if (i < text.length) mask[i] = 1;
+      i++;
+      prev = c;
+    } else if (c === '/' && (REGEX_PREV.has(prev) || prev === 'return')) {
+      i++;
+      let inClass = false;
+      while (i < text.length && text[i] !== '\n' && (inClass || text[i] !== '/')) {
+        if (text[i] === '\\') i++;
+        else if (text[i] === '[') inClass = true;
+        else if (text[i] === ']') inClass = false;
+        i++;
+      }
+      i++;
+      prev = ')';
+    } else {
+      if (!/\s/.test(c)) {
+        const word = /[A-Za-z_$]/.test(c) ? text.slice(i).match(/^[\w$]+/)[0] : c;
+        prev = word === 'return' ? 'return' : word.length > 1 ? 'a' : c;
+        i += word.length;
+        continue;
+      }
+      i++;
+    }
+  }
+  return mask;
+}
+
+const used = new Set();
+
+function findViolations(rel, text) {
+  const out = [];
+  const mask = literalMask(text);
+  const lines = text.split('\n');
+  const starts = [];
+  let off = 0;
+  for (const l of lines) { starts.push(off); off += l.length + 1; }
+  for (const m of text.matchAll(COMMAND_RE)) {
+    if (!mask[m.index]) continue;
+    let ln = starts.findIndex((st, k) => k === starts.length - 1 || starts[k + 1] > m.index);
+    const line = lines[ln];
+    const idx = ALLOWLIST.findIndex((a) => a.file === rel && line.includes(a.contains));
+    if (idx >= 0) { used.add(idx); continue; }
+    out.push(`${rel}:${ln + 1}: ${line.trim()}`);
+  }
+  return out;
+}
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// Sanity del rilevatore: deve fermare il literal originale e ignorare i path.
+ok('detector flags the original review-offer literal',
+  findViolations('x.js', "  '3) open /trailhead:config to pick per key.',").length === 1);
+ok('detector flags a bare /trailhead in a literal',
+  findViolations('x.js', "console.log('run /trailhead to start');").length === 1);
+ok('detector ignores comment lines', findViolations('x.js', '// run /trailhead:update').length === 0);
+ok('detector ignores path segments',
+  findViolations('x.js', "path.join('skills/trailhead/hooks', 'refs/heads/trailhead/t1')").length === 0);
+ok('detector flags a concatenated literal', findViolations('x.js', "const c = '/trailhead:' + v;").length === 1);
+ok('detector flags a template literal with interpolation', findViolations('x.js', 'const c = `/trailhead:${v}`;').length === 1);
+ok('detector flags a literal on a later line of a multi-line template',
+  findViolations('x.js', 'const t = `first line\nrun /trailhead:config now`;').length === 1);
+ok('detector flags the glob and placeholder forms',
+  findViolations('x.js', "a('/trailhead:*'); b('/trailhead:<verb>');").length === 2);
+ok('detector ignores a regex literal with an escaped slash',
+  findViolations('x.js', "const R = /^refs\\/heads\\/trailhead\\/t(\\d+)$/; const q = /['\"]/;").length === 0);
+ok('detector ignores the host-neutral helper form',
+  findViolations('x.js', 'const c = commandForm(host, "config");').length === 0);
+
+// Le eccezioni in allowlist devono ancora corrispondere a qualcosa.
+for (const a of ALLOWLIST) {
+  ok(`allowlist file exists: ${a.file}`, fs.existsSync(path.join(ROOT, a.file)));
+  ok(`allowlist reason given: ${a.file}`, a.reason.length > 0);
+}
+
+const files = SCAN_DIRS.flatMap(({ dir, skip }) => listJs(dir, skip));
+ok('scan covers hook libs, templates and bin', files.length > 20);
+const violations = files.flatMap((rel) => findViolations(rel, fs.readFileSync(path.join(ROOT, rel), 'utf8')));
+assert.deepStrictEqual(violations, [],
+  `literal di comando Claude in codice runtime (usa commandForm):\n${violations.join('\n')}`);
+passed++;
+const unused = ALLOWLIST.filter((_, i) => !used.has(i)).map((a) => `${a.file}: ${a.contains}`);
+assert.deepStrictEqual(unused, [], `voci di allowlist mai usate (da rimuovere):\n${unused.join('\n')}`);
+passed++;
+
+console.log(`runtime-command-literals.test.js: ${passed} assertions passed`);

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

@@ -35,23 +35,31 @@ 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/');
-    const b = para.indexOf('~/.claude/trailhead/templates/');
+    const b = para.indexOf('${CLAUDE_CONFIG_DIR:-~/.claude}/trailhead/templates/');
     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.0",
+  "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.0",
+  "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-code-review.md

@@ -19,7 +19,7 @@ Never `cd` (or `pushd`/`env -C`) into a directory first; the full rule is in `_s
 <!-- trailhead:agent-block reviewing -->
 **Return contract.** Return the complete report as your final message. Do not post it anywhere (no issue comment, no PR comment): the orchestrator posts the `VERIFY` comment after it checks the status line.
 - The first line of the report is the technique's `status:` line, verbatim: `status: <token>`, with nothing before it and no other `status:` line.
-- trailhead-verify: `<token>` is one of `met` | `gaps_found` | `inconclusive`.
-- trailhead-code-review: `<token>` is one of `clean` | `issues_found`, and line 2 is the counts line `critical: <n> · warning: <n> · info: <n>`.
+- 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.
 <!-- /trailhead:agent-block reviewing -->