@marcomigozzi/trailhead 0.16.1 → 0.18.0

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. Every engine subagent must start FRESH (the task prompt only, not this conversation): the spawn turns forking off, because without that \`multi_agent_v2\` defaults \`fork_turns\` to \`all\`, a full-history fork that inherits this conversation and ignores the model/effort override. So **every** \`spawn_agent\` (engine agents, the base v1 fallback, and generic spawns such as research or the codebase-map readers) passes \`fork_turns="none"\` when the visible schema exposes \`fork_turns\` (v2), or \`fork_context=false\` when it exposes \`fork_context\` (v1), and neither when the schema exposes neither (no fork option, so pass neither); key it on the context parameter the schema shows, not on whether \`agent_type\` is present. 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>", fork_turns="none", reasoning_effort=…)\` (the v2 shape: a schema exposing only \`fork_context\` takes \`fork_context=false\` instead of \`fork_turns="none"\`) (\`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\` (still with \`fork_context=false\`, or \`fork_turns="none"\` if that is what the schema exposes) 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.
 
@@ -120,13 +120,13 @@ Codex has a subagent toolkit: the multi_agent tools (\`spawn_agent\`, \`send_inp
 The engine's \`/clear\` is Codex's \`/new\` (start a fresh session). Command references in a handoff use the skill form (\`$trailhead work <n>\`).
 
 ## F. Lifecycle hooks (native Codex hooks)
-Codex has a hook bus, so trailhead's guardrails run as **real Codex hooks**, not degraded prose. The installer registers them in \`~/.codex/hooks.json\`: commit-guard, secret-guard, install-guard, body-guard and labels-guard as \`PreToolUse\` (matcher \`Bash\`) hooks that can veto the command before it runs (the five run in one process, a single \`trailhead-bash-guards.js --guards=commit,secret,install,body,labels\` registration, so a Bash call pays one start-up instead of five), secret-read-guard as a \`PreToolUse\` (matcher \`Read|Bash\`) hook that denies reads of \`.env\`/\`.env.*\`/\`.secrets\`, the injection-scanner as a \`PostToolUse\` (matcher \`Bash\`) advisory, mockup-link-stop as a \`Stop\` hook (when your final reply asks to approve a mockup without carrying its link, it continues the turn so you rewrite the ask with the URL or file path in the prose), and check-update as a \`SessionStart\` hook. On Codex, file reads happen through shell commands rather than a native Read-tool event, so the secret-read guard's enforcement here runs via its **Bash** arm (protection is not lost); the \`Read\` half of its matcher is a Claude-Code-native path, registered on Codex too only so it fires without changes if a future Codex version adds an equivalent event. search-guard is Claude-Code-specific (it only prevents arming Claude's \`Read()\` deny rule under bypass permissions, a mechanism Codex lacks), so it is not projected to Codex at all. They use the same wire format they use on Claude Code (JSON on stdin, a \`decision\`/\`permissionDecision\` verdict on stdout), which Codex accepts. The host-independent git \`commit-msg\` hook is still installed at repo first-use as well (defence in depth), exactly as on Claude. Codex gates hooks behind \`features.hooks = true\` and reviews them for trust on first start: the installer enables the flag, and Codex will ask you to trust trailhead's hooks the next time it starts.
+Codex has a hook bus, so trailhead's guardrails run as **real Codex hooks**, not degraded prose. The installer registers them in \`~/.codex/hooks.json\`: commit-guard, secret-guard, install-guard, body-guard, labels-guard and test-guard as \`PreToolUse\` (matcher \`Bash\`) hooks that can veto the command before it runs (the six run in one process, a single \`trailhead-bash-guards.js --guards=commit,secret,install,body,labels,test\` registration, so a Bash call pays one start-up instead of six), secret-read-guard as a \`PreToolUse\` (matcher \`Read|Bash\`) hook that denies reads of \`.env\`/\`.env.*\`/\`.secrets\`, the injection-scanner as a \`PostToolUse\` (matcher \`Bash\`) advisory, mockup-link-stop as a \`Stop\` hook (when your final reply asks to approve a mockup without carrying its link, it continues the turn so you rewrite the ask with the URL or file path in the prose), and check-update as a \`SessionStart\` hook. On Codex, file reads happen through shell commands rather than a native Read-tool event, so the secret-read guard's enforcement here runs via its **Bash** arm (protection is not lost); the \`Read\` half of its matcher is a Claude-Code-native path, registered on Codex too only so it fires without changes if a future Codex version adds an equivalent event. search-guard is Claude-Code-specific (it only prevents arming Claude's \`Read()\` deny rule under bypass permissions, a mechanism Codex lacks), so it is not projected to Codex at all. They use the same wire format they use on Claude Code (JSON on stdin, a \`decision\`/\`permissionDecision\` verdict on stdout), which Codex accepts. The host-independent git \`commit-msg\` hook is still installed at repo first-use as well (defence in depth), exactly as on Claude. Codex gates hooks behind \`features.hooks = true\` and reviews them for trust on first start: the installer enables the flag, and Codex will ask you to trust trailhead's hooks the next time it starts.
 
 ## G. Design / UI mockups: artifacts -> stitch offer, else local disk
 The \`artifacts\` mockup mode (a Design canvas Artifact built with Claude Code's \`Artifact\` tool; the legacy \`claude.ai/design\` value means the same) does not exist on Codex: there is no \`Artifact\` tool here. When \`config.design\` names it, follow the Prototype technique's fallback: **offer once to switch this project to \`design: stitch\`** (the Google Stitch MCP runs on Codex too), and only on decline produce a throwaway static HTML mockup next to the code (\`disk\`), link it from the ticket, and say why. Never try to create or edit an Artifact on Codex. \`config.design.approval\` still applies unchanged: \`explicit\` waits for the user's go-ahead before any UI code, \`auto\` surfaces the mockup and proceeds.
 
 ## H. Shell timeouts & background jobs (plan-review's external CLIs)
-The **Cross-AI plan review** technique invokes each external reviewer CLI (\`codex exec\`, \`gemini -p\`, \`qwen -p\`, …) through Claude Code's **Bash tool**, and tells the engine to beat that tool's ~2-minute default cut by setting its \`timeout\` parameter to the 10-minute max, or launching the call with \`run_in_background: true\` and collecting it later. Those are Claude Bash-tool knobs with no Codex equivalent, so map the *intent* onto Codex's own shell/exec tool. Reviews never block the session (the engine's hard cross-host default), so **the default is to background the reviewers** and collect them by polling, never block on them: launch each with a trailing \`&\` (or your shell tool's background form), **redirect its stdin from \`/dev/null\` and its output to a file** (\`codex exec … "<prompt>" < /dev/null > out.txt 2>&1 &\`), and poll/collect when it finishes, so several reviewers run in parallel instead of serially eating the wall-clock; or wrap each reviewer invocation in a §D subagent so the long-running call sits behind the multi_agent poll loop. Where a reviewer must run synchronously instead, give that call its **own long timeout** (the \`timeout_ms\` / equivalent on Codex's shell/exec tool, set to several minutes, never the short default), so a reviewer that legitimately runs for minutes is not cut mid-review. Either way plan-review's own rule is unchanged: never rely on a short default timeout, retry once at the wide margin, then drop a still-slow reviewer rather than let it wedge the build. **Close the reviewer's stdin when backgrounding it** (\`< /dev/null\`): \`codex exec\` reads additional prompt input from stdin and blocks on EOF, so a backgrounded reviewer that inherits an open or attached stdin sits idle at "Reading additional input from stdin..." (0% CPU) forever instead of running (passing the prompt as an argument does not exempt it). Guard the poll loop too: a reviewer pinned at 0% CPU with no output past a threshold is stuck, so surface it and drop it after the one retry rather than reporting "still running" indefinitely. This is the external-CLI **shell** path; §D covers the separate **subagent** (\`wait_agent\`) path, and the two are distinct (an external reviewer CLI is a plain shell call, not a spawned Codex subagent).
+The **Cross-AI plan review** technique invokes each external reviewer CLI (\`codex exec\`, \`gemini -p\`, \`qwen -p\`, …) through Claude Code's **Bash tool**, and tells the engine to beat that tool's ~2-minute default cut by setting its \`timeout\` parameter to the 10-minute max, or launching the call with \`run_in_background: true\` and collecting it later. Those are Claude Bash-tool knobs with no Codex equivalent, so map the *intent* onto Codex's own shell/exec tool. Reviews never block the session (the engine's hard cross-host default), so **the default is to background the reviewers** and collect them by polling, never block on them: launch each through the plan-review **\`run\` subcommand** (\`node <templates>/trailhead-plan-review-rounds.js run --output <dir>/<cli>.out -- <the CLI's headless command>\`), backgrounded with a trailing \`&\` (or your shell tool's background form) and the helper's one JSON line sent to a file (\`… run --output out.txt -- codex exec … "<prompt>" > run.json &\`), then poll/collect when it finishes, so several reviewers run in parallel instead of serially eating the wall-clock; or wrap each \`run\` invocation in a §D subagent so the long-running call sits behind the multi_agent poll loop. The helper is what bounds the call (a 600-second wall-clock deadline, SIGTERM then SIGKILL to the reviewer's process group); nothing else on Codex limits a backgrounded call. Where a reviewer must run synchronously instead, it still goes through \`run\`, and the call gets its **own long timeout** (the \`timeout_ms\` / equivalent on Codex's shell/exec tool, set above the helper's deadline, never the short default), so the helper rather than the tool ends it. Either way plan-review's own rule is unchanged: branch on the JSON \`status\` (a \`timeout\` skips the \`overflow\` check), retry once, then drop a still-slow reviewer, recorded as skipped, rather than let it wedge the build; a reviewer is never reported as "still running" past the bound. **Stdin must be closed on every reviewer call**: \`codex exec\` also reads prompt input from stdin, so a call that inherits an open or attached stdin may wait for EOF (passing the prompt as an argument does not exempt it). The \`run\` helper closes it; the raw fallback (\`timeout -k 10 600 <cmd> < /dev/null > out.txt 2>&1\`, used only when the helper is missing, exits non-zero with no JSON line, or prints non-JSON output; a \`status: error\` JSON line is handled by the \`failed\`/\`error\` branch instead) appends \`< /dev/null\` itself. The line "Reading additional input from stdin..." is not evidence of a stdin hang (codex-cli prints it with stdin already closed), so never diagnose a stall from it. This is the external-CLI **shell** path; §D covers the separate **subagent** (\`wait_agent\`) path, and the two are distinct (an external reviewer CLI is a plain shell call, not a spawned Codex subagent).
 </codex_skill_adapter>`;
 }
 
