@marcomigozzi/trailhead 0.14.0 → 0.16.0

package/bin/lib/codex-projection.js

@@ -91,7 +91,7 @@ This trailhead engine is running on **Codex CLI**, not Claude Code. The installe
 trailhead is a native Codex skill. Invoke it as \`$trailhead <verb>\` (e.g. \`$trailhead work\`, \`$trailhead new "idea"\`); bare \`$trailhead\` is smart entry. Never \`/trailhead:<verb>\` (that is the Claude Code surface). Whatever you type after the verb is the arguments. For discoverability the installer also projects one thin skill per verb (\`$trailhead-work\`, \`$trailhead-bug\`, …) that just delegates to \`$trailhead <verb>\`, so the verbs surface in the \`$\`-menu; \`$trailhead <verb>\` stays the canonical form and this SKILL.md the single source of truth. (Codex custom prompts under \`~/.codex/prompts/\` are deliberately NOT used: they do not surface as slash commands.)
 
 ## B. This IS the skill; the engine is split across sibling skill dirs
-Codex loaded this SKILL.md because you invoked \`$trailhead\` (or a \`$trailhead-<verb>\` / \`$trailhead-<cluster>\` entry); there is no separate Skill tool to call. The engine is split across sibling skill dirs under \`~/.codex/skills/\`: the dispatcher (\`trailhead/\`), five cluster skills (\`trailhead-chart/\`, \`trailhead-work/\`, \`trailhead-view/\`, \`trailhead-capture/\`, \`trailhead-manage/\`), and the shared core (\`_shared/\`, no SKILL.md). Read every referenced file **relative to the SKILL.md you are currently in**: a \`references/*.md\` from this skill's own dir, and the shared core (\`../_shared/*.md\`, or \`../../_shared/*.md\` from a \`references/\` file) from the sibling \`_shared/\` dir. Where the dispatcher's routing says "call the Skill tool with skill name \`trailhead-<cluster>\` and arguments \`<verb> <rest>\`", there is no Skill tool on Codex: **Read \`../trailhead-<cluster>/SKILL.md\` (the sibling dir) and follow it**, treating \`<verb> <rest>\` as its arguments.
+Codex loaded this SKILL.md because you invoked \`$trailhead\` (or a \`$trailhead-<verb>\` / \`$trailhead-<cluster>\` entry); there is no separate Skill tool to call. The engine is split across sibling skill dirs under \`~/.codex/skills/\`: the dispatcher (\`trailhead/\`), five cluster skills (\`trailhead-chart/\`, \`trailhead-work/\`, \`trailhead-view/\`, \`trailhead-capture/\`, \`trailhead-manage/\`), and the shared core (\`_shared/\`, no SKILL.md). Resolve every referenced file **relative to the SKILL.md you are currently in** into an absolute path, then read it with a single \`cat <absolute path>\` or the file-read tool (never \`cd\` into a skills dir and then read a relative path): a \`references/*.md\` from this skill's own dir, and the shared core (\`../_shared/*.md\`, or \`../../_shared/*.md\` from a \`references/\` file) from the sibling \`_shared/\` dir. Where the dispatcher's routing says "call the Skill tool with skill name \`trailhead-<cluster>\` and arguments \`<verb> <rest>\`", there is no Skill tool on Codex: **Read \`../trailhead-<cluster>/SKILL.md\` (the sibling dir) and follow it**, treating \`<verb> <rest>\` as its arguments.
 
 ## C. AskUserQuestion -> plain-text numbered list (the guaranteed path on Codex)
 Codex's \`request_user_input\` tool only works in **Plan Mode** (Codex's collaboration mode with a plan-review step). trailhead skills run in Codex's **Default mode**: the installer never enables \`collaboration_modes\` / Plan Mode, so \`request_user_input\` is unavailable here. This is a **permanent, known constraint** of running trailhead on Codex, not a conditional "if unavailable" case.
@@ -113,7 +113,7 @@ 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 and body-guard as \`PreToolUse\` (matcher \`Bash\`) hooks that can veto the command before it runs (the four run in one process, a single \`trailhead-bash-guards.js --guards=commit,secret,install,body\` registration, so a Bash call pays one start-up instead of four), 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 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.
 
 ## 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.
@@ -366,9 +366,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 four Bash guards
-// (commit, secret, install, body) are ONE registration, the merged
-// trailhead-bash-guards.js with `--guards=commit,secret,install,body` (a single
+// 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
 // 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
@@ -381,7 +381,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` },
+    { event: 'PreToolUse', matcher: 'Bash', command: `${cmd('trailhead-bash-guards.js')} --guards=commit,secret,install,body,labels` },
     { 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

@@ -173,8 +173,8 @@ 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',
-  bashEntries[0].command === 'node "/h/trailhead-bash-guards.js" --guards=commit,secret,install,body');
+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: no per-guard script is registered on its own', entries.every((e) =>
   !/trailhead-(commit|secret|install|search|body)-guard\.js/.test(e.command)));
 ok('codexHookEntries: secret-read-guard is PreToolUse/Read|Bash', entries.some((e) =>
@@ -410,6 +410,11 @@ ok('convertToCodex projects the anchor positives to Codex forms', (() => {
 // the projected work skill and handoff carry the set/clear calls.
 ok('convertToCodex keeps the trailhead-work-state.js filename',
   convertToCodex('node <templates>/trailhead-work-state.js set').includes('<templates>/trailhead-work-state.js set'));
+// #253: the Resolve bookkeeping helper filenames survive the projection.
+ok('convertToCodex keeps the trailhead-issue-body.js filename',
+  convertToCodex('node <templates>/trailhead-issue-body.js append --issue 1').includes('<templates>/trailhead-issue-body.js append'));
+ok('convertToCodex keeps the trailhead-dashboard.js filename',
+  convertToCodex('node <templates>/trailhead-dashboard.js --dry-run').includes('<templates>/trailhead-dashboard.js --dry-run'));
 ok('convertToCodex keeps CLAUDE_CODE_SESSION_ID intact',
   convertToCodex('session from CLAUDE_CODE_SESSION_ID when set').includes('CLAUDE_CODE_SESSION_ID'));
 {
@@ -417,6 +422,12 @@ ok('convertToCodex keeps CLAUDE_CODE_SESSION_ID intact',
   const workSkill = convertToCodex(fs.readFileSync(path.join(skillsDir, 'trailhead-work', 'SKILL.md'), 'utf8'));
   ok('projected work skill carries the work-start set call',
     workSkill.includes('trailhead-work-state.js set --repo <working-root> --map <n> --ticket <n> --title "<title>" --step discuss'));
+  // #234: the scope confirm menu call-site and the adapter's numbered-list rule both reach Codex.
+  const workInjected = injectCodexAdapterHeader(workSkill);
+  ok('projected work skill carries the step 3 scope-confirm menu call-site',
+    /AskUserQuestion[\s\S]{0,300}\*\*Proceed\*\*/.test(workInjected));
+  ok('projected work skill carries the adapter AskUserQuestion -> numbered list rule',
+    workInjected.includes('## C. AskUserQuestion -> plain-text numbered list'));
   const handoff = convertToCodex(fs.readFileSync(path.join(skillsDir, '_shared', 'session-handoff.md'), 'utf8'));
   ok('projected session handoff carries the work state clear call',
     handoff.includes('trailhead-work-state.js clear --repo <working-root>'));
@@ -430,4 +441,34 @@ ok('convertToCodex keeps CLAUDE_CODE_SESSION_ID intact',
     autoRef.includes('--auto true --auto-done <n>'));
 }
 
+// #248: the shared boundary blocks survive the Codex projection of every real agent.
+{
+  const { parseSource } = require('../../scripts/sync-agent-blocks.js');
+  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: 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',
+  };
+  const families = ['reviewing', 'implementing', 'investigating', 'plan'];
+  ok('projection boundaries: source has every family block', families.every((f) => !!shared[f]));
+  for (const f of files) {
+    const name = f.slice(0, -3);
+    const body = fs.readFileSync(path.join(agentsDir, f), 'utf8').replace(/^---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/, '');
+    const out = codexAgentToml({ name, description: 'd', developerInstructions: body, model: null, effort: null });
+    ok(`${name}: projection carries the whole common block`, !!shared.common && out.includes(shared.common));
+    ok(`${name}: has a family`, families.includes(familyOf[name]));
+    for (const fam of families) {
+      ok(`${name}: projection ${familyOf[name] === fam ? 'carries the whole' : 'omits the'} ${fam} block`,
+        !!shared[fam] && out.includes(shared[fam]) === (familyOf[name] === fam));
+    }
+  }
+}
+
 console.log(`✓ codex-projection: ${passed} assertions passed`);

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

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Docs test for #282: the needs-you label (an autonomous run parks a ticket for the
+// human) is documented where the run, the claim and the substrate depend on it.
+// Plain asserts, no framework. Run: node bin/needs-you-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 auto = read('skills/trailhead-work/references/auto.md');
+const work = read('skills/trailhead-work/SKILL.md');
+const substrate = read('skills/_shared/substrate.md');
+const commands = read('skills/_shared/substrate-commands.md');
+
+for (const needle of ['trailhead:needs-you', 'trailhead-needs-you.js park', '`NEEDS YOU`', 'needs-you ticket', 'queue skips it', 'does not reconsider it', 'surviving blocking review concern', 'stale-base stop', 'a failing UAT setup'.replace('a failing', 'failing')]) {
+  ok(`auto.md names: ${needle}`, auto.includes(needle));
+}
+ok('auto.md no longer says "set aside" / "set-aside"', !/set[- ]aside|sets? (?:it|that|such a|the) (?:ticket )?aside|sets? .{0,20} aside/i.test(auto));
+
+const claimStep = (work.match(/^2\. Choose the ticket\..*$/m) || [''])[0];
+const quickBullet = (work.match(/^- \*\*Same isolation setup as `work`\.\*\*.*$/m) || [''])[0];
+const CLEAR = 'node <templates>/trailhead-needs-you.js clear --issue <n> --repo <owner/name>';
+ok('work claim step clears needs-you with the helper', claimStep.includes(CLEAR));
+ok('quick isolation bullet clears needs-you with the helper', quickBullet.includes(CLEAR));
+ok('work claim step has the by-hand fallback', claimStep.includes('gh issue edit <n> --remove-label trailhead:needs-you'));
+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-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));
+
+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)));
+}
+console.log(`needs-you-docs.test.js: ${passed} checks passed`);

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

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// Docs test: the agent never offers or acts on its own pick unchecked. The stress-test rule is
+// stated once (choices.md) and pointed at by grilling, the delegate option, auto and the Plan;
+// the Plan carries a Done-when coverage check, decision Diverge re-checks a framed option set,
+// and inbox never closes or answers someone else's issue without the user's yes.
+// Run: node pick-stress-test-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const skills = path.join(__dirname, '..', 'plugins', 'trailhead', 'skills');
+const read = (rel) => fs.readFileSync(path.join(skills, rel), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const ANCHOR = 'Stress-test the pick before offering it';
+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)]);
+const lineOf = (text, pred) => text.split('\n').find(pred);
+
+// 1. la definizione esiste una sola volta, in choices.md
+const defs = walk(skills).filter((f) => fs.readFileSync(f, 'utf8').includes(DEFINITION));
+ok('definition appears in exactly one file', defs.length === 1);
+ok('definition lives in choices.md', defs[0] === path.join(skills, '_shared', 'choices.md'));
+const choices = read('_shared/choices.md');
+ok('definition appears once', choices.split(DEFINITION).length === 2);
+
+// 2. la definizione porta i frammenti normativi
+const rule = lineOf(choices, (l) => l.includes(DEFINITION));
+for (const frag of [
+  'a recommended answer in grilling',
+  '`(Recommended)`',
+  'the delegate option',
+  'an option `auto` takes on its own',
+  'the edge case or failure mode where it breaks',
+  'checked against the code rather than assumed',
+  'the choices already settled',
+  'real holes, not manufactured doubt',
+  'One pass, no loop',
+  'present only that',
+  'Weak point:',
+  'still recommended because',
+  'conversation language',
+  'where no human sees it live',
+  'trivial or already-decided choice',
+]) ok(`rule carries: ${frag}`, rule.includes(frag));
+
+// 3. i call-site puntano alla regola senza ripeterla
+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('manufactured doubt'));
+};
+const grilling = read('_shared/techniques/grilling.md');
+const gl = grilling.split('\n');
+const pickIdx = gl.findIndex((l) => l.startsWith('- **One question at a time, with your pick.**'));
+ok('grilling pick bullet found', pickIdx >= 0);
+pointer('grilling self-check bullet', gl[pickIdx + 1]);
+ok('grilling bullet keeps the per-question check', gl[pickIdx + 1].includes('by question number'));
+ok('grilling pick bullet points at the self-check', gl[pickIdx].includes('stress-tested per the next bullet'));
+pointer('delegate step 2', lineOf(choices, (l) => l.startsWith('2. The agent states **which option it would choose')));
+const auto = read('trailhead-work/references/auto.md');
+const autoLine = lineOf(auto, (l) => l.startsWith('- **Advisory / process choice**'));
+pointer('auto advisory choice', autoLine);
+ok('auto records the weak point', autoLine.includes('`Weak point:` line'));
+const engines = read('trailhead-work/references/ticket-engines.md');
+const plan = lineOf(engines, (l) => l.startsWith('2. **Plan**'));
+pointer('build Plan', plan);
+
+// 4. Plan: copertura del Done when prima di ready
+for (const frag of [
+  '**Coverage check before `ready`.**',
+  'every `Done when` criterion',
+  'a criterion no step delivers is a gap',
+  'return `needs_input`',
+  'the short inline plan too',
+]) ok(`plan carries: ${frag}`, plan.includes(frag));
+
+// 5. Diverge: un set di opzioni gia' inquadrato viene ricontrollato
+const diverge = lineOf(engines, (l) => l.startsWith('1. **Diverge'));
+ok('diverge found', !!diverge);
+ok('diverge no longer skips blindly', !diverge.includes('skip straight to grilling when it did.'));
+for (const frag of ['still current and complete', 'Decisions so far', 'status quo', '`OPTIONS` comment'])
+  ok(`diverge carries: ${frag}`, diverge.includes(frag));
+
+// 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'));
+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.**'));
+for (const frag of ['what each one covers', 'partial overlap', 'not a duplicate'])
+  ok(`inbox duplicate carries: ${frag}`, dup.includes(frag));
+
+// 7. niente em-dash
+for (const rel of ['_shared/choices.md', '_shared/techniques/grilling.md', 'trailhead-work/references/auto.md',
+  'trailhead-work/references/ticket-engines.md', 'trailhead-chart/references/inbox.md'])
+  ok(`${rel} has no em-dash`, !read(rel).includes(String.fromCharCode(8212)));
+ok('this test has no em-dash', !fs.readFileSync(__filename, 'utf8').includes(String.fromCharCode(8212)));
+
+console.log(`pick-stress-test-docs.test.js: ${passed} checks passed`);

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

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+// Pins the report status protocol in the shipped skills (#250, #249): the
+// canonical "Malformed review report" paragraph (every engine-agent report) and
+// VERIFY comment layout in _shared/techniques.md, the clause on both Verify lines of
+// ticket-engines.md, the return-not-post wording in the verify and code-review
+// techniques, and how Plan, Execute, Fix, Diagnose, research and the codebase map
+// read the fields of their agent's report.
+// Run: node report-status-docs.test.js. No framework: plain asserts.
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const skills = path.join(__dirname, '..', 'plugins', 'trailhead', 'skills');
+const read = (...p) => fs.readFileSync(path.join(skills, ...p), 'utf8');
+const techniques = read('_shared', 'techniques.md');
+const verify = read('_shared', 'techniques', 'verify.md');
+const codeReview = read('_shared', 'techniques', 'code-review.md');
+const acceptance = read('_shared', 'techniques', 'acceptance-testing.md');
+const engines = read('trailhead-work', 'references', 'ticket-engines.md');
+const brief = read('trailhead-work', 'references', 'executor-brief.md');
+const research = read('_shared', 'techniques', 'research.md');
+const codebaseMap = read('_shared', 'techniques', 'codebase-map.md');
+const debug = read('_shared', 'techniques', 'debug.md');
+const charting = read('trailhead-chart', 'references', 'charting.md');
+const researchAgent = fs.readFileSync(path.join(__dirname, '..', 'plugins', 'trailhead', 'agents', 'trailhead-research.md'), 'utf8');
+
+// --- the canonical paragraph -------------------------------------------------------
+const start = techniques.indexOf('**Malformed review report');
+ok('techniques.md has the Malformed review report paragraph', start !== -1);
+const neverBlock = techniques.indexOf('**Reviews never block the session');
+ok('the paragraph sits next to "Reviews never block the session"',
+  start !== -1 && neverBlock !== -1 && Math.abs(start - neverBlock) < 2500 && start > neverBlock);
+const para = start === -1 ? '' : techniques.slice(start, techniques.indexOf('\n| Technique |', start));
+const lc = para.toLowerCase();
+ok('the paragraph section was found and is bounded', para.length > 1000 && !para.includes('| **Grilling**'));
+
+ok('it MUST run on every engine-agent report, the two reviews included', /MUST run on every/.test(para)
+  && para.includes('Code review') && para.includes('Goal-backward verification'));
+ok('it names every technique it covers',
+  ['plan', 'executor', 'fix', 'debug', 'research', 'codebase-map'].every((t) => para.includes(t)) && lc.includes('every engine-agent report'));
+ok('the checker line carries fields and body', para.includes('{"action","verdict","problem","report","fields","body"}'));
+ok('it covers subagent, inline and the lean inline pass', lc.includes('subagent') && lc.includes('inline') && lc.includes('lean inline pass'));
+ok('the checker command with its technique flag and a report file',
+  para.includes('node <templates>/trailhead-report-status.js --technique <verify|code-review|plan|executor|fix|debug|research|codebase-map> --file <that dir>/report.md'));
+ok('the three templates dirs, in order',
+  (() => {
+    const a = para.indexOf('${CLAUDE_PLUGIN_ROOT}/templates/');
+    const b = para.indexOf('~/.claude/trailhead/templates/');
+    const c = para.indexOf('~/.codex/skills/trailhead/templates/');
+    return a !== -1 && b > a && c > b;
+  })());
+ok('the plugin root dir is skipped when unset', lc.includes('skipped when unset'));
+ok('a private temp dir from mktemp -d, once per report', para.includes('`mktemp -d`') && lc.includes('once') && lc.includes('0700'));
+ok('the raw report is written to report.md at the literal printed path with the Write tool',
+  para.includes('<that dir>/report.md') && para.includes('Write tool') && lc.includes('literal printed path'));
+ok('the dir is removed with rm -rf at the literal absolute path', para.includes('rm -rf <that dir>') && lc.includes('literal absolute path'));
+ok('cleanup runs after every path',
+  lc.includes('cleanup runs after every path') && ['accept', 'normalise', 're-ask check', 'second failure', 'checker failure'].every((w) => lc.includes(w)));
+ok('never a fixed or predictable path, never reused', lc.includes('never a fixed or predictable path') && lc.includes('never reused'));
+ok('stdin stays a CLI input but the protocol does not use it', lc.includes('stdin') && lc.includes('does not use'));
+ok('the checker-returned report replaces the raw report', lc.includes('checker-returned `report` replaces the raw report'));
+ok('the engine branches only on the returned verdict', para.includes('branches only on the returned `verdict`'));
+ok('the engine reads the returned fields and body, never re-derives them from prose',
+  para.includes('reads the returned `fields`') && para.includes('`body`') && lc.includes('instead of re-deriving them from the prose'));
+ok('reask: ask once, continue the same agent where the host allows, else re-dispatch',
+  lc.includes('ask once') && lc.includes('continue the same agent') && lc.includes('re-dispatch the same `trailhead-<technique>` agent')
+  && lc.includes('same model override') && lc.includes('malformed report quoted'));
+const prompt = 'Your report could not be accepted: `<problem>` (missing: no `status:` line; unknown-token: `<found>` is not an allowed token; '
+  + 'conflicting: more than one `status:` line, so quote or reword any status text in the body, which must not start a line with `status:` outside a code fence or blockquote; counts: the counts line is missing or repeated; fields: a required field is missing or an invariant is broken). '
+  + 'Return the complete report again with its first line exactly `status: <token>`, where `<token>` is one of `<allowed tokens>`, '
+  + 'and no other `status:` line<for code-review: , and its second line exactly `critical: <n> · warning: <n> · info: <n>`>'
+  + '<for fields: , with each of `<required fields>` as a top-level `<label>:` line and `<the broken invariant>` holding, with nothing after the last field>. '
+  + 'Do not post it anywhere.';
+ok('the corrective prompt, verbatim', para.includes(prompt));
+ok('for code-review the prompt always restates both required lines', lc.includes('always restates both required lines'));
+ok('for fields the prompt names the missing fields and the broken invariant', lc.includes('names the missing or empty fields and the invariant that broke'));
+ok('the reply is re-checked', lc.includes('re-check'));
+ok('a second failure: no verdict, nothing posted, no third ask, no inference from the body',
+  lc.includes('no verdict') && lc.includes('nothing posted') && lc.includes('no third ask') && lc.includes('no inference from the body'));
+ok('a second failure: HITL checkpoint naming the technique and the problem, Resolve stays blocked',
+  para.includes('HITL checkpoint') && lc.includes('naming the technique and the problem') && lc.includes('resolve stays blocked'));
+ok('the previous VERIFY comment stays latest', lc.includes('previous `verify` comment stays latest'));
+ok('a step that needed the report stays blocked too', lc.includes('so does any step that needed the report'));
+ok('the layout part is for the reviewing pair only', para.includes('**VERIFY comment layout (the reviewing pair only).**'));
+ok('checker missing, exit 2 or non-JSON: apply the same rules by hand, never guess',
+  lc.includes('checker is missing') && lc.includes('exit 2') && lc.includes('non-json') && lc.includes('by hand') && lc.includes('never guess a verdict'));
+
+// --- the VERIFY comment layout ------------------------------------------------------
+ok('layout: one VERIFY comment per Verify round', /one `VERIFY` comment per Verify round/.test(para));
+ok('layout part 1: the code-review report verbatim, status line 1, counts line 2, ledger, findings',
+  lc.includes('code-review report verbatim') && lc.includes('counts line 2') && lc.includes('ledger'));
+ok('layout part 2: a "## Goal-backward verification" heading and the verify report verbatim',
+  para.includes('`## Goal-backward verification` heading') && lc.includes('verify report verbatim'));
+ok('layout part 3: test or criterion outcome, then acceptance testing results',
+  lc.includes('test/criterion outcome') && lc.includes('acceptance-testing results'));
+ok('layout: an issues_found round posts parts 1 and 3 only', lc.includes('`issues_found` posts parts 1 and 3 only'));
+ok('layout: a verify-only round repeats the latest code-review report verbatim as part 1',
+  lc.includes('repeats the latest checker-returned code-review report verbatim as part 1'));
+ok('layout: the latest VERIFY comment holds the counts line and ledger', lc.includes('latest `verify` comment always holds the authoritative counts line and ledger'));
+ok('layout: the engine never reads the comment back to branch', lc.includes('never by reading the comment back'));
+
+// --- both Verify lines -----------------------------------------------------------------
+const verifyLines = engines.split('\n').filter((l) => l.trim().startsWith('4. **Verify**'));
+ok('ticket-engines.md has exactly two Verify (step 4) lines', verifyLines.length === 2);
+for (const [i, l] of verifyLines.entries()) {
+  ok(`Verify line ${i + 1}: run the report-status check before branching on status`, l.includes('run the report-status check before branching on status'));
+  ok(`Verify line ${i + 1}: points to the paragraph by name`, l.includes('*Malformed review report*') && l.includes('../../_shared/techniques.md'));
+  ok(`Verify line ${i + 1}: points to the VERIFY comment layout`, l.includes('layout'));
+  ok(`Verify line ${i + 1}: keeps the Ticket diff reference (#181)`, l.includes('**Ticket diff**'));
+}
+
+// --- the techniques return, the orchestrator posts --------------------------------------
+ok('verify.md: "Return the verdict" with a leading status', verify.includes('Return the verdict with a leading `status:`'));
+ok('verify.md: the orchestrator posts it under the Goal-backward verification heading of the round\'s VERIFY comment',
+  verify.includes('the orchestrator posts it') && verify.includes('`## Goal-backward verification` heading') && verify.includes("round's `VERIFY` comment"));
+ok('verify.md: no "Post the result"', !verify.includes('Post the result'));
+ok('verify.md keeps the three tokens', ['met', 'gaps_found', 'inconclusive'].every((t) => verify.includes(`\`status: ${t}\``)));
+ok('code-review.md: returns the report and the orchestrator posts it as the VERIFY comment',
+  /Return the report/.test(codeReview) && codeReview.includes('the orchestrator posts it as the `VERIFY` comment'));
+ok('code-review.md: no "Report in the ticket\'s VERIFY comment"', !codeReview.includes("Report in the ticket's `VERIFY` comment"));
+ok('code-review.md: status tag still on its own first line', codeReview.includes('machine-checkable status tag on its own first line'));
+ok('code-review.md: counts line phrasing kept', codeReview.includes('critical: <n> · warning: <n> · info: <n>')
+  && codeReview.includes('**Counts line, right under `status:`.**'));
+ok('code-review.md: dispositions and the latest VERIFY comment kept',
+  codeReview.includes('`fixed (<commit>)`') && codeReview.includes('latest `VERIFY` comment'));
+ok('code-review.md keeps the #181 Ticket diff rule', codeReview.includes("**Ticket diff: review the ticket's own commits, never a range.**"));
+
+// --- acceptance results are part 3 of the round's single VERIFY comment ---------------
+ok('acceptance-testing.md: results are gathered as it goes and land in part 3 of the round\'s VERIFY comment',
+  acceptance.includes('as it goes') && acceptance.includes("part 3 of the round's single `VERIFY` comment"));
+ok('acceptance-testing.md: the orchestrator posts once the round\'s checks, including acceptance, are done',
+  acceptance.includes('the orchestrator posts once the round\'s checks, including this one, are done'));
+ok('acceptance-testing.md: no longer records "in the VERIFY comment as it goes"', !acceptance.includes('in the `VERIFY` comment as it goes'));
+ok('acceptance-testing.md: the screenshot and the pending checklist go to part 3, not straight into a comment',
+  !acceptance.includes('screenshot into the `VERIFY` comment') && !acceptance.includes('checklist in the `VERIFY` comment'));
+ok('acceptance-testing.md: the two start paths outside a Verify round post their own VERIFY comment',
+  acceptance.includes("the Pending-UAT guard's option (a) and a UAT follow-up, there is no round: the orchestrator posts the results as a `VERIFY` comment of their own"));
+ok('acceptance-testing.md: no em-dash', !acceptance.includes('\u2014'));
+
+// --- every engine step reads the fields of its agent's report (#249) --------------------
+const stepOf = (src, startPrefix, endPrefix) => {
+  const ls = src.split('\n');
+  const a = ls.findIndex((l) => l.startsWith(startPrefix));
+  const b = ls.findIndex((l, i) => i > a && l.startsWith(endPrefix));
+  return a === -1 ? '' : ls.slice(a, b === -1 ? undefined : b).join('\n');
+};
+const has = (src, ...needles) => needles.every((n) => src.includes(n));
+const plan = stepOf(engines, '2. **Plan**', '3. **Execute**');
+const execute = stepOf(engines, '3. **Execute**', '4. **Verify**');
+const fixStep = stepOf(engines, '3. **Fix**', '4. **Verify**');
+const diagnose = stepOf(engines, '2. **Diagnose**', '3. **Fix**');
+ok('the steps were found', [plan, execute, fixStep, diagnose].every((x) => x.length > 300));
+ok('Plan: checks the planner report with --technique plan', has(plan, '--technique plan', '*Malformed review report*'));
+ok('Plan: ready posts the checker body verbatim as the PLAN comment', has(plan, '`status: ready`', "checker's `body` verbatim", '`PLAN` comment'));
+ok('Plan: needs_input asks the questions, re-spawns with the answers, never guesses',
+  has(plan, '`status: needs_input`', '`questions:`', 're-spawn the planner with the answers', 'never answer them yourself or guess'));
+for (const [label, step, tech] of [['Execute', execute, 'executor'], ['Fix', fixStep, 'fix']]) {
+  ok(`${label}: checks the report with --technique ${tech}`, has(step, `--technique ${tech}`, '*Malformed review report*'));
+  ok(`${label}: branches on the verdict and reads the fields, never reconstructs from prose`,
+    has(step, "checker's `verdict`", '`fields`', 'never reconstruct a result from the prose'));
+  ok(`${label}: done goes to Verify`, has(step, '`status: done` -> Verify'));
+  ok(`${label}: partial or blocked acts on each blockers entry, then re-spawns`,
+    has(step, '`status: partial` or `blocked`', 'each `blockers:` entry', 'foreign change', 're-spawn'));
+  ok(`${label}: posts fidelity as the fidelity comment and routes surfaced scope`, has(step, 'Post `fidelity:` as the fidelity comment', '`surfaced scope:`'));
+  ok(`${label}: commits must equal the Refs set since the base, both directions, every SHA resolves, a mismatch is surfaced`,
+    has(step, '`commits:`', 'must equal the `Refs: #<n>` commit set since the base SHA', 'both directions', 'every SHA must resolve', 'surfaced to the user, never patched over'));
+}
+ok('Diagnose: checks the debug report with --technique debug', has(diagnose, '--technique debug', '*Malformed review report*'));
+ok('Diagnose: found feeds the DIAGNOSIS from answer and evidence', has(diagnose, '`status: found`', '`answer:`', '`evidence:`', '`DIAGNOSIS`'));
+ok('Diagnose: inconclusive stays in diagnosis, needs_input asks the open questions',
+  has(diagnose, '`status: inconclusive`', 'stays in diagnosis', '`status: needs_input`', '`open questions:`'));
+ok('research: no research/<name> branch anywhere', ![research, charting, researchAgent].some((t) => /research\/(<name>|&lt;name)/.test(t)));
+ok('research: the report is the artifact, posted as a RESEARCH comment with every claim and its URL',
+  has(research, 'the report is the artifact', '`RESEARCH` comment', '`evidence:`', 'URL'));
+ok('research: branches on found, inconclusive and needs_input',
+  has(research, '`status: found`', 'resolve the ticket', '`status: inconclusive`', 'accept the answer at that confidence, narrow the question, or run another round',
+    '`status: needs_input`', '`open questions:`', 're-spawn'));
+ok('research: checked with --technique research', research.includes('--technique research'));
+ok('charting: the research fan-out posts the report, no branch', has(charting, '`RESEARCH` comment', 'no branch'));
+ok('research agent: identity returns findings in the report', researchAgent.includes('returning findings with their citations in your report') && researchAgent.includes('commit nothing'));
+ok('codebase-map: each reader returns an investigating report checked with --technique codebase-map',
+  has(codebaseMap, 'investigating report', '--technique codebase-map'));
+ok('codebase-map: distils the answer fields; inconclusive notes the gap; needs_input asked once then re-spawned or unmapped',
+  has(codebaseMap, 'distil** the `answer:` fields', '`status: inconclusive`', 'note the gap', '`status: needs_input`', 'once', 're-spawn that facet', 'unmapped'));
+ok('debug: a Report line points at the investigating contract', has(debug, '**Report.**', 'investigating report', 'never commits or creates a branch', '`DIAGNOSIS`'));
+ok('brief: the report names the implementing Return contract', has(brief, 'implementing `Return contract`', '`blockers:`'));
+
+for (const [label, src] of [['techniques.md', techniques], ['verify.md', verify], ['code-review.md', codeReview], ['ticket-engines.md', engines], ['executor-brief.md', brief], ['research.md', research], ['codebase-map.md', codebaseMap], ['debug.md', debug], ['charting.md', charting]]) {
+  ok(`${label}: no em-dash`, !src.includes('—'));
+}
+
+console.log(`report-status-docs.test.js: ${passed} checks passed`);

