@marcomigozzi/trailhead 0.16.1 → 0.18.0

package/bin/engine-route-docs.test.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// Docs test per #325: ogni step del motore decide inline vs dispatch con
+// model-route.js, non con la regola in prosa. Il testo canonico vive una volta
+// in techniques.md; ogni punto di dispatch ha un gate imperativo che lo richiama.
+// Run: node engine-route-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const root = path.join(__dirname, '..');
+const skills = path.join(root, 'plugins', 'trailhead', 'skills');
+const read = (rel) => fs.readFileSync(path.join(skills, rel), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const SECTION = '**Route every step through model-route.js.**';
+const SECTION_NAME = 'Route every step through model-route.js';
+
+// --- Parte A: la sezione canonica in techniques.md -----------------------------------
+{
+  const techniques = read('_shared/techniques.md');
+  const at = techniques.indexOf(SECTION);
+  ok('A: techniques.md has the canonical routing paragraph', at !== -1);
+  const sec = at === -1 ? '' : techniques.slice(at, techniques.indexOf('\n\n', at));
+  const has = (...needles) => needles.every((n) => sec.includes(n));
+  ok('A: the command with every flag',
+    has('model-route.js <key> --session <your full model id>', '--session-effort', '--host codex', '--no-subagents', '<project root>'));
+  ok('A: the two-path <hooks> lookup', has('../../hooks/lib/', '../trailhead/hooks/lib/', 'model-defaults-review.js'));
+  ok('A: where the model id comes from', has('The exact model ID is', 'pass `unknown` only if it is truly absent'));
+  ok('A: the key per step', has(
+    'Plan -> `plan`', 'Execute -> `execute`', 'Fix -> `execute`', 'Code review -> `review`',
+    'Goal-backward verification -> `verify`', 'Research -> `research`', 'Debug -> `debug`',
+    'Codebase map -> `codebase-map`', 'Grilling -> `grill`'));
+  ok('A: Fix spawns trailhead-fix in place of the returned agent', has('spawn `trailhead-fix` in place of the returned `agent`'));
+  ok('A: Grilling keeps its own section', has('**Who runs a round**'));
+  ok('A: route inline, suggest and warning', has('`route: inline`', '`suggest`', '`warning`'));
+  ok('A: route dispatch uses agent and alias verbatim', has('`route: dispatch`', 'use its `agent` and `alias` verbatim'));
+  ok('A: no hand decision', has('Never decide inline versus dispatch by hand', 'never read the config yourself'));
+  ok('A: an unregistered agent runs inline', has('not registered', 'inline'));
+  ok('A: the lean exception', has('accepted `lean` skip'));
+  ok('A: the autonomous-run exception dispatches with no model override on an inline route',
+    has('more than one slot', 'no model override'));
+  ok('A: Codex spawns by agent_type, with a null alias', has('`agent_type=<agent>` on Codex', '`alias` is null'));
+  ok('A: Claude Code passes alias as the Agent model override', has('`alias` as the `Agent` model override on Claude Code'));
+  const rule = sec.indexOf('Never decide inline versus dispatch by hand');
+  const lean = sec.indexOf('accepted `lean` skip');
+  const auto = sec.indexOf('more than one slot');
+  ok('A: both exclusions are stated after the rule, inside the paragraph',
+    rule !== -1 && lean > rule && auto > rule && sec.indexOf('Two cases sit outside the route') > rule);
+  ok('A: the helper still runs in the autonomous case', sec.slice(auto).includes('the helper is still run'));
+  const dispatch = techniques.split('\n')[4] || '';
+  ok('A: the dispatch paragraph points at the routing paragraph', dispatch.includes(SECTION_NAME));
+  ok('A: the dispatch paragraph no longer restates the hand rule',
+    !dispatch.includes('running inline instead only when') && !dispatch.includes('Keep the inline-vs-subagent decision on the full id'));
+}
+
+// --- Parte B: il gate a ogni punto di dispatch ---------------------------------------
+const gateOk = (text, key) =>
+  text.includes(`model-route.js ${key} --session <your full model id> <project root>`) &&
+  text.includes('obey its `route`') &&
+  text.includes('never decide inline versus dispatch by hand') &&
+  text.includes(SECTION_NAME);
+
+{
+  const engines = read('trailhead-work/references/ticket-engines.md');
+  const lines = engines.split('\n');
+  const line = (prefix) => lines.find((l) => l.startsWith(prefix)) || '';
+  ok('B: build Plan gates on plan', gateOk(line('2. **Plan**:'), 'plan'));
+  ok('B: build Execute Dispatch gates on execute', gateOk(line('   - **Dispatch.** Spawn the **`trailhead-executor`**'), 'execute'));
+  ok('B: bug Diagnose gates on debug', gateOk(line('2. **Diagnose**:'), 'debug'));
+  const fix = line('   - **Dispatch.** Spawn the **`trailhead-fix`**');
+  ok('B: bug Fix Dispatch gates on execute and spawns trailhead-fix', gateOk(fix, 'execute') && fix.includes('`trailhead-fix`'));
+  ok('B: ticket-engines.md no longer restates the hand rule', !engines.includes('Inline only when the resolved model'));
+  const GATE = '**First, route it.**';
+  for (const [name, l] of [['Plan', line('2. **Plan**:')], ['Execute', line('   - **Dispatch.** Spawn the **`trailhead-executor`**')],
+    ['Diagnose', line('2. **Diagnose**:')], ['Fix', fix]]) {
+    ok(`B: ${name} spawns by agent_type on Codex`, l.includes('agent_type='));
+    const g = l.indexOf(GATE);
+    ok(`B: ${name} gate comes before any lean-skip or exception wording`, g !== -1 && (l.indexOf('`lean`') === -1 || g < l.indexOf('`lean`')));
+  }
+}
+
+for (const [file, key, agent] of [
+  ['code-review.md', 'review', 'trailhead-code-review'],
+  ['verify.md', 'verify', 'trailhead-verify'],
+  ['research.md', 'research', 'trailhead-research'],
+  ['debug.md', 'debug', 'trailhead-debug'],
+  ['codebase-map.md', 'codebase-map', 'trailhead-codebase-map'],
+]) {
+  const text = read(`_shared/techniques/${file}`);
+  const gateAt = text.indexOf('**First, route it.**');
+  const dispatchAt = text.indexOf(`**\`${agent}\`** agent`);
+  const gate = gateAt === -1 ? '' : text.slice(gateAt, text.indexOf('\n', gateAt));
+  ok(`B: ${file} has a routing gate before its dispatch sentence`, gateAt !== -1 && dispatchAt !== -1 && gateAt < dispatchAt);
+  ok(`B: ${file} gate runs model-route.js ${key}`, gateOk(gate, key));
+  ok(`B: ${file} gate exempts the dispatched ${agent}`, gate.includes(`If you are the \`${agent}\` agent, skip this gate`));
+  ok(`B: ${file} no longer restates the hand rule`, !text.includes('inline only when the resolved model'));
+  ok(`B: ${file} gate spawns by agent_type on Codex`, gate.includes('agent_type=<agent>'));
+  ok(`B: ${file} gate points at the canonical paragraph`, gate.includes('Route every step through model-route.js'));
+  ok(`B: ${file} gate comes before any lean-skip wording`, text.indexOf('`lean`') === -1 || gateAt < text.indexOf('`lean`'));
+}
+
+// --- Parte B2: auto.md ---------------------------------------------------------------
+{
+  const auto = read('trailhead-work/references/auto.md');
+  const line = auto.split('\n').find((l) => l.startsWith('- **Background dispatch, never inline.**')) || '';
+  ok('B: auto.md still dispatches every step in the background', line.includes('background subagent'));
+  ok('B: auto.md runs the helper per step', line.includes('model-route.js <key> --session <your full model id> <project root>') && line.includes('Route every step through model-route.js'));
+  ok('B: auto.md spawns with no model override on an inline route', line.includes('`route: inline`') && line.includes('no model override'));
+}
+
+// --- Parte B3: rifiniture della review di #325 --------------------------------------
+{
+  const cr = read('_shared/techniques/code-review.md');
+  ok('B: code-review.md no longer says a lean skip is the only inline review', !cr.includes('only inline review'));
+  ok('B: code-review.md says the review runs inline on route: inline', cr.includes('in the session on `route: inline`'));
+  const audit = read('trailhead-manage/references/auditing.md');
+  ok('B: auditing.md routes verify once per run through model-route.js',
+    audit.includes('routes `verify` once per run through `model-route.js`') && audit.includes('Route every step through model-route.js'));
+  const agent = fs.readFileSync(path.join(root, 'plugins', 'trailhead', 'agents', 'trailhead-codebase-map.md'), 'utf8');
+  ok('B: the codebase-map agent no longer claims it has no model key', !agent.includes('no dedicated model key') && agent.includes('config.models.codebase-map'));
+  const cfg = read('_shared/configuration.md');
+  const ref = read('_shared/configuration-reference.md');
+  ok('B: configuration docs say every key routes through model-route.js',
+    !cfg.includes('every model key runs as a subagent') && !ref.includes('Every model key runs as a subagent') &&
+    cfg.includes('every model key routes through `model-route.js`') && ref.includes('Every model key routes through `model-route.js`'));
+}
+
+// --- Parte C: la config descrive l'helper, non una decisione a mano -------------------
+{
+  const cfg = read('_shared/configuration.md');
+  const ref = read('_shared/configuration-reference.md');
+  ok('C: configuration.md lets the helper decide', cfg.includes('model-route.js') && !cfg.includes('Run Execute inline only when'));
+  const bullet = (k) => ref.split('\n').find((l) => l.startsWith(`- \`${k}\` →`)) || '';
+  ok('C: configuration-reference.md plan bullet points at the helper', bullet('plan').includes('model-route.js') && !bullet('plan').includes('inline only when'));
+  ok('C: configuration-reference.md execute bullet points at the helper', bullet('execute').includes('model-route.js') && !bullet('execute').includes('inline in the session instead when'));
+}
+
+// --- Parte D: l'helper copre ogni chiave nominata ------------------------------------
+{
+  const { AGENT_OF } = require(path.join(root, 'plugins', 'trailhead', 'hooks', 'lib', 'model-route.js'));
+  for (const key of ['plan', 'execute', 'review', 'verify', 'research', 'debug', 'codebase-map', 'grill']) {
+    ok(`D: model-route.js knows ${key} on both hosts`, !!AGENT_OF.claude[key] && !!AGENT_OF.codex[key]);
+  }
+}
+
+// --- Parte E: #350, ogni agent del motore parte con contesto fresco, mai un fork ---------
+{
+  const techniques = read('_shared/techniques.md');
+  ok('E: techniques.md states engine agents spawn with fresh context, never a fork',
+    /fresh context, never a fork/.test(techniques) && techniques.includes('fork_turns'));
+}
+
+console.log(`engine-route-docs.test.js: ${passed} checks passed`);

package/bin/facet-stamp-docs.test.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// Docs test for #360: every codebase facet is stamped with the commit it is true
+// at, the Resolve patches of build and bug restamp the facet they touch, and the
+// audit flags facets whose files moved after their stamp.
+// Run: node facet-stamp-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const root = path.join(__dirname, '..');
+const skills = path.join(root, 'plugins', 'trailhead', 'skills');
+const docs = path.join(root, 'site', 'src', 'content', 'docs', 'docs');
+const read = (...p) => fs.readFileSync(path.join(...p), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const map = read(skills, '_shared', 'techniques', 'codebase-map.md');
+const substrate = read(skills, '_shared', 'substrate.md');
+const engines = read(skills, 'trailhead-work', 'references', 'ticket-engines.md');
+const auditing = read(skills, 'trailhead-manage', 'references', 'auditing.md');
+const manage = read(docs, 'commands', 'manage.md');
+const concepts = read(docs, 'concepts.md');
+const readmes = [['README.md', read(root, 'README.md')], ['README.it.md', read(root, 'README.it.md')]];
+
+// The format and who writes it: codebase-map.md.
+ok('map: facet stamp format', map.includes('`_as of <short sha>_`'));
+ok('map: stamp comes from the scan root HEAD', map.includes('`git -C <scan root> rev-parse --short HEAD`'));
+ok('map: a full re-run restamps every facet', /full re-run[^.]*restamps? (?:all|every)/i.test(map));
+ok('map: the restamp rule is not a parenthetical splitting the sentence', !/restamps all of them\)/.test(map));
+ok('map: a patch passes --stamp', map.includes('--section "<facet>" --stamp <short sha>'));
+ok('map: an unstamped facet gains it on its next patch', /no stamp[^.]*gains it on its next patch/i.test(map));
+ok('map: an untouched facet keeps its stamp', /untouched[^.]*keeps its (?:old )?stamp/i.test(map));
+
+// The substrate row states the stamp.
+const codebaseRow = substrate.split('\n').find((l) => l.startsWith('| Codebase |')) || '';
+ok('substrate: Codebase row states the stamp', codebaseRow.includes('`_as of <short sha>_`'));
+
+// Resolve of build and bug.
+const resolves = engines.split('\n').filter((l) => l.startsWith('5. **Resolve**'));
+ok('engines: build and bug Resolve both found', resolves.length === 2);
+for (const [name, line] of [['build', resolves[0] || ''], ['bug', resolves[1] || '']]) {
+  ok(`engines ${name}: the facet patch passes --stamp`, line.includes('--stamp'));
+  ok(`engines ${name}: stamp is the trunk tip after integration`, /trunk tip/.test(line));
+  ok(`engines ${name}: a pr not merged yet stamps the fork point`, line.includes('git merge-base HEAD origin/<trunk>'));
+  ok(`engines ${name}: by-hand fallback updates the stamp line`, /by hand[^.]*stamp line/i.test(line));
+}
+
+// The audit.
+const secStart = auditing.indexOf('## 7b. Codebase facets');
+const secEnd = auditing.indexOf('## 8. Report');
+const sec = secStart >= 0 ? auditing.slice(secStart, secEnd) : '';
+ok('auditing: 7b sits between 7 and 8', secStart > auditing.indexOf('## 7. Compare the open tickets') && secEnd > secStart);
+ok('auditing 7b: runs the script facets command', sec.includes('trailhead-audit-walk.js facets --repo'));
+ok('auditing 7b: whole-repo runs only', /whole-repo/.test(sec) && /\[map\]/.test(sec));
+ok('auditing 7b: no codebase issue skips it', /no `trailhead:codebase` issue/.test(sec));
+ok('auditing 7b: singleton fail-closed lookup', /fail-closed/.test(sec));
+ok('auditing 7b: body in a private mktemp directory removed on every path', sec.includes('mktemp -d') && /every path/.test(sec));
+ok('auditing 7b: a script failure never blocks the audit or the marker', /never blocks the audit or the marker/.test(sec));
+for (const status of ['current', 'stale', 'unstamped', 'unresolved', 'no-paths']) {
+  ok(`auditing 7b: status ${status}`, sec.includes(`\`${status}\``));
+}
+ok('auditing 7b: current is not proof either, a patch moves the stamp over the whole facet', /`current` is not proof/.test(sec) && /whole facet/.test(sec));
+const report = auditing.slice(secEnd, auditing.indexOf('## 9. Proposals'));
+ok('auditing 8: report lists stale facets with changed files, outside the sum', /stale facets?[^.]*changed files/i.test(report) && /outside the (?:class )?sum/.test(report));
+const proposals = auditing.slice(auditing.indexOf('## 9. Proposals'), auditing.indexOf('## 10.'));
+ok('auditing 9: stale facets get no proposal', /\*\*Stale facets\*\* → no proposal/.test(proposals));
+
+// Reader-facing docs.
+ok('site manage: audit mentions stale codebase facets', /codebase facet/i.test(manage) && /as of/.test(manage));
+ok('site concepts: codebase bullet mentions the stamp', concepts.split('\n').some((l) => l.includes('`trailhead:codebase`') && /as of/.test(l)));
+
+for (const [name, text] of readmes) {
+  const lines = text.split('\n');
+  ok(`${name}: codebase bullet mentions the stamp`, lines.some((l) => l.includes('`trailhead:codebase`') && l.includes('`_as of <short sha>_`')));
+  ok(`${name}: audit paragraph mentions stale codebase facets`, lines.some((l) => l.startsWith('`/trailhead:audit') && l.includes('`_as of <short sha>_`')));
+}
+
+console.log(`facet-stamp-docs.test.js: ${passed} checks passed`);

package/bin/forced-mutation-docs.test.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// Docs test for #357: a red obtained by forcing a change (mutating code or a
+// fixture) counts only after the change is shown to have landed, stated by the
+// RED step of TDD and by the "watch it fail" step of Debug.
+// Run: node forced-mutation-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const techniques = path.join(__dirname, '..', 'plugins', 'trailhead', 'skills', '_shared', 'techniques');
+const read = (...p) => fs.readFileSync(path.join(...p), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const RULE = 'prove the change landed before trusting the run: diff the mutated file against a clean copy, or re-read it, and see the mutation there';
+const WHY = 'A mutation that silently failed to apply leaves the code as it was, so the run proves nothing';
+
+const tdd = read(techniques, 'tdd.md');
+const debug = read(techniques, 'debug.md');
+
+const red = tdd.split('\n').find((l) => l.startsWith('- **RED**:')) || '';
+ok('tdd: the RED step carries the rule', red.includes(RULE));
+ok('tdd: the RED step says why', red.includes(WHY));
+
+const verifyFix = debug.split('\n').find((l) => l.startsWith('9. **Verify the fix.**')) || '';
+ok('debug: the rule follows "watch it fail"', verifyFix.indexOf(RULE) > verifyFix.indexOf('Watch it fail') && verifyFix.includes('Watch it fail'));
+ok('debug: the step says why', verifyFix.includes(WHY));
+
+for (const [name, text] of Object.entries({
+  'tdd.md': tdd,
+  'debug.md': debug,
+  'forced-mutation-docs.test.js': read(__dirname, 'forced-mutation-docs.test.js'),
+})) {
+  ok(`${name} has no em-dash`, !text.includes(String.fromCharCode(0x2014)));
+}
+
+console.log(`forced-mutation-docs.test.js: ${passed} checks passed`);

package/bin/grill-model-docs.test.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// Docs test per #323: Grilling gira su models.grill / trailhead-grill, con la sessione
+// principale come orchestratore HITL. Il protocollo e' scritto una volta (grilling.md);
+// i punti d'ingresso lo richiamano soltanto.
+// Run: node grill-model-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const root = path.join(__dirname, '..');
+const skills = path.join(root, 'plugins', 'trailhead', 'skills');
+const read = (rel) => fs.readFileSync(path.join(skills, rel), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// --- Parte A: configuration-reference.md e configuration.md --------------------------
+{
+  const ref = read('_shared/configuration-reference.md');
+  const cfg = read('_shared/configuration.md');
+  const lines = ref.split('\n');
+  const rowStart = (prefix) => lines.find((l) => l.startsWith(prefix)) || '';
+  ok('A: models.{...} key-table row lists grill', /^\| `models\.\{[^}]*\bgrill\b[^}]*\}`/.test(rowStart('| `models.{')));
+  ok('A: models.codex.{...} key-table row lists grill', /^\| `models\.codex\.\{[^}]*\bgrill\b[^}]*\}`/.test(rowStart('| `models.codex.{')));
+  ok('A: Models bullet for grill', lines.some((l) => /^- `grill`:/.test(l) && l.includes('Grilling')));
+  ok('A: subagent bullet maps grill to trailhead-grill and says the session keeps asking the user',
+    lines.some((l) => /^- `grill`/.test(l) && l.includes('trailhead-grill') && /session (keeps|still) ask/.test(l)));
+  const header = lines.find((l) => l.startsWith('| profile |')) || '';
+  ok('A: profile table has a grill column', header.includes('| grill |'));
+  const col = (name) => {
+    const idx = header.split('|').map((c) => c.trim()).indexOf('grill');
+    const row = lines.find((l) => l.startsWith(`| **${name}** |`)) || '';
+    return row.split('|').map((c) => c.trim())[idx];
+  };
+  ok('A: grill column reads High strong, Balanced strong, Low standard',
+    col('High') === 'strong' && col('Balanced') === 'strong' && col('Low') === 'standard');
+  ok('A: a profile writes no grill entry, so grill keeps following plan',
+    ref.includes('a profile writes **no `grill` entry**') && ref.includes('keeps following `plan`'));
+  ok('A: the key rows say an unset grill follows plan',
+    rowStart('| `models.{').includes('unset `grill` follows `plan`') && rowStart('| `models.codex.{').includes('unset `grill` follows `models.codex.plan`'));
+  ok('A: Models bullet says unset grill is the same model as plan', lines.some((l) => /^- `grill`:/.test(l) && l.includes('Unset, it uses the same model as `plan`')));
+  ok('A: the unset-default paragraph names the grill exception',
+    ref.includes('the one exception is `grill`: unset, it follows the resolved `models.plan`'));
+  ok('A: Manual path offers grill with "same as plan (Recommended)" first, leaving the key unset',
+    ref.includes('**same as plan (Recommended)** as the first option') && ref.includes('leaves `models.grill` unset') &&
+    ref.includes('leaves `models.codex.grill` unset'));
+  ok('A: a layer that sets plan but not grill implies grill = plan before the merge',
+    ref.includes('a config layer that sets `plan` but not `grill` implicitly sets `grill` to that `plan` for that layer, before the project-over-global merge'));
+  ok('A: existing configs without grill need no action or notice',
+    ref.includes('An existing config with no `grill` key grills on its `plan` model with no action and no notice'));
+  const advanced = lines.filter((l) => l.includes('behind an "Advanced" option') || l.includes('behind Advanced'));
+  ok('A: Advanced lists name grill for Claude and Codex', advanced.length === 2 && advanced.every((l) => l.includes('`grill`')));
+  const everything = lines.find((l) => l.startsWith('**Everything else runs in the main session')) || '';
+  ok('A: Everything else paragraph no longer lists grilling', everything.length > 0 && !/grilling/i.test(everything.split("That's deliberate")[0]));
+  ok('A: Codex sentence (unset inherits, profile or pin brings strong, equal pin runs inline)',
+    /unset `models\.codex\.grill` follows `models\.codex\.plan` when that is pinned/.test(ref) &&
+    ref.includes('else inherits the session model') && ref.includes('an equal pin (same model as the session'));
+  ok('A: a spawn gets the family, not the exact version', ref.includes('A dispatched grill is guaranteed the family of the resolved id, not its exact version'));
+  ok('A: configuration.md names the grill exception to the Balanced default', cfg.includes('except `grill`, which follows `plan`'));
+  ok('A: configuration.md lists grill in the subagent list', /`research`, `review`, `debug`, `verify`, `codebase-map`, `grill`/.test(cfg));
+}
+
+// --- Parte B: grilling.md "Who runs a round" e techniques.md ---------------------------
+{
+  const grilling = read('_shared/techniques/grilling.md');
+  const techniques = read('_shared/techniques.md');
+  const at = grilling.indexOf('\n## Who runs a round');
+  ok('B: grilling.md has a Who runs a round section', at !== -1);
+  const sec = at === -1 ? '' : grilling.slice(at);
+  const has = (...needles) => needles.every((n) => sec.includes(n));
+  const gateAt = grilling.indexOf('**First, before any question: route the round.**');
+  const firstBullet = grilling.indexOf('\n- **Map the decision as a tree.**');
+  ok('B: the routing gate exists and precedes the first round bullet', gateAt !== -1 && firstBullet !== -1 && gateAt < firstBullet);
+  const gate = gateAt === -1 ? '' : grilling.slice(gateAt, firstBullet);
+  ok('B: the gate runs model-route.js grill --session with the session full model id and obeys route',
+    gate.includes('model-route.js grill --session <your full model id> <project root>') && gate.includes('obey its `route`'));
+  ok('B: the gate says where the model id comes from and when to pass unknown',
+    gate.includes('system prompt or environment') && gate.includes('The exact model ID is') && gate.includes('pass `unknown` only if it is truly absent'));
+  ok('B: the gate forbids hand decisions', gate.includes('Never decide inline versus dispatch by hand') && gate.includes('never skip the helper') && gate.includes('never read the config yourself'));
+  ok('B: on dispatch the session does not write the questions and relays the report',
+    gate.includes('you do not write the questions yourself') && gate.includes('spawn `agent` with model `alias`') && gate.includes('relay its report'));
+  ok('B: the gate points at Who runs a round and exempts the dispatched agent', gate.includes('**Who runs a round**') && gate.includes('If you are the `trailhead-grill` agent, skip this gate'));
+  ok('B: the route call, with --session-effort and unknown',
+    has('model-route.js grill --session', '--session-effort', 'unknown', '--no-subagents', '--host codex'));
+  ok('B: the helper is found with the same two-path lookup as model-defaults-review.js',
+    has('../../hooks/lib/', '../trailhead/hooks/lib/', 'model-defaults-review.js'));
+  ok('B: a context-window suffix on the session id is documented as ignored', has('a trailing `[...]` suffix such as `[1m]` is ignored'));
+  ok('B: the per-layer implicit grill rule', has('a config layer that sets `plan` but not `grill` implicitly sets `grill` to that `plan` for that layer, before the project-over-global merge'));
+  ok('B: an unset models.grill follows models.plan', has('`models.grill` unset follows `models.plan`'));
+  ok('B: use its agent and alias verbatim', has('use its `agent` and `alias` verbatim'));
+  ok('B: route inline with the suggest line', has('`route: inline`', '`suggest`', 'suggesting the user switch the session'));
+  ok('B: an unregistered agent runs inline', has('not registered', 'inline'));
+  ok('B: the report is checked with --technique grill', has('--technique grill'));
+  ok('B: the relay never answers on the user\'s behalf', has('relay', 'Never answer on the user\'s behalf', 'never proceed on silence'));
+  ok('B: re-dispatch with the full state', has('re-dispatch with the full state'));
+  ok('B: the orchestrator holds the review cap', has('The orchestrator caps reviews at two', 'accepted risk'));
+  ok('B: the apply/amend/keep menu is the orchestrator\'s', has('apply', 'amend', 'keep', 'AskUserQuestion'));
+  ok('B: the family-not-version note', has('the family of the resolved id, not its exact version'));
+  ok('B: an inline round writes no report', has('An inline round writes no report'));
+  ok('B: Codex semantics', has('unset `models.codex.grill` follows `models.codex.plan` when that is pinned', 'else inherits the session model', 'equal to the session model'));
+  ok('B: the protocol bullets above stay the agent\'s protocol', grilling.indexOf('Holistic review before the final confirmation') < at);
+
+  ok('B: grilling.md states that trailhead-grill output is always the report',
+    has('When it runs as `trailhead-grill`, its output is always the report', 'never asks the user live and never shows a menu'));
+  const agent = fs.readFileSync(path.join(root, 'plugins', 'trailhead', 'agents', 'trailhead-grill.md'), 'utf8');
+  ok('B: the agent follows the round bullets and its return contract, not the orchestrator section',
+    agent.includes('round bullets') && agent.includes('Return contract') && !agent.includes('Who runs a round'));
+
+  const dispatch = techniques.split('\n')[4] || '';
+  ok('B: techniques.md dispatch list maps Grilling to trailhead-grill', /Grilling → `trailhead-grill`/.test(dispatch));
+  ok('B: techniques.md read-only list includes trailhead-grill', /\*\*read-only\*\*[^)]*`trailhead-grill`/.test(dispatch));
+  const row = techniques.split('\n').find((l) => l.startsWith('| **Grilling** |')) || '';
+  ok('B: the Grilling index row names models.grill', row.includes('`models.grill`'));
+}
+
+// --- Parte C: i punti d'ingresso puntano a "Who runs a round" per nome -----------------
+{
+  const POINTER = 'Who runs a round';
+  const lineWith = (text, needle) => text.split('\n').find((l) => l.includes(needle)) || '';
+  const points = (label, line) => ok(`C: ${label} points at ${POINTER} with the imperative routing wording`, line.length > 0 && line.includes(POINTER) && line.includes('grilling.md') && line.includes('first run the routing step at the top of'));
+  const chart = read('trailhead-chart/SKILL.md');
+  const standalone = chart.slice(chart.indexOf('## Standalone grill'));
+  points('chart SKILL.md Standalone grill', lineWith(standalone, 'Run a standalone **Grilling**'));
+  const charting = read('trailhead-chart/references/charting.md');
+  points('charting.md Mode 1 Name the destination', lineWith(charting, '1. **Name the destination.**'));
+  points('charting.md Mode 1 Map the frontier', lineWith(charting, '2. **Map the frontier.**'));
+  points('charting.md Mode 1-bis Map the frontier of the remainder', lineWith(charting, '4. **Map the frontier of the remainder**'));
+  points('charting.md Mode 1-bis Name the destination of the remaining stretch', lineWith(charting, '2. **Name the destination of the remaining stretch.**'));
+  const engines = read('trailhead-work/references/ticket-engines.md');
+  points('ticket-engines.md build Discuss', lineWith(engines, '1. **Discuss**: **never auto-grill.**'));
+  points('ticket-engines.md Plan needs_input grill option', lineWith(engines, 'needs_input` -> ask the user the `questions:`'));
+  ok('C: the Plan needs_input pointer is about opting to grill the planner questions',
+    /opts? to grill/.test(lineWith(engines, 'needs_input` -> ask the user the `questions:`')));
+  points('ticket-engines.md decision Converge', lineWith(engines, '2. **Converge.**'));
+  const work = read('trailhead-work/SKILL.md');
+  points('work SKILL.md quick Grill only if needed', lineWith(work, '- **Grill only if needed** (Discuss)'));
+}
+
+// --- Parte D: README e README.it.md ---------------------------------------------------
+{
+  for (const file of ['README.md', 'README.it.md']) {
+    const text = fs.readFileSync(path.join(root, file), 'utf8');
+    const lines = text.split('\n');
+    const row = (prefix) => lines.find((l) => l.startsWith(prefix)) || '';
+    ok(`D: ${file} models.{...} row lists grill`, /^\| `models\.\{[^}]*codebase-map,grill\}`/.test(row('| `models.{')));
+    ok(`D: ${file} models.codex.{...} row lists grill`, /^\| `models\.codex\.\{[^}]*codebase-map,grill\}`/.test(row('| `models.codex.{')));
+    ok(`D: ${file} Models bullets carry a grill bullet`, lines.some((l) => /^- `grill`/.test(l) && l.includes('trailhead-grill')));
+    ok(`D: ${file} no longer says grilling runs on the session model`,
+      !/charting, grilling/.test(text));
+    ok(`D: ${file} says grill follows plan when unset`, lines.some((l) => /^- `grill`/.test(l) && l.includes('`plan`') && /unset|non impostat/.test(l)));
+  ok(`D: ${file} carries the Codex note`, text.includes('models.codex.grill') && /models\.codex\.plan/.test(lines.find((l) => l.includes('models.codex.grill') && !l.startsWith('|')) || ''));
+  }
+}
+
+console.log(`grill-model-docs.test.js: ${passed} checks passed`);

package/bin/grilling-holistic-review-docs.test.js

@@ -37,8 +37,12 @@ for (const frag of [
   'contradictions, gaps, choices that break each other or the destination',
   'by question number',
   'say so in one line and go straight to the confirmation',
-  'accept, amend or reject',
-  'reject keeps the choices as they were',
+  'Every non-working combination carries its fix',
+  'say why in one line and name where it goes',
+  'Accepting a combination as a risk is never the proposed fix',
+  'apply, amend or keep',
+  'apply (the first option, recommended) applies every proposed amendment and fix',
+  'keep leaves the choices as they were',
   'consciously accepted risk',
   'reopens that branch',
   'the review runs again on the new set',
@@ -60,7 +64,7 @@ const pointer = (name, text, startsWith) => {
   const l = text.split('\n').find((x) => x.startsWith(startsWith));
   ok(`${name} found`, !!l);
   ok(`${name} references the anchor`, l.includes(ANCHOR));
-  ok(`${name} does not restate the rule`, !l.includes('accepted risk') && !l.includes('reject keeps'));
+  ok(`${name} does not restate the rule`, !l.includes('accepted risk') && !l.includes('keep leaves'));
 };
 pointer('chart SKILL standalone grill', read('trailhead-chart/SKILL.md'), 'Run a standalone **Grilling**');
 const engines = read('trailhead-work/references/ticket-engines.md');

package/bin/guard-axis-docs.test.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// Docs test for #352: code review has a fifth axis, Impossible-state guards,
+// with an evidence rule, a Warning severity cap and explicit non-findings, and
+// the reviewing agent's brief reaches it.
+// Run: node guard-axis-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const root = path.join(__dirname, '..');
+const skills = path.join(root, 'plugins', 'trailhead', 'skills');
+const agents = path.join(root, 'plugins', 'trailhead', 'agents');
+const read = (...p) => fs.readFileSync(path.join(...p), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const review = read(skills, '_shared', 'techniques', 'code-review.md');
+const techniques = read(skills, '_shared', 'techniques.md');
+const engines = read(skills, 'trailhead-work', 'references', 'ticket-engines.md');
+const agent = read(agents, 'trailhead-code-review.md');
+
+const axis = (review.split('\n').find((l) => l.startsWith('- **Impossible-state guards**')) || '');
+const classify = (review.split('\n').find((l) => l.startsWith('Classify each finding')) || '');
+const reuse = (review.split('\n').find((l) => l.startsWith('- **Reuse & simplification**')) || '');
+
+ok('code-review.md: review on five axes', review.includes('Review on five axes:'));
+ok('code-review.md: no four-axes leftover', !review.includes('Review on four axes'));
+
+ok('axis bullet exists', axis.length > 0);
+for (const sub of ['a guard on an impossible state', 'defence already enforced elsewhere', 'a pattern copied without its premises', 'a stale or phantom requirement', 'an abstraction with one instance']) {
+  ok(`axis names subtype: ${sub}`, axis.includes(sub));
+}
+ok('axis extends the speculative generality smell', axis.includes('extends the speculative generality smell'));
+
+ok('axis: the guard code is reachable, the state it guards must be shown impossible',
+  axis.includes("The guard's own code must be reachable (live), while the state it guards against must be shown impossible"));
+ok('classify: this axis is the exception, what is verified is the impossibility',
+  classify.includes('except for Impossible-state guards, where what you verify is that the state cannot occur, not a reachable failing path'));
+
+ok('axis: every finding cites concrete evidence the state cannot occur',
+  axis.includes('Every finding cites concrete evidence (file:line or a doc) that the state cannot occur'));
+ok('axis: admissible evidence kinds',
+  axis.includes('a closed type or enum, an API or framework invariant, fixed configuration, validation already done upstream, or a guarantee of the stack itself'));
+ok('axis: no evidence, no finding, never the reviewer\'s say-so',
+  axis.includes("Without such evidence there is no finding, never the reviewer's say-so"));
+
+ok('axis: severity cap', axis.includes('at most Warning, never Critical, so it never enters the Critical-only fix-and-re-review loop'));
+ok('classify: severity cap', classify.includes('Impossible-state guards findings are at most Warning, never Critical, so they never enter the Critical-only fix-and-re-review loop'));
+
+ok('axis: explicit non-findings',
+  axis.includes('Not findings: trust boundaries (user input, network, files, env), deliberate defence-in-depth, test and DI seams, and dead code (a separate smell, not this axis)'));
+ok('axis: exclusions win over the evidence',
+  axis.includes('The exclusions win over the evidence: no evidence, upstream validation included, turns a check at a trust boundary into a finding.'));
+
+ok('reuse smell list points to the new axis', /speculative generality \(delete; see \*\*Impossible-state guards\*\*\)/.test(reuse));
+
+ok('techniques.md: protocol carried in the spawn prompt', techniques.includes('carries its full protocol in the prompt'));
+ok('techniques.md: Code review row on 5 axes', techniques.includes("review the ticket's own commits (its `Refs: #<n>` set) on 5 axes"));
+const verifyLines = engines.split('\n').filter((l) => l.startsWith('4. **Verify**'));
+ok('ticket-engines.md: build and bug Verify found', verifyLines.length === 2);
+ok('ticket-engines.md: both Verify lines reference techniques/code-review.md', verifyLines.every((l) => l.includes('techniques/code-review.md')));
+ok('agent: names the injected single source', agent.includes('injected at spawn from the trailhead skill\'s single source (`_shared/techniques/code-review.md`)'));
+
+for (const [name, text] of Object.entries({ 'code-review.md': review, 'techniques.md': techniques, 'guard-axis-docs.test.js': read(__dirname, 'guard-axis-docs.test.js') })) {
+  ok(`${name} has no em-dash`, !text.includes(String.fromCharCode(0x2014)));
+}
+
+console.log(`guard-axis-docs.test.js: ${passed} checks passed`);

package/bin/inbox-needs-info-docs.test.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// Docs test for #354: an inbox issue waiting on its reporter is parked with
+// `trailhead:needs-info`, resurfaces only on the reporter's answer, and is offered
+// for closing (never auto-closed) after inbox.needs_info_days.
+// Plain asserts, no framework. Run: node bin/inbox-needs-info-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const root = path.resolve(__dirname, '..');
+const plugin = path.join(root, 'plugins', 'trailhead');
+const read = (rel) => fs.readFileSync(path.join(plugin, rel), 'utf8');
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const inbox = read('skills/trailhead-chart/references/inbox.md');
+const commands = read('skills/_shared/substrate-commands.md');
+const substrate = read('skills/_shared/substrate.md');
+const reference = read('skills/_shared/configuration-reference.md');
+const lineOf = (text, re) => (text.split('\n').find((l) => re.test(l)) || '');
+
+// Four sections, by descriptive name.
+ok('inbox.md presents four sections', inbox.includes('presents **four sections**') && !inbox.includes('presents **three sections**'));
+ok('inbox.md has the Waiting on the reporter section', inbox.includes('**Waiting on the reporter.**'));
+ok('the waiting section reads through the helper with the templates lookup', /trailhead-inbox-needs-info\.js --repo <owner\/name> --config-root <project root>/.test(inbox) && inbox.includes('same three-dir lookup as `trailhead-work-state.js`'));
+ok('a failed helper never guesses answered or timed out', /never guess which are answered or timed out/.test(inbox));
+ok('the proposal list covers the waiting section', /^For each issue in the first three sections \(incoming issues, waiting on the reporter, parked fog/m.test(inbox));
+
+// The Needs info move.
+const needsInfo = inbox.slice(inbox.indexOf('- **Needs info.**'));
+ok('needs info: question posted first, then the label', /post the question \*\*first\*\*, then add `trailhead:needs-info`/.test(needsInfo));
+ok('needs info: ensures the label idempotently', needsInfo.includes('gh label create trailhead:needs-info --color FBCA04') && needsInfo.includes('2>/dev/null || true'));
+ok('resurfacing only on a reporter comment after the label', /only when the reporter comments after the label/.test(needsInfo));
+ok('every move on an answered issue drops the label first', /dropping `trailhead:needs-info` first/.test(needsInfo));
+ok('Ask again removes and re-adds the label', /\*\*Ask again\*\*[^\n]*removes and re-adds the label/.test(needsInfo));
+ok('Keep waiting removes and re-adds the label, stating what a failure leaves', /\*\*Keep waiting\*\* removes and re-adds the label/.test(needsInfo) && /A failed removal keeps the old clock, so the offer returns next run; a failed re-add leaves the issue in the incoming queue/.test(needsInfo));
+ok('a timeout is only an offer, never an automatic close', /only \*\*offered\*\* for closing/.test(needsInfo) && /never closed automatically/.test(needsInfo));
+ok('the label comes off before the close', /remove the label, \*\*then\*\* `gh issue close <n> --reason "not planned"/.test(needsInfo));
+ok('the close message follows ticket.language and asks for a new issue', needsInfo.includes('`config.ticket.language`') && needsInfo.includes('asks for a new issue linking this one'));
+ok('failed steps are reported with the state left behind', /Any failed step of a move is reported naming the issue and the state it was left in/.test(needsInfo));
+ok('the direct /trailhead:inbox <n> path triages whatever the state', /`\/trailhead:inbox <n>` on a needs-info issue triages it directly, whatever its state/.test(needsInfo));
+ok('inbox.md has no em-dash', !inbox.includes(String.fromCharCode(8212)));
+
+// The label set.
+const firstUse = lineOf(commands, /^1\. Create any missing labels/);
+ok('first-use setup lists the label among twenty-two', firstUse.includes('all twenty-two:') && firstUse.includes('`trailhead:needs-info`'));
+ok('substrate-commands.md has the idempotent ensure line', commands.includes('gh label create trailhead:needs-info --color FBCA04 --description "Waiting on the reporter: back in the inbox when they answer" 2>/dev/null || true'));
+ok('substrate.md documents the state label and the count', substrate.includes('**`trailhead:needs-info`**') && substrate.includes('twenty-two labels'));
+ok('the labels guard exempts it (not a ticket)', /EXEMPT = \[[^\]]*'trailhead:needs-info'/.test(fs.readFileSync(path.join(plugin, 'hooks', 'trailhead-labels-guard.js'), 'utf8')));
+ok('the label-guard Action strips any trailhead:* by prefix, so it needs no change', /label\.startsWith\('trailhead:'\)/.test(fs.readFileSync(path.join(root, '.github', 'workflows', 'trailhead-label-guard.yml'), 'utf8')));
+
+// Config.
+ok('configuration-reference documents inbox.needs_info_days, default 14', /\| `inbox\.needs_info_days` \| positive integer \(\*\*`14`\*\*\)/.test(reference) && reference.includes('**inbox.needs_info_days.**'));
+
+// README mirror and site pages.
+for (const f of ['README.md', 'README.it.md', 'site/src/content/docs/docs/configuration.mdx']) {
+  ok(`${f} documents inbox.needs_info_days`, fs.readFileSync(path.join(root, f), 'utf8').includes('`inbox.needs_info_days`'));
+}
+for (const f of ['README.md', 'README.it.md', 'site/src/content/docs/docs/concepts.md']) {
+  ok(`${f} lists the needs-info state label`, fs.readFileSync(path.join(root, f), 'utf8').includes('`needs-info` ('));
+}
+ok('chart.md shows four sections', fs.readFileSync(path.join(root, 'site/src/content/docs/docs/commands/chart.md'), 'utf8').includes('Shows four sections by name'));
+const chartPage = fs.readFileSync(path.join(root, 'site/src/content/docs/docs/commands/chart.md'), 'utf8');
+ok('chart.md no longer says the inbox decides alone', !chartPage.includes('alone on clear ones'));
+ok('chart.md states the explicit yes', chartPage.includes('Nothing is written without your explicit yes'));
+ok('this test has no em-dash', !fs.readFileSync(__filename, 'utf8').includes(String.fromCharCode(8212)));
+
+console.log(`inbox-needs-info-docs.test.js: ${passed} checks passed`);