@@ -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;
         }
@@ -373,9 +381,9 @@ function codexVerbSkillPlan(codexHome, verbs) {
 // --- codexHookEntries -----------------------------------------------------
 // The guardrail hooks trailhead registers on Codex, as {event, matcher,
 // command} records. Commands run the copied hook scripts under hooksScriptsDir
-// via node, matching Claude's `node "<path>"` form. The five Bash guards
-// (commit, secret, install, body, labels) are ONE registration, the merged
-// trailhead-bash-guards.js with `--guards=commit,secret,install,body,labels` (a single
+// via node, matching Claude's `node "<path>"` form. The six Bash guards
+// (commit, secret, install, body, labels, test) are ONE registration, the merged
+// trailhead-bash-guards.js with `--guards=commit,secret,install,body,labels,test` (a single
 // node process per Bash call); secret-read is a separate PreToolUse hook. All
 // PreToolUse guards can veto; the injection-scanner
 // is a PostToolUse advisory; check-update runs at SessionStart. Reused by the
@@ -388,7 +396,7 @@ function codexVerbSkillPlan(codexHome, verbs) {
 function codexHookEntries(hooksScriptsDir) {
   const cmd = (name) => `node "${path.join(hooksScriptsDir, name)}"`;
   return [
-    { event: 'PreToolUse', matcher: 'Bash', command: `${cmd('trailhead-bash-guards.js')} --guards=commit,secret,install,body,labels` },
+    { event: 'PreToolUse', matcher: 'Bash', command: `${cmd('trailhead-bash-guards.js')} --guards=commit,secret,install,body,labels,test` },
     { event: 'PreToolUse', matcher: 'Read|Bash', command: cmd('trailhead-secret-read-guard.js') },
     { event: 'PostToolUse', matcher: 'Bash', command: cmd('trailhead-issue-injection-scanner.js') },
     { event: 'Stop', matcher: '', command: cmd('trailhead-mockup-link-stop.js') },
@@ -457,6 +465,7 @@ module.exports = {
   codexClusterAgentsYaml,
   codexAgentToml,
   codexAgentTomlPlan,
+  MODEL_KEYS,
   codexVerbSkillContent,
   codexVerbSkillAgentsYaml,
   codexVerbSkillPlan,

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

@@ -94,8 +94,22 @@ ok('codexSkillAdapterHeader §D no longer calls per-subagent model pinning defer
   !header.includes('deferred'));
 ok('codexSkillAdapterHeader §D pins the exact agent_type dispatch call shape',
   header.includes('spawn_agent(agent_type="trailhead-<technique>"'));
+ok('codexSkillAdapterHeader §D passes fork_turns="none" (v2) and fork_context=false (v1) on every spawn',
+  header.includes('fork_turns="none"') && header.includes('fork_context=false'));
+ok('codexSkillAdapterHeader §D pins the full v2 call shape with fork_turns="none"',
+  header.includes('spawn_agent(agent_type="trailhead-<technique>", fork_turns="none"'));
+ok('codexSkillAdapterHeader §D keys the no-fork rule on the context parameter, not on agent_type',
+  header.includes('key it on the context parameter the schema shows, not on whether `agent_type` is present'));
+ok('codexSkillAdapterHeader §D passes neither fork parameter when the schema exposes neither',
+  header.includes('exposes neither') && header.includes('pass neither'));
+ok('codexSkillAdapterHeader §D says a fork_context-only schema takes fork_context=false in the agent_type call',
+  header.includes('v2 shape') && header.includes('takes `fork_context=false` instead'));
+ok('codexSkillAdapterHeader §D no longer claims a subagent is unconditionally FRESH',
+  !header.includes('A subagent runs as a FRESH session'));
 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',
@@ -117,6 +131,10 @@ ok('codexSkillAdapterHeader §H makes backgrounding reviewers the default',
   header.includes('the default is to background the reviewers'));
 ok('codexSkillAdapterHeader §H closes reviewer stdin to avoid the EOF hang',
   header.includes('/dev/null') && header.toLowerCase().includes('stdin'));
+ok('codexSkillAdapterHeader §H bounds every reviewer call through the run subcommand (#368)',
+  header.includes('trailhead-plan-review-rounds.js run --output') && header.includes('timeout_ms') && header.includes('above the helper') &&
+  header.includes('a `timeout` skips the `overflow` check') && header.includes('timeout -k 10 600') &&
+  header.includes('not evidence of a stdin hang') && !header.includes('0% CPU'));
 
 // --- codexVerbSkillContent (#46) ---
 ok('codexVerbSkillContent: SKILL.md frontmatter is at byte 0 with name+description', (() => {
@@ -173,10 +191,10 @@ const entries = codexHookEntries('/h');
 ok('codexHookEntries returns 5 entries', Array.isArray(entries) && entries.length === 5);
 const bashEntries = entries.filter((e) => e.event === 'PreToolUse' && e.matcher === 'Bash');
 ok('codexHookEntries: exactly one PreToolUse/Bash registration', bashEntries.length === 1);
-ok('codexHookEntries: the Bash entry is the merged hook with exactly --guards=commit,secret,install,body,labels',
-  bashEntries[0].command === 'node "/h/trailhead-bash-guards.js" --guards=commit,secret,install,body,labels');
+ok('codexHookEntries: the Bash entry is the merged hook with exactly --guards=commit,secret,install,body,labels,test',
+  bashEntries[0].command === 'node "/h/trailhead-bash-guards.js" --guards=commit,secret,install,body,labels,test');
 ok('codexHookEntries: no per-guard script is registered on its own', entries.every((e) =>
-  !/trailhead-(commit|secret|install|search|body)-guard\.js/.test(e.command)));
+  !/trailhead-(commit|secret|install|search|body|test)-guard\.js/.test(e.command)));
 ok('codexHookEntries: secret-read-guard is PreToolUse/Read|Bash', entries.some((e) =>
   e.event === 'PreToolUse' && e.matcher === 'Read|Bash' && e.command.includes('trailhead-secret-read-guard.js')));
 ok('codexHookEntries: injection-scanner is PostToolUse/Bash', entries.some((e) =>
@@ -261,10 +279,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 +291,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 +372,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 +527,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)',

package/bin/needs-you-docs.test.js

@@ -30,10 +30,17 @@ ok('work claim step has the by-hand fallback', claimStep.includes('gh issue edit
 ok('a failed clear is reported, never blocking the claim (work)', /failed `clear` is reported to the user in one line but never blocks the claim/.test(claimStep));
 ok('a failed clear is reported, never blocking the claim (quick)', /failed `clear` is reported to the user in one line but never blocks the claim/.test(quickBullet));
 
-ok('substrate.md documents the label, off every run, on the human frontier', /\*\*`trailhead:needs-you`\*\*[\s\S]{0,900}not a frontier exclusion for humans/.test(substrate) && substrate.includes('twenty-one labels'));
+ok('substrate.md documents the label, off every run, on the human frontier', /\*\*`trailhead:needs-you`\*\*[\s\S]{0,900}not a frontier exclusion for humans/.test(substrate) && substrate.includes('twenty-two labels'));
 ok('substrate-commands.md ensures the label idempotently', commands.includes('gh label create trailhead:needs-you --color D93F0B --description "Needs you: an autonomous run parked it for the human" --force'));
 ok('substrate-commands.md documents park and clear', commands.includes('trailhead-needs-you.js park --issue <n> --reason <text> --repo <owner/name>') && commands.includes('trailhead-needs-you.js clear --issue <n> --repo <owner/name>'));
-ok('substrate-commands.md first-use list has twenty-one labels', /all twenty-one:[^\n]*`trailhead:needs-you`/.test(commands));
+ok('substrate-commands.md first-use list has twenty-two labels', /all twenty-two:[^\n]*`trailhead:needs-you`/.test(commands));
+
+// Un ticket chiuso non tiene mai il mark, comunque sia stato chiuso.
+const SWEEP = 'node <templates>/trailhead-needs-you.js sweep --repo <owner/name>';
+ok('substrate-commands.md: Resolve clears needs-you right after the close', /gh issue close <n>\n[^\n]*\nnode <templates>\/trailhead-needs-you\.js clear --issue <n> --repo <owner\/name>/.test(commands));
+ok('substrate-commands.md documents sweep', commands.includes(SWEEP) && /however it was closed/.test(commands));
+ok('work SKILL.md sweeps at every work-start', work.includes(SWEEP) && /Sweep stale needs-you marks/.test(work));
+ok('auto.md sweeps at run start, before the queue', auto.includes(SWEEP) && /before the queue is read/.test(auto));
 
 for (const [name, text] of [['auto.md', auto], ['SKILL.md', work], ['substrate.md', substrate], ['substrate-commands.md', commands]]) {
   ok(`${name}: no em-dash`, !text.includes(String.fromCharCode(0x2014)));

package/bin/options-in-chat-docs.test.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// Docs test for #365: options posted on the ticket are the record, never the ask surface.
+// The rule is stated once (Grilling technique); call-sites only point at it.
+// Run: node options-in-chat-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const root = path.join(__dirname, '..', 'plugins', 'trailhead');
+const skills = path.join(root, 'skills');
+const read = (rel) => fs.readFileSync(path.join(skills, rel), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const ANCHOR = 'The ask is answerable from the chat alone';
+const DEFINITION = `**${ANCHOR}.**`;
+
+const walk = (dir) => fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+  e.isDirectory() ? walk(path.join(dir, e.name)) : [path.join(dir, e.name)]);
+
+// 1. defined exactly once, in the Grilling technique
+const defs = walk(root).filter((f) => fs.readFileSync(f, 'utf8').includes(DEFINITION));
+ok('definition appears in exactly one file', defs.length === 1);
+ok('definition lives in grilling.md', defs[0] === path.join(skills, '_shared', 'techniques', 'grilling.md'));
+const grilling = read('_shared/techniques/grilling.md');
+ok('definition appears once', grilling.split(DEFINITION).length === 2);
+
+// 2. the definition carries the normative fragments
+const rule = grilling.split('\n').find((l) => l.includes(DEFINITION));
+for (const frag of [
+  'an `OPTIONS` comment, or any comment',
+  'the record, never the ask surface',
+  'renders every option asked about in chat',
+  'a one-line summary',
+  'its trade-off',
+  'the recommendation',
+  'structured question tool',
+  'with no option text',
+]) ok(`rule carries: ${frag}`, rule.includes(frag));
+
+// 3. pointers name the rule without restating it
+const pointer = (name, line) => {
+  ok(`${name} found`, !!line);
+  ok(`${name} references the anchor`, line.includes(ANCHOR));
+  ok(`${name} does not restate the rule`, !line.includes('never the ask surface'));
+};
+const engines = read('trailhead-work/references/ticket-engines.md');
+pointer('decision Diverge', engines.split('\n').find((l) => l.startsWith('1. **Diverge')));
+pointer('decision Converge', engines.split('\n').find((l) => l.startsWith('2. **Converge.**')));
+const relay = grilling.split('\n').find((l) => l.startsWith('   - `question`: relay'));
+pointer('grilling relay of question', relay);
+ok('relay covers a question that only names the options', relay.includes('re-render'));
+pointer('chart standalone grill', read('trailhead-chart/SKILL.md').split('\n').find((l) => l.startsWith('Run a standalone **Grilling**')));
+const agent = fs.readFileSync(path.join(root, 'agents', 'trailhead-grill.md'), 'utf8');
+const q = agent.split('\n').find((l) => l.startsWith('- `question:`'));
+pointer('trailhead-grill question field', q);
+ok('question field asks label, summary, trade-off', q.includes('label') && q.includes('summary') && q.includes('trade-off'));
+
+// 4. no em-dash
+for (const f of [path.join(skills, '_shared/techniques/grilling.md'), path.join(skills, 'trailhead-work/references/ticket-engines.md'),
+  path.join(skills, 'trailhead-chart/SKILL.md'), path.join(root, 'agents', 'trailhead-grill.md'), __filename])
+  ok(`${path.basename(f)} has no em-dash`, !fs.readFileSync(f, 'utf8').includes(String.fromCharCode(8212)));
+
+console.log(`options-in-chat-docs.test.js: ${passed} checks passed`);

package/bin/pick-stress-test-docs.test.js

@@ -89,7 +89,7 @@ for (const frag of ['still current and complete', 'Decisions so far', 'status qu
 // 6. Inbox: nessuna chiusura o commento pubblico senza un si'
 const inbox = read('trailhead-chart/references/inbox.md');
 ok('inbox drops "on your own for clear ones"', !inbox.includes('on your own for clear ones'));
-const intro = lineOf(inbox, (l) => l.startsWith('For each issue in the first two sections'));
+const intro = lineOf(inbox, (l) => l.startsWith('For each issue in the first three sections'));
 for (const frag of ['propose a disposition', 'one list', 'explicit yes', 'never close', 'comment on', 'out-of-scope ruling'])
   ok(`inbox intro carries: ${frag}`, intro.includes(frag));
 const dup = lineOf(inbox, (l) => l.startsWith('- **Duplicate.**'));

package/bin/pipeline-review-docs.test.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// Docs test for #355: code review loads a CI/CD pipeline reliability reference
+// on a pipeline-touching diff only, every finding capped at Warning, and the
+// review brief, the techniques table and the agent all point at it.
+// Run: node pipeline-review-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 refPath = path.join(skills, '_shared', 'techniques', 'code-review-pipeline.md');
+ok('reference file exists', fs.existsSync(refPath));
+const ref = read(refPath);
+const review = read(skills, '_shared', 'techniques', 'code-review.md');
+const techniques = read(skills, '_shared', 'techniques.md');
+const agent = read(agents, 'trailhead-code-review.md');
+
+const route = review.split('\n').find((l) => l.startsWith('**First, route it.**')) || '';
+const para = review.split('\n').find((l) => l.startsWith('**Pipeline reliability (only on a pipeline-touching diff)**')) || '';
+const lines = review.split('\n');
+const classifyIdx = lines.findIndex((l) => l.startsWith('Classify each finding'));
+const paraIdx = lines.findIndex((l) => l.startsWith('**Pipeline reliability (only on a pipeline-touching diff)**'));
+const guardIdx = lines.findIndex((l) => l.startsWith('- **Impossible-state guards**'));
+
+// The reference: the eight checks.
+for (const sub of [
+  '`npm install` where a lockfile exists (use `npm ci` instead)',
+  'a job without `timeout-minutes`',
+  'a deploy without a `concurrency` group',
+  'a rebuild per environment instead of build once, promote',
+  'applies only when the workflow targets more than one environment',
+  'a deploy with neither a health check nor a rollback',
+  '`continue-on-error` on a step that later steps depend on',
+  'static cloud keys where the provider supports OIDC',
+  'a third-party action on `@main` or `@latest`',
+]) {
+  ok(`reference check: ${sub}`, ref.includes(sub));
+}
+
+ok('reference: every finding is a Warning, never Critical',
+  ref.includes('Every finding is a Warning, never Critical, so it never enters the Critical-only fix-and-re-review loop'));
+
+for (const sub of [
+  'global tool installs (`npm install -g`)',
+  'reusable workflows (a job calling one takes neither `timeout-minutes` nor steps of its own)',
+  'actions already pinned to a tag',
+  'test-only workflows (a workflow that runs tests and publishes or deploys nothing: none of the checks apply)',
+]) {
+  ok(`reference non-finding: ${sub}`, ref.includes(sub));
+}
+
+ok('reference: hardcoded secrets stay Critical under Security',
+  ref.includes('Hardcoded secrets are not in this reference: they stay Critical under the Security axis'));
+ok('reference: a deploy finding names what makes it a deploy one',
+  ref.includes('A deploy finding names what makes the workflow a deploy one (a quoted command, an `environment:`, a target)'));
+ok('reference: scope is the ticket diff',
+  ref.includes("only jobs and steps the ticket's commits add or change, per the Ticket diff rule"));
+ok('reference: not a sixth axis', ref.includes('not a sixth axis'));
+
+// The brief: route paragraph.
+ok('route: first-line route structure kept', route.includes('**First, route it.** Run `node <hooks>/lib/model-route.js review'));
+ok('route: spawn prompt carries the pipeline reference line', route.includes('`pipeline reference: <absolute path>`'));
+ok('route: path is code-review-pipeline.md beside the code-review.md just read',
+  route.includes('`code-review-pipeline.md` in the same directory as the `code-review.md` you just read by absolute path'));
+ok('route: path only, never the contents', route.includes('never the reference\'s contents'));
+
+// The brief: the new paragraph.
+ok('five axes wording kept', review.includes('Review on five axes:'));
+ok('paragraph exists', para.length > 0);
+ok('paragraph sits after the axes and before Classify', guardIdx >= 0 && paraIdx > guardIdx && paraIdx < classifyIdx);
+for (const sub of [
+  'git -C <repo> show --format= --name-only <sha>',
+  '`.github/workflows/*`',
+  '`Dockerfile*`',
+  '`docker-compose*`',
+  '(basename, at any depth)',
+  'a script with `deploy` in its file name',
+  'a release script under another name is not matched',
+  'on every pass including the lean inline one',
+  'otherwise do not read it',
+  'Inline, it sits beside this file',
+  'the review is incomplete and fails closed',
+  'a Critical finding `pipeline checks did not run` naming the matched path',
+  'status is `issues_found` and Resolve stays blocked',
+  'discards that incomplete report',
+  'never enters the ledger',
+  're-spawns with the path',
+  'HITL checkpoint naming the path',
+  'It is not a sixth axis',
+]) {
+  ok(`paragraph: ${sub}`, para.includes(sub));
+}
+
+// Pointers.
+ok('techniques.md: Code review row on 5 axes kept', techniques.includes("review the ticket's own commits (its `Refs: #<n>` set) on 5 axes"));
+ok('techniques.md: row names the conditional reference', techniques.includes('code-review-pipeline.md'));
+ok('agent: names the reference at the path the spawn names',
+  agent.includes('`code-review-pipeline.md`') && agent.includes('the path the spawn names'));
+ok('agent: injected single source kept', 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-pipeline.md': ref,
+  'code-review.md': review,
+  'techniques.md': techniques,
+  'trailhead-code-review.md': agent,
+  'pipeline-review-docs.test.js': read(__dirname, 'pipeline-review-docs.test.js'),
+})) {
+  ok(`${name} has no em-dash`, !text.includes(String.fromCharCode(0x2014)));
+}
+
+console.log(`pipeline-review-docs.test.js: ${passed} checks passed`);