@marcomigozzi/trailhead 0.17.0 → 0.18.0

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

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

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

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

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

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

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, 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.
+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 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.
+**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>`;
 }
 
@@ -381,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
@@ -396,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') },

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

@@ -94,6 +94,18 @@ 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',
@@ -119,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', (() => {
@@ -175,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) =>

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`);

package/bin/plan-review-budget-docs.test.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// Docs test for #353: plan review skips a reviewer whose prompt exceeds its context.
+// Plain asserts, no framework. Run: node bin/plan-review-budget-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const plugin = path.resolve(__dirname, '..', 'plugins', 'trailhead');
+const read = (rel) => fs.readFileSync(path.join(plugin, rel), 'utf8');
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const review = read('skills/_shared/techniques/plan-review.md');
+const config = read('skills/_shared/configuration-reference.md');
+
+ok('plan-review.md: runs the budget call before each reviewer call', /trailhead-plan-review-rounds\.js budget --repo[^\n]*--reviewer[^\n]*--prompt/.test(review));
+ok('plan-review.md: names the three decisions arg, file, skip', /`arg`:[\s\S]*`file`:[\s\S]*`skip`:/.test(review));
+ok('plan-review.md: file passes the pointer, never the brief as one argument', /`file`:[^\n]*`pointer`[^\n]*never the brief itself as one argument/.test(review));
+ok('plan-review.md: notes the E2BIG limit of a single argument', /128 KiB[^\n]*E2BIG/.test(review));
+ok('plan-review.md: skip does not invoke the reviewer and records the reason', /`skip`:\s*do not invoke[^\n]*`reason`/.test(review));
+ok('plan-review.md: captures stdout and stderr together into one output file', /> <dir>\/<cli>\.out 2>&1/.test(review));
+ok('plan-review.md: a shell-tool launch failure is written into the same file', /shell tool itself fails to launch[^\n]*same file/.test(review));
+ok('plan-review.md: runs the overflow call on a failed call', /trailhead-plan-review-rounds\.js overflow --output/.test(review));
+ok('plan-review.md: overflow true means no retry, recorded as skipped with its reason', /`overflow: true`[^\n]*do not retry[^\n]*skipped[^\n]*`reason`/.test(review));
+ok('plan-review.md: the one-retry rule never applies after an overflow', /One retry \(never after a context overflow\)/.test(review));
+ok('plan-review.md: PLAN-REVIEW lists every skipped or dropped reviewer with its reason, never silent', /`PLAN-REVIEW`[^\n]*every reviewer skipped or dropped, with its reason[^\n]*budget skip[^\n]*context overflow[^\n]*second timeout[^\n]*hard error[^\n]*never a silent drop/.test(review));
+ok('plan-review.md: all reviewers skipped falls back to the no-reviewer rule', /every reviewer ends up skipped[^\n]*no-reviewer-left rule/.test(review));
+
+ok('configuration-reference.md: has the plan_review.context row', /^\| `plan_review\.context` \|/m.test(config));
+ok('configuration-reference.md: explains the 65% rule, the estimate and the post-check', /\*\*plan_review\.context\.\*\*[^\n]*ceil\(bytes \/ 3\)[^\n]*65%[^\n]*not a guarantee[^\n]*not retried/.test(config));
+ok('configuration-reference.md: documents the per-reviewer merge', /\*\*plan_review\.context\.\*\*[^\n]*merge per reviewer[^\n]*project wins/.test(config));
+
+ok('plan-review.md: the overflow call passes the brief so echoed lines are ignored', /overflow --output <dir>\/<cli>\.out --prompt <brief file>/.test(review));
+ok('plan-review.md: a failing budget or overflow helper has a stated fallback', /When `budget` or `overflow` itself fails[^\n]*never guess[^\n]*at most 100 KiB/.test(review));
+
+// #368: every reviewer call is bounded by the run helper.
+ok('plan-review.md: every reviewer call goes through the run subcommand, whatever the launch mode', /Every reviewer call goes through the `run` subcommand, whatever the launch mode[^\n]*trailhead-plan-review-rounds\.js run --output <dir>\/<cli>\.out -- /.test(review));
+ok('plan-review.md: the helper bounds the call because the Bash timeout does not apply to a background call', /helper is what bounds[^\n]*`timeout` parameter does not apply to a background call/.test(review));
+ok('plan-review.md: a timeout skips overflow and takes the one-retry rule', /- `timeout`:[^\n]*\*\*Do not run `overflow`\*\*[^\n]*one-retry rule/.test(review));
+ok('plan-review.md: a second timeout drops the reviewer, recorded with the seconds', /A second timeout \*\*drops\*\*[^\n]*`second timeout`[^\n]*seconds/.test(review));
+ok('plan-review.md: failed or error runs overflow then the one-retry rule', /- `failed` or `error`: run `node <templates>\/trailhead-plan-review-rounds\.js overflow/.test(review));
+ok('plan-review.md: the helper-fails fallback names no JSON line and excludes a status error line', /helper is missing, exits non-zero with no JSON line \(a helper killed by a signal prints none\), or prints non-JSON output\*\*[^\n]*`status: error` JSON line is not this case[^\n]*`failed`\/`error` branch/.test(review));
+ok('plan-review.md: no human prompt on this path, never reported as still running past the bound', /No human prompt anywhere on this path[^\n]*never reported as "still running" past the bound/.test(review));
+ok('plan-review.md: a missing run helper falls back to timeout -k 10 600, 124 or 137 meaning timeout', /helper is missing, exits non-zero[^\n]*`timeout -k 10 600 <cmd> < \/dev\/null > <dir>\/<cli>\.out 2>&1`[^\n]*`gtimeout`[^\n]*124 or 137/.test(review));
+ok('plan-review.md: with no bound available the reviewer is skipped, recorded', /neither available, skip the reviewer, recording that no bound was available/.test(review));
+ok('plan-review.md: the stdin line is not evidence of a stdin hang', /`Reading additional input from stdin\.\.\.` is \*\*not evidence of a stdin hang\*\*/.test(review));
+ok('plan-review.md: the synchronous case still goes through run with the tool timeout above the helper deadline', /still goes through `run`[^\n]*`600000`[^\n]*above the helper's deadline/.test(review));
+ok('plan-review.md: the raw-shell 0% CPU stuck check is gone', !/0% CPU/.test(review));
+const techniques = read('skills/_shared/techniques.md');
+ok('techniques.md: the outcome is awaited up to the bound, a stalled plan reviewer ends as a recorded drop', /the outcome always awaited \(up to its bound[^\n]*stalled reviewer ends as a dropped reviewer, recorded in `PLAN-REVIEW`, never an open wait/.test(techniques));
+
+const root = path.resolve(__dirname, '..');
+const readme = fs.readFileSync(path.join(root, 'README.md'), 'utf8');
+const readmeIt = fs.readFileSync(path.join(root, 'README.it.md'), 'utf8');
+const site = fs.readFileSync(path.join(root, 'site', 'src', 'content', 'docs', 'docs', 'configuration.mdx'), 'utf8');
+for (const [name, text] of [['README.md', readme], ['README.it.md', readmeIt], ['configuration.mdx', site]]) {
+  ok(`${name}: has the plan_review.context row`, /^\| `plan_review\.context` \|/m.test(text));
+}
+
+for (const [name, text] of [['plan-review.md', review], ['configuration-reference.md', config], ['techniques.md', techniques]]) {
+  ok(`${name}: no em-dash`, !text.includes(String.fromCharCode(0x2014)));
+}
+console.log(`plan-review-budget-docs.test.js: ${passed} checks passed`);