@marcomigozzi/trailhead 0.16.1 → 0.17.0

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

@@ -0,0 +1,148 @@
+#!/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]);
+  }
+}
+
+console.log(`engine-route-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/lib/codex-projection.js

@@ -108,11 +108,11 @@ Where the engine uses \`AskUserQuestion\`, pose the choice as a **plain-text num
 After presenting the numbered list, STOP and wait: the user's **next message** is the answer to this pending question, not a fresh unrelated turn. Resolve it by matching either the **number typed** (e.g. "2") or the option's **label text** back onto that option, then continue the engine exactly as it would from a native \`AskUserQuestion\` response (e.g. write the chosen config value, or proceed down the chosen branch). If the reply matches no option, ask again rather than guessing. Never silently pick a default and proceed.
 
 ## D. Subagents (native multi_agent)
-Codex has a subagent toolkit: the multi_agent tools (\`spawn_agent\`, \`send_input\`, \`wait_agent\`, \`resume_agent\`, \`close_agent\`), stable and on by default on supported Codex (the installer gates on the floor that guarantees them). Where the engine delegates to a subagent (research, codebase-map, review, plan, execute, debug), spawn a real Codex subagent with these tools and the technique's own protocol (each technique carries its full protocol in-prompt, so no specialised agent is needed; pass the ticket's \`Scope:\` when relevant). The Claude-only Explore-vs-general-purpose split does not apply: Codex has one subagent kind. A subagent runs as a FRESH session that receives a task prompt, not this conversation; run independent ones in parallel (e.g. the codebase-map readers) and \`wait_agent\` on them.
+Codex has a subagent toolkit: the multi_agent tools (\`spawn_agent\`, \`send_input\`, \`wait_agent\`, \`resume_agent\`, \`close_agent\`), stable and on by default on supported Codex (the installer gates on the floor that guarantees them). Where the engine delegates to a subagent (research, codebase-map, review, plan, execute, debug, grill), spawn a real Codex subagent with these tools and the technique's own protocol (each technique carries its full protocol in-prompt, so no specialised agent is needed; pass the ticket's \`Scope:\` when relevant). The Claude-only Explore-vs-general-purpose split does not apply: Codex has one subagent kind. A subagent runs as a FRESH session that receives a task prompt, not this conversation; run independent ones in parallel (e.g. the codebase-map readers) and \`wait_agent\` on them.
 
 **Never surrender the session to one open-ended \`wait_agent\`; poll instead.** \`wait_agent\` blocks until the subagent returns, so a single unconditional \`wait_agent\` on a long or stalling subagent freezes the whole session with nothing to check: this is the review / plan-review hang. Collect every delegated subagent through a **bounded wait in a poll loop**, not one open-ended blocking call. Give \`wait_agent\` a short timeout (30 to 60s); on each timeout, report a one-line "still running" progress note and loop again, so the session stays responsive and can be checked or interrupted between polls. The two **review** steps, **Code review** and **Cross-AI plan review**, always run this way: backgrounding and polling them (never a blind \`wait_agent\`) is the engine's hard cross-host default, not merely the case where it matters most. They are also the longest quiet activities in the cycle (a full-diff adversarial review, or an external CLI) and the ones most often seen to hang. If your Codex build's \`wait_agent\` exposes no timeout, poll the agent's status/output at intervals instead of blocking, or run the review as a **background job** and check back on it at intervals; the rule is the same either way. When several subagents run in parallel, poll them as a set, a bounded wait cycling across the outstanding handles, reporting which are still running.
 
-**Per-technique agent registry (\`agent_type\` dispatch).** The installer always projects all 8 committed trailhead agents as \`~/.codex/agents/trailhead-<technique>.toml\` (one per technique) and enables \`features.multi_agent_v2\`, so Codex always exposes a per-technique agent registry. A TOML whose technique has a \`models.codex.<key>\` pin set carries that OpenAI model (plus its reasoning effort); every other TOML — an unpinned keyed technique, or the 1 keyless agent — is pin-less and its subagent inherits the session model. Detect the registry at runtime by introspecting the visible \`spawn_agent\` tool schema (GSD-style, never a config read): if its parameters expose an \`agent_type\` field, spawn each delegated activity as \`spawn_agent(agent_type="trailhead-<technique>", reasoning_effort=…)\` (\`trailhead-plan\` for the Plan step, \`trailhead-execute\` for Execute, likewise research/review/debug/verify and \`trailhead-codebase-map\` for the Codebase-map step, plus the 1 keyless \`trailhead-fix\` for the Fix step), which routes it onto that technique's pinned model when one is set, or the session model otherwise. If the \`spawn_agent\` schema exposes NO \`agent_type\` field at all (a Codex build with only base multi_agent v1), spawn with base \`spawn_agent\` and the subagents inherit the one session model. Trust the tool surface you actually see and degrade gracefully: \`multi_agent_v2\` is still under development upstream, so v1 stays a supported runtime.
+**Per-technique agent registry (\`agent_type\` dispatch).** The installer always projects all 9 committed trailhead agents as \`~/.codex/agents/trailhead-<technique>.toml\` (one per technique) and enables \`features.multi_agent_v2\`, so Codex always exposes a per-technique agent registry. A TOML whose technique has a \`models.codex.<key>\` pin set carries that OpenAI model (plus its reasoning effort); every other TOML (an unpinned keyed technique, or fix with execute unset) is pin-less and its subagent inherits the session model. Detect the registry at runtime by introspecting the visible \`spawn_agent\` tool schema (GSD-style, never a config read): if its parameters expose an \`agent_type\` field, spawn each delegated activity as \`spawn_agent(agent_type="trailhead-<technique>", reasoning_effort=…)\` (\`trailhead-plan\` for the Plan step, \`trailhead-execute\` for Execute, likewise research/review/debug/verify \`trailhead-codebase-map\` for the Codebase-map step and \`trailhead-grill\` for a Grilling round, plus \`trailhead-fix\` for the Fix step, which tracks the Execute pin), which routes it onto that technique's pinned model when one is set, or the session model otherwise. An unpinned or session-equal grill runs inline in the main session (no spawn): the main session stays the HITL orchestrator and asks the user itself. If the \`spawn_agent\` schema exposes NO \`agent_type\` field at all (a Codex build with only base multi_agent v1), spawn with base \`spawn_agent\` and the subagents inherit the one session model. Trust the tool surface you actually see and degrade gracefully: \`multi_agent_v2\` is still under development upstream, so v1 stays a supported runtime.
 
 \`config.models.*\` (Claude model ids) still cannot take effect here regardless: Codex's subagent model registry is OpenAI-only, so a Claude id cannot run and those keys collapse to the session model. The honoured namespace on Codex is \`models.codex.*\` (above); the one-time models-collapse notice still applies while a stray \`models.*\` is set and \`models.codex.*\` is empty.
 
@@ -191,10 +191,11 @@ function codexTechniqueKey(name) {
 }
 
 // --- MODEL_KEYS --------------------------------------------------------------
-// The 7 pinnable technique keys, mirroring the models.codex.* namespace. The
-// other committed agent (fix) has no pin key and is always
-// projected pin-less (session model).
-const MODEL_KEYS = new Set(['plan', 'execute', 'research', 'review', 'debug', 'verify', 'codebase-map']);
+// The 8 pinnable technique keys, mirroring the models.codex.* namespace. The
+// other committed agent (fix) has no pin key of its own: it tracks execute.
+// Riconoscimento condiviso di "inherit session" (stesso del router, hooks/lib); modulo senza dipendenze, la proiezione resta pura.
+const { isInheritSession } = require('../../plugins/trailhead/hooks/lib/inherit-session.js');
+const MODEL_KEYS = new Set(['plan', 'execute', 'research', 'review', 'debug', 'verify', 'codebase-map', 'grill']);
 
 // --- codexAgentToml ---------------------------------------------------------
 // Render one Codex custom-agent TOML. When `model` is empty/absent, the TOML
@@ -238,9 +239,10 @@ function codexAgentToml({ name, description, developerInstructions, model, effor
 // readAgentDefs(): every committed plugins/trailhead/agents/trailhead-*.md,
 // each { name, description, tools, body }), return the set of
 // trailhead-<technique>.toml writes the installer should make: ONE per agent,
-// uniformly (all 8 project, always). A keyed agent (plan/execute/research/
-// review/debug/verify/codebase-map) carries its models.codex.<key> pin when set, else is
-// pin-less; the 1 keyless agent (fix) is always pin-less.
+// uniformly (all 9 project, always). A keyed agent (plan/execute/research/
+// review/debug/verify/codebase-map/grill) carries its models.codex.<key> pin when set, else is
+// pin-less; fix has no key and carries the models.codex.execute pin (same
+// string/object/effort/inherit-session handling), so no agent is keyless.
 // Iterates agentDefs in the given order (readAgentDefs sorts by name) so the
 // write order is deterministic.
 function codexAgentTomlPlan(codexHome, codexModels, agentDefs) {
@@ -256,13 +258,19 @@ function codexAgentTomlPlan(codexHome, codexModels, agentDefs) {
 
     let model = null;
     let effort = null;
-    if (MODEL_KEYS.has(key) && models[key] != null) {
-      const raw = models[key];
+    // grill non impostato segue models.codex.plan (come model-route.js).
+    // fix non ha chiave propria: segue models.codex.execute (come model-route.js).
+    let pinKey = key === 'grill' && (models.grill == null || (typeof models.grill === 'string' && models.grill.trim() === '')) ? 'plan' : key;
+    if (key === 'fix') pinKey = 'execute';
+    if ((MODEL_KEYS.has(key) || key === 'fix') && models[pinKey] != null) {
+      const raw = models[pinKey];
+      // "inherit session" e' il default Codex documentato: nessun pin.
+      const isInherit = isInheritSession;
       if (typeof raw === 'string') {
-        if (raw.trim() !== '') model = raw;
+        if (raw.trim() !== '' && !isInherit(raw)) model = raw;
       } else if (typeof raw === 'object') {
         const m = typeof raw.model === 'string' ? raw.model : '';
-        if (m.trim() !== '') {
+        if (m.trim() !== '' && !isInherit(m)) {
           model = m;
           effort = typeof raw.effort === 'string' ? raw.effort : null;
         }
@@ -457,6 +465,7 @@ module.exports = {
   codexClusterAgentsYaml,
   codexAgentToml,
   codexAgentTomlPlan,
+  MODEL_KEYS,
   codexVerbSkillContent,
   codexVerbSkillAgentsYaml,
   codexVerbSkillPlan,

package/bin/lib/codex-projection.test.js

@@ -96,6 +96,8 @@ ok('codexSkillAdapterHeader §D pins the exact agent_type dispatch call shape',
   header.includes('spawn_agent(agent_type="trailhead-<technique>"'));
 ok('codexSkillAdapterHeader §D keeps the base spawn_agent v1 fallback path',
   header.includes('base multi_agent v1') && header.includes('inherit the one session model'));
+ok('codexSkillAdapterHeader §D says all 9 committed agents, names trailhead-grill, and runs an unpinned grill inline',
+  header.includes('all 9 committed') && header.includes('trailhead-grill') && /unpinned or session-equal grill runs inline/.test(header));
 ok('codexSkillAdapterHeader §D warns against a single blocking wait_agent with a poll loop',
   header.includes('bounded wait') && header.includes('poll'));
 ok('codexSkillAdapterHeader §D offers a background-job fallback for a stalling review',
@@ -261,10 +263,10 @@ ok('codexAgentToml escapes a " and \\ in name/description so the TOML stays vali
 })());
 
 // --- codexAgentTomlPlan ---
-// 7-entry stub agentDefs mirroring the real plugins/trailhead/agents/*.md
-// sources: 6 keyed techniques (plan/execute/research/review/debug/codebase-map,
+// 8-entry stub agentDefs mirroring the real plugins/trailhead/agents/*.md
+// sources: 7 keyed techniques (plan/execute/research/review/debug/codebase-map/grill,
 // whose filenames derive from trailhead-executor -> execute and
-// trailhead-code-review -> review) + 1 always-keyless agent (fix).
+// trailhead-code-review -> review) + fix, which tracks the execute pin.
 const STUB_AGENT_DEFS = [
   { name: 'trailhead-plan', description: 'plan desc', tools: 'Read', body: 'Plan body.' },
   { name: 'trailhead-executor', description: 'execute desc', tools: 'Read, Write', body: 'Execute body.' },
@@ -273,37 +275,76 @@ const STUB_AGENT_DEFS = [
   { name: 'trailhead-debug', description: 'debug desc', tools: 'Read', body: 'Debug body.' },
   { name: 'trailhead-fix', description: 'fix desc', tools: 'Read, Write', body: 'Fix body.' },
   { name: 'trailhead-codebase-map', description: 'map desc', tools: 'Read', body: 'Map body.' },
+  { name: 'trailhead-grill', description: 'grill desc', tools: 'Read', body: 'Grill body.' },
 ];
 
-ok('codexAgentTomlPlan: 7 agentDefs -> 7 writes with only the pinned key carrying a model', (() => {
+ok('codexAgentTomlPlan: 8 agentDefs -> 8 writes with only execute (and fix, which tracks it) carrying a model', (() => {
   const plan = codexAgentTomlPlan('/c', { execute: 'gpt-5.6-terra' }, STUB_AGENT_DEFS);
-  if (plan.writes.length !== 7) return false;
+  if (plan.writes.length !== 8) return false;
   const byName = Object.fromEntries(plan.writes.map((w) => [w.name, w]));
   const execute = byName['trailhead-execute'];
   if (!execute || execute.path !== '/c/agents/trailhead-execute.toml') return false;
   if (!execute.content.includes('model = "gpt-5.6-terra"')) return false;
-  const others = plan.writes.filter((w) => w.name !== 'trailhead-execute');
+  const fix = byName['trailhead-fix'];
+  if (!fix || !fix.content.includes('model = "gpt-5.6-terra"')) return false;
+  const others = plan.writes.filter((w) => w.name !== 'trailhead-execute' && w.name !== 'trailhead-fix');
   return others.length === 6 && others.every((w) => !/^model = /m.test(w.content));
 })());
 
-ok('codexAgentTomlPlan: keyless trailhead-fix stays pin-less; trailhead-codebase-map now pins on codebase-map', (() => {
-  const plan = codexAgentTomlPlan('/c', { fix: 'gpt-5.6-terra', 'codebase-map': 'gpt-5.6-terra' }, STUB_AGENT_DEFS);
+ok('codexAgentTomlPlan: models.codex.grill pins trailhead-grill.toml; unset leaves it pin-less', (() => {
+  const pinned = codexAgentTomlPlan('/c', { grill: 'gpt-5.6-sol' }, STUB_AGENT_DEFS).writes.find((w) => w.name === 'trailhead-grill');
+  const unset = codexAgentTomlPlan('/c', {}, STUB_AGENT_DEFS).writes.find((w) => w.name === 'trailhead-grill');
+  return pinned && pinned.path === '/c/agents/trailhead-grill.toml' && pinned.content.includes('model = "gpt-5.6-sol"') &&
+    unset && !/^model = /m.test(unset.content);
+})());
+
+ok('codexAgentTomlPlan: an unset models.codex.grill follows models.codex.plan; a set grill wins', (() => {
+  const find = (m) => codexAgentTomlPlan('/c', m, STUB_AGENT_DEFS).writes.find((w) => w.name === 'trailhead-grill');
+  const follow = find({ plan: { model: 'gpt-5.6-sol', effort: 'high' } });
+  const own = find({ plan: 'gpt-5.6-sol', grill: 'gpt-5.6-terra' });
+  const none = find({ execute: 'gpt-5.6-sol' });
+  const plan = codexAgentTomlPlan('/c', { plan: 'gpt-5.6-sol' }, STUB_AGENT_DEFS).writes.find((w) => w.name === 'trailhead-plan');
+  return follow.content.includes('model = "gpt-5.6-sol"') && follow.content.includes('model_reasoning_effort = "high"') &&
+    own.content.includes('model = "gpt-5.6-terra"') && !/^model = /m.test(none.content) && plan.content.includes('model = "gpt-5.6-sol"');
+})());
+
+ok('codexAgentTomlPlan: a literal inherit session is pin-less for every key, and grill follows it', (() => {
+  const find = (m, n) => codexAgentTomlPlan('/c', m, STUB_AGENT_DEFS).writes.find((w) => w.name === n);
+  const pinned = (w) => /^model = /m.test(w.content);
+  const a = { plan: 'inherit session' };
+  const b = { plan: 'gpt-5.6-sol', grill: 'inherit session' };
+  const c = { execute: ' Inherit Session ', research: { model: 'inherit session', effort: 'high' } };
+  return !pinned(find(a, 'trailhead-plan')) && !pinned(find(a, 'trailhead-grill')) &&
+    !pinned(find(b, 'trailhead-grill')) && find(b, 'trailhead-plan').content.includes('model = "gpt-5.6-sol"') &&
+    !pinned(find(c, 'trailhead-execute')) && !pinned(find(c, 'trailhead-research')) &&
+    !find(c, 'trailhead-research').content.includes('model_reasoning_effort');
+})());
+
+ok('codexAgentTomlPlan: trailhead-fix carries the execute pin (not a fix key); trailhead-codebase-map pins on codebase-map', (() => {
+  const plan = codexAgentTomlPlan('/c', { execute: { model: 'gpt-5.6-sol', effort: 'high' }, fix: 'gpt-5.6-luna', 'codebase-map': 'gpt-5.6-terra' }, STUB_AGENT_DEFS);
   const byName = Object.fromEntries(plan.writes.map((w) => [w.name, w]));
   const fix = byName['trailhead-fix'];
   const map = byName['trailhead-codebase-map'];
   return fix && map &&
-    fix.path === '/c/agents/trailhead-fix.toml' && !/^model = /m.test(fix.content) &&
+    fix.path === '/c/agents/trailhead-fix.toml' && fix.content.includes('model = "gpt-5.6-sol"') &&
+    fix.content.includes('model_reasoning_effort = "high"') && !fix.content.includes('gpt-5.6-luna') &&
     map.path === '/c/agents/trailhead-codebase-map.toml' && map.content.includes('model = "gpt-5.6-terra"');
 })());
 
-ok('codexAgentTomlPlan: empty models object -> 7 pin-less writes (not zero)', (() => {
+ok('codexAgentTomlPlan: trailhead-fix is pin-less when execute is unset or inherit session', (() => {
+  const find = (m) => codexAgentTomlPlan('/c', m, STUB_AGENT_DEFS).writes.find((w) => w.name === 'trailhead-fix');
+  return ![{}, { plan: 'gpt-5.6-sol' }, { execute: 'inherit session' }, { execute: { model: ' Inherit Session ', effort: 'high' } }]
+    .some((m) => /^model = /m.test(find(m).content) || find(m).content.includes('model_reasoning_effort'));
+})());
+
+ok('codexAgentTomlPlan: empty models object -> 8 pin-less writes (not zero)', (() => {
   const plan = codexAgentTomlPlan('/c', {}, STUB_AGENT_DEFS);
-  return plan.writes.length === 7 && plan.writes.every((w) => !/^model = /m.test(w.content));
+  return plan.writes.length === 8 && plan.writes.every((w) => !/^model = /m.test(w.content));
 })());
 
-ok('codexAgentTomlPlan: null models -> 7 pin-less writes (not zero)', (() => {
+ok('codexAgentTomlPlan: null models -> 8 pin-less writes (not zero)', (() => {
   const plan = codexAgentTomlPlan('/c', null, STUB_AGENT_DEFS);
-  return plan.writes.length === 7 && plan.writes.every((w) => !/^model = /m.test(w.content));
+  return plan.writes.length === 8 && plan.writes.every((w) => !/^model = /m.test(w.content));
 })());
 
 ok('codexAgentTomlPlan: object model value on the execute key carries model + model_reasoning_effort', (() => {
@@ -315,7 +356,7 @@ ok('codexAgentTomlPlan: object model value on the execute key carries model + mo
 ok('codexAgentTomlPlan: a keyed key whose object value has no model stays pin-less', (() => {
   const plan = codexAgentTomlPlan('/c', { execute: { effort: 'high' } }, STUB_AGENT_DEFS);
   const execute = plan.writes.find((w) => w.name === 'trailhead-execute');
-  return plan.writes.length === 7 && !/^model = /m.test(execute.content) && !execute.content.includes('model_reasoning_effort');
+  return plan.writes.length === 8 && !/^model = /m.test(execute.content) && !execute.content.includes('model_reasoning_effort');
 })());
 
 ok('codexAgentTomlPlan: description is routed through convertToCodex (host paths rewritten)', (() => {
@@ -470,16 +511,16 @@ ok('convertToCodex keeps CLAUDE_CODE_SESSION_ID intact',
   const shared = parseSource(fs.readFileSync(path.join(__dirname, '../../scripts/agent-blocks.md'), 'utf8'));
   const agentsDir = path.join(__dirname, '../../plugins/trailhead/agents');
   const files = fs.readdirSync(agentsDir).filter((f) => /^trailhead-.*\.md$/.test(f));
-  ok('projection boundaries: found the eight real agents', files.length === 8);
+  ok('projection boundaries: found the nine real agents', files.length === 9);
   ok('projection boundaries: source has common and implementing blocks', !!shared.common && !!shared.implementing);
   // #249: every agent's projected TOML carries exactly its family block, whole.
   const familyOf = {
     'trailhead-verify': 'reviewing', 'trailhead-code-review': 'reviewing',
     'trailhead-executor': 'implementing', 'trailhead-fix': 'implementing',
     'trailhead-debug': 'investigating', 'trailhead-research': 'investigating', 'trailhead-codebase-map': 'investigating',
-    'trailhead-plan': 'plan',
+    'trailhead-plan': 'plan', 'trailhead-grill': 'grilling',
   };
-  const families = ['reviewing', 'implementing', 'investigating', 'plan'];
+  const families = ['reviewing', 'implementing', 'investigating', 'plan', 'grilling'];
   ok('projection boundaries: source has every family block', families.every((f) => !!shared[f]));
   for (const f of files) {
     const name = f.slice(0, -3);

package/bin/lib/host-descriptor.js

@@ -196,7 +196,7 @@ function degradations(host) {
 
   if (descriptor.axes.subagentToolkit === 'none') {
     entries.push({
-      from: 'subagent fan-out (research, codebase-map, review, plan, execute)',
+      from: 'subagent fan-out (research, codebase-map, review, plan, execute, grill)',
       to: 'inline sequential execution in the main session',
     });
   }

package/bin/lib/host-descriptor.test.js

@@ -105,6 +105,12 @@ ok('modelsCollapseNotice(codex, models set) names the set keys', (() => {
   const msg = modelsCollapseNotice('codex', { models: { plan: 'x', execute: 'y' } });
   return typeof msg === 'string' && msg.includes('plan') && msg.includes('execute') && msg.includes('Codex');
 })());
+ok('modelsCollapseNotice(codex, models.grill set) names grill', (() => {
+  const msg = modelsCollapseNotice('codex', { models: { grill: 'claude-opus-5-5' } });
+  return typeof msg === 'string' && msg.includes('(grill)') && msg.includes('models.codex');
+})());
+ok('modelsCollapseNotice is null once models.codex.grill is set',
+  modelsCollapseNotice('codex', { models: { grill: 'claude-opus-5-5', codex: { grill: 'gpt-5.6-sol' } } }) === null);
 ok('modelsCollapseNotice(codex, undefined config) is null',
   modelsCollapseNotice('codex') === null);
 ok('modelsCollapseNotice(claude, models set) is null (Claude honours the keys)',