package/bin/resolve-helpers-docs.test.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// Docs test for #253: the skill prose names the Resolve bookkeeping helpers as the
+// default path (trailhead-issue-body.js, trailhead-dashboard.js, and the one `clear`
+// that also removes the session-ticket marker), while keeping the by-hand fallback.
+// Run: node resolve-helpers-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const skills = path.join(__dirname, '..', 'plugins', 'trailhead', 'skills');
+const read = (rel) => fs.readFileSync(path.join(skills, rel), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// file -> strings it must carry
+const EXPECT = {
+  '_shared/substrate.md': ['trailhead-issue-body.js', 'trailhead-dashboard.js', 'when a helper is missing'],
+  '_shared/substrate-commands.md': ['trailhead-issue-body.js append --issue <map> --section "Decisions so far"', 'trailhead-dashboard.js', '--set-last-audit', 'fully generated'],
+  'trailhead-work/references/ticket-engines.md': ['trailhead-issue-body.js append --issue <map> --section "Decisions so far"', 'trailhead-dashboard.js', 'trailhead-work-state.js clear --repo <working-root>'],
+  'trailhead-work/SKILL.md': ['trailhead-issue-body.js append --issue <map> --section "Decisions so far"', 'trailhead-dashboard.js', 'trailhead-work-state.js clear --repo <working-root>',
+    'trailhead-issue-body.js remove --issue <map> --section "Not yet specified" --match "<unique text of the entry>"'],
+  '_shared/session-handoff.md': ['trailhead-work-state.js clear --repo <working-root>', 'removes both'],
+  '_shared/teamwork.md': ['trailhead-issue-body.js append --issue <map> --section "Decisions so far"', 'sessionTicket', 'when the helper is missing'],
+  'trailhead-view/SKILL.md': ['trailhead-dashboard.js', '--dry-run'],
+  'trailhead-manage/references/auditing.md': ['trailhead-dashboard.js --set-last-audit'],
+  '_shared/configuration-reference.md': ['trailhead-issue-body.js replace --issue <conventions> --section :preamble'],
+};
+
+for (const [rel, needles] of Object.entries(EXPECT)) {
+  const text = read(rel);
+  for (const needle of needles) ok(`${rel} names: ${needle}`, text.includes(needle));
+  ok(`${rel} has no em-dash`, !text.includes('—'));
+}
+
+console.log(`resolve-helpers-docs.test.js: ${passed} checks passed`);

package/bin/scope-confirm-skip-docs.test.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// Docs test for #244: the ticket-start scope confirm is skipped on a ticket this session
+// already shaped. The rule is stated once (Work the map step 3); the quick bullet and the
+// choices table only point at it.
+// Run: node scope-confirm-skip-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const skills = path.join(__dirname, '..', 'plugins', 'trailhead', 'skills');
+const read = (rel) => fs.readFileSync(path.join(skills, rel), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const ANCHOR = 'Skip the confirm on a ticket this session already shaped';
+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. the bold definition exists exactly once, in trailhead-work/SKILL.md
+const defs = walk(skills).filter((f) => fs.readFileSync(f, 'utf8').includes(DEFINITION));
+ok('definition appears in exactly one file', defs.length === 1);
+ok('definition lives in trailhead-work/SKILL.md', defs[0] === path.join(skills, 'trailhead-work', 'SKILL.md'));
+const work = read('trailhead-work/SKILL.md');
+ok('definition appears once in SKILL.md', work.split(DEFINITION).length === 2);
+
+// 2. step 3 carries the normative fragments
+const lines = work.split('\n');
+const s = lines.findIndex((l) => l.startsWith('3. **Brief the ticket and confirm scope'));
+const e = lines.findIndex((l, i) => i > s && l.startsWith('4. '));
+ok('step 3 found', s >= 0 && e > s);
+const step3 = lines.slice(s, e).join('\n');
+ok('step 3 carries the definition', step3.includes(DEFINITION));
+// match the fragments in the rule sub-bullet only, not the whole of step 3
+const rule = lines.slice(s, e).find((l) => l.includes(DEFINITION));
+for (const frag of [
+  "from the user's own request for it",
+  'a Grilling round on this ticket concluded',
+  'created in bulk',
+  'earlier session',
+  '/clear',
+  'resume',
+  'one-line',
+  'never inferred from tracker metadata',
+  '`auto` is unchanged',
+]) ok(`rule carries: ${frag}`, rule.includes(frag));
+
+// 3. the quick bullet only points at the rule
+const quick = lines.find((l) => l.startsWith('- **Briefs and confirms scope first'));
+ok('quick bullet found', !!quick);
+ok('quick bullet references the anchor', quick.includes(ANCHOR));
+ok('quick bullet gates the menu on the rule', quick.includes('Whether the menu is posed at all follows'));
+ok('quick "<text>" gets the note, no menu', quick.includes('one-line note, no menu'));
+ok('quick bullet does not restate bulk exclusion', !quick.includes('created in bulk'));
+ok('quick bullet does not restate grill trigger', !quick.includes('a Grilling round on this ticket concluded'));
+
+// 4. the choices row only points at the rule
+const row = read('_shared/choices.md').split('\n').find((l) => l.startsWith('| Ticket-start scope confirm'));
+ok('choices row found', !!row);
+ok('choices row references the anchor', row.includes(ANCHOR));
+ok('choices row does not restate bulk exclusion', !row.includes('created in bulk'));
+
+// 5. no em-dash in the touched files
+for (const rel of ['trailhead-work/SKILL.md', '_shared/choices.md'])
+  ok(`${rel} has no em-dash`, !read(rel).includes('\u2014'));
+ok('this test has no em-dash', !fs.readFileSync(__filename, 'utf8').includes('\u2014'));
+
+console.log(`scope-confirm-skip-docs.test.js: ${passed} checks passed`);