@marcomigozzi/trailhead 0.13.0 → 0.15.0

package/bin/isolation-answer-docs.test.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Docs test for #245: the skill prose names the isolation-answer helper's check/record
+// reuse for the `auto` work-start ask, its fingerprint contract and the 8-hour session.
+// Run: node isolation-answer-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');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const teamwork = fs.readFileSync(path.join(skills, '_shared', 'teamwork.md'), 'utf8');
+const workSkill = fs.readFileSync(path.join(skills, 'trailhead-work', 'SKILL.md'), 'utf8');
+const choices = fs.readFileSync(path.join(skills, '_shared', 'choices.md'), 'utf8');
+const gitignore = fs.readFileSync(path.join(root, '.gitignore'), 'utf8');
+
+for (const [name, text] of [['teamwork.md', teamwork], ['trailhead-work/SKILL.md', workSkill]]) {
+  ok(`${name} names check`, text.includes('trailhead-isolation-answer.js check'));
+  ok(`${name} names record`, text.includes('trailhead-isolation-answer.js record'));
+  ok(`${name} has no em-dash`, !text.includes('—'));
+}
+ok('choices.md has no em-dash', !choices.includes('—'));
+
+for (const needle of [
+  '--others <csv|none|unavailable>',
+  'unavailable',
+  '8 hours',
+  '`/trailhead:auto` and an explicit `none`/`worktree`/`clone` never read or write the record',
+  "Isolation: reusing this session's answer",
+  "(one ticket at a time)",
+  "add it to that repo's `.gitignore` if absent",
+  '.trailhead/isolation-answer.json',
+  'three-dir lookup',
+]) ok(`teamwork.md carries: ${needle}`, teamwork.includes(needle));
+
+ok('.gitignore carries the record', gitignore.includes('.trailhead/isolation-answer.json'));
+
+console.log(`isolation-answer-docs.test.js: ${passed} checks passed`);

package/bin/isolation-copy-docs.test.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Docs test for #242: the skill prose names the gitignored-file copy helper for new
+// isolation workspaces and documents the isolation.copy config key.
+// Run: node isolation-copy-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 = {
+  'trailhead-work/SKILL.md': ['trailhead-isolation-copy.js --from <main-checkout> --to <working-root>', 'Gitignored files in a new workspace'],
+  '_shared/teamwork.md': ['trailhead-isolation-copy.js --from <main-checkout> --to <working-root>', 'Gitignored files in a new workspace', 'isolation.copy', 'before any install', '`rejected`', '`warnings`', '`status: skipped`'],
+  '_shared/configuration-reference.md': ['`isolation.copy`', 'Isolation copy', '.example', '.sample'],
+};
+
+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(`isolation-copy-docs.test.js: ${passed} checks passed`);

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, 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 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.
 
 ## 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.
@@ -323,6 +323,11 @@ policy:
 `;
 }
 
+// --- CODEX_MOD_ONLY_VERBS --------------------------------------------------
+// Verbs only the Claude Code mod answers (commands/<verb>.md exists for the
+// namespaced command, but nothing on Codex can draw it): never projected.
+const CODEX_MOD_ONLY_VERBS = ['panel'];
+
 // --- codexVerbSkillPlan ----------------------------------------------------
 // Given the resolved verb list (each { verb, description? }, or a bare string
 // verb; normally read from plugins/trailhead/commands/*.md by the installer),
@@ -340,6 +345,7 @@ function codexVerbSkillPlan(codexHome, verbs) {
     const v = entry && typeof entry === 'object' ? entry.verb : entry;
     if (v == null || String(v).trim() === '') continue;
     const verb = String(v).trim();
+    if (CODEX_MOD_ONLY_VERBS.includes(verb)) continue;
     const description = entry && typeof entry === 'object' ? entry.description : undefined;
     const skillDir = path.join(skillsRoot, `trailhead-${verb}`);
     dirs.push(skillDir);
@@ -358,10 +364,13 @@ function codexVerbSkillPlan(codexHome, verbs) {
 }
 
 // --- codexHookEntries -----------------------------------------------------
-// The six guardrail hooks trailhead registers on Codex, as {event, matcher,
-// command} records. Commands run the copied guard scripts under hooksScriptsDir
-// via node, matching Claude's `node "<path>"` form. PreToolUse guards (commit,
-// secret, install, body, secret-read) can veto; the injection-scanner
+// 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
+// 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
 // installer, which merges them into ~/.codex/hooks.json (same shape as
 // Claude's settings.json hooks block).
@@ -372,10 +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-commit-guard.js') },
-    { event: 'PreToolUse', matcher: 'Bash', command: cmd('trailhead-secret-guard.js') },
-    { event: 'PreToolUse', matcher: 'Bash', command: cmd('trailhead-install-guard.js') },
-    { event: 'PreToolUse', matcher: 'Bash', command: cmd('trailhead-body-guard.js') },
+    { event: 'PreToolUse', matcher: 'Bash', command: `${cmd('trailhead-bash-guards.js')} --guards=commit,secret,install,body` },
     { 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') },
@@ -447,6 +453,7 @@ module.exports = {
   codexVerbSkillContent,
   codexVerbSkillAgentsYaml,
   codexVerbSkillPlan,
+  CODEX_MOD_ONLY_VERBS,
   codexHookEntries,
   enableCodexFeatureFlag,
   enableCodexHooksFeature,

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

@@ -15,6 +15,7 @@ const {
   codexVerbSkillContent,
   codexVerbSkillAgentsYaml,
   codexVerbSkillPlan,
+  CODEX_MOD_ONLY_VERBS,
   codexHookEntries,
   enableCodexHooksFeature,
   enableCodexMultiAgentV2Feature,
@@ -160,19 +161,22 @@ ok('codexVerbSkillPlan: accepts a bare-string verb and skips empty/invalid', (()
 })());
 ok('codexVerbSkillPlan: null verbs yields nothing', codexVerbSkillPlan('/c', null).dirs.length === 0 && codexVerbSkillPlan('/c').dirs.length === 0);
 
+// #208: a verb only the Claude Code mod answers (the map panel) has no Codex projection.
+ok('CODEX_MOD_ONLY_VERBS names exactly the panel verb', Array.isArray(CODEX_MOD_ONLY_VERBS) && CODEX_MOD_ONLY_VERBS.length === 1 && CODEX_MOD_ONLY_VERBS[0] === 'panel');
+ok('codexVerbSkillPlan: never projects a mod-only verb, object or bare string', (() => {
+  const plan = codexVerbSkillPlan('/c', [{ verb: 'panel', description: 'x' }, 'panel', { verb: 'map' }]);
+  return plan.dirs.length === 1 && plan.dirs[0] === '/c/skills/trailhead-map' && !plan.writes.some((w) => /panel/.test(w.path));
+})());
+
 // --- codexHookEntries ---
 const entries = codexHookEntries('/h');
-ok('codexHookEntries returns 8 entries', Array.isArray(entries) && entries.length === 8);
-ok('codexHookEntries: commit-guard is PreToolUse/Bash', entries.some((e) =>
-  e.event === 'PreToolUse' && e.matcher === 'Bash' && e.command.includes('trailhead-commit-guard.js') && e.command.includes('/h')));
-ok('codexHookEntries: secret-guard is PreToolUse/Bash', entries.some((e) =>
-  e.event === 'PreToolUse' && e.matcher === 'Bash' && e.command.includes('trailhead-secret-guard.js')));
-ok('codexHookEntries: install-guard is PreToolUse/Bash', entries.some((e) =>
-  e.event === 'PreToolUse' && e.matcher === 'Bash' && e.command.includes('trailhead-install-guard.js')));
-ok('codexHookEntries: search-guard is absent (Claude-Code-only, not projected to Codex)',
-  entries.every((e) => !e.command.includes('trailhead-search-guard.js')));
-ok('codexHookEntries: body-guard is PreToolUse/Bash', entries.some((e) =>
-  e.event === 'PreToolUse' && e.matcher === 'Bash' && e.command.includes('trailhead-body-guard.js')));
+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: 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) =>
   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) =>
@@ -402,4 +406,69 @@ ok('convertToCodex projects the anchor positives to Codex forms', (() => {
     !out.includes('/trailhead:work') && !out.includes('/clear');
 })());
 
+// #205: the work state helper and its session env var survive the projection;
+// 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'));
+{
+  const skillsDir = path.join(__dirname, '../../plugins/trailhead/skills');
+  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>'));
+  const teamwork = convertToCodex(fs.readFileSync(path.join(skillsDir, '_shared', 'teamwork.md'), 'utf8'));
+  ok('projected teamwork carries the step change call',
+    teamwork.includes('trailhead-work-state.js set --repo <working-root> --step <step>'));
+  ok('projected teamwork carries the autoDone counter flag',
+    teamwork.includes('--auto true --auto-done <n>'));
+  const autoRef = convertToCodex(fs.readFileSync(path.join(skillsDir, 'trailhead-work', 'references', 'auto.md'), 'utf8'));
+  ok('projected auto reference carries the autoDone counter flag',
+    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/lib/install-verify.js

@@ -135,6 +135,9 @@ function readRegistry(registryFile) {
 // token expands to exactly hooksDir/<f>, OR an unresolved token's basename is
 // <f> (stays warning-only, never also missing).
 function checkRegisteredTargets(spec, missing, unverified) {
+  // Shipped files (hookFiles) may include modules that are only require()d;
+  // the files that must be registered are the entrypoints (default: all shipped).
+  const entrypoints = spec.entrypointFiles || spec.hookFiles;
   const registry = readRegistry(spec.registryFile);
   const registryName = path.basename(spec.registryFile);
   const events = (registry && typeof registry.hooks === 'object' && registry.hooks) ? registry.hooks : {};
@@ -168,7 +171,7 @@ function checkRegisteredTargets(spec, missing, unverified) {
     }
   }
 
-  for (const f of spec.hookFiles) {
+  for (const f of entrypoints) {
     if (!registeredExact.has(f) && !registeredViaUnresolved.has(f)) {
       missing.push(`hook registration ${f} (${registryName})`);
     }
@@ -185,8 +188,8 @@ function checkAgents(spec, missing) {
 }
 
 // --- verifyInstall --------------------------------------------------------------
-// spec = { skillsRoot, skillDirs, sharedFiles, hooksDir, hookFiles,
-//          hookLibFiles, registryFile, agentsDir, agentPattern, env, home }
+// spec = { skillsRoot, skillDirs, sharedFiles, hooksDir, hookFiles (shipped),
+//          entrypointFiles (registered; defaults to hookFiles), hookLibFiles, registryFile, agentsDir, agentPattern, env, home }
 function verifyInstall(spec) {
   const missing = [];
   const unverified = [];
@@ -199,13 +202,14 @@ function verifyInstall(spec) {
 }
 
 // --- spec builders ---------------------------------------------------------
-function claudeVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, hookLibFiles, env, home }) {
+function claudeVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, entrypointFiles, hookLibFiles, env, home }) {
   return {
     skillsRoot: path.join(configDir, 'skills'),
     skillDirs,
     sharedFiles,
     hooksDir: path.join(configDir, 'hooks'),
     hookFiles,
+    entrypointFiles,
     hookLibFiles,
     registryFile: path.join(configDir, 'settings.json'),
     agentsDir: path.join(configDir, 'agents'),
@@ -215,7 +219,7 @@ function claudeVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, hookLi
   };
 }
 
-function codexVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, hookLibFiles, env, home }) {
+function codexVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, entrypointFiles, hookLibFiles, env, home }) {
   const L = codexLayout(configDir);
   return {
     skillsRoot: L.skillsRoot,
@@ -223,6 +227,7 @@ function codexVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, hookLib
     sharedFiles,
     hooksDir: L.hooksScriptsDir,
     hookFiles,
+    entrypointFiles,
     hookLibFiles,
     registryFile: L.hooksJson,
     agentsDir: L.codexAgentsDir,

package/bin/lib/install-verify.test.js

@@ -359,6 +359,57 @@ function buildCodexFixture() {
     r.unverified.some((u) => u.includes('CLAUDE_PLUGIN_ROOT undefined')));
 }
 
+// --- shipped files vs registered entrypoints (#207) ---------------------------
+// The guard modules are shipped (they must exist) but only require()d by the
+// merged hook, so they are never required to be registered.
+function buildMergedFixture(host) {
+  const configDir = mktmp();
+  const skillDirs = ['trailhead', '_shared'];
+  const sharedFiles = ['load-first.md'];
+  const modules = ['trailhead-commit-guard.js', 'trailhead-body-guard.js'];
+  const entrypointFiles = ['trailhead-bash-guards.js'];
+  const hookFiles = [...modules, ...entrypointFiles];
+  const hooksDir = host === 'codex' ? path.join(configDir, 'skills', 'trailhead', 'hooks') : path.join(configDir, 'hooks');
+  write(path.join(configDir, 'skills', 'trailhead', 'SKILL.md'), 'x');
+  write(path.join(configDir, 'skills', '_shared', 'load-first.md'), 'x');
+  for (const f of hookFiles) write(path.join(hooksDir, f), 'x');
+  write(path.join(configDir, 'agents', host === 'codex' ? 'trailhead-execute.toml' : 'trailhead-execute.md'), 'x');
+  const registry = { hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [
+    { type: 'command', command: `node "${path.join(hooksDir, 'trailhead-bash-guards.js')}"${host === 'codex' ? ' --guards=commit,body' : ''}` },
+  ] }] } };
+  write(path.join(configDir, host === 'codex' ? 'hooks.json' : 'settings.json'), JSON.stringify(registry, null, 2));
+  const build = host === 'codex' ? codexVerifySpec : claudeVerifySpec;
+  const spec = build(configDir, { skillDirs, sharedFiles, hookFiles, entrypointFiles, hookLibFiles: [], env: {}, home: H });
+  return { configDir, spec, hooksDir };
+}
+for (const host of ['claude', 'codex']) {
+  {
+    const { spec } = buildMergedFixture(host);
+    const r = verifyInstall(spec);
+    ok(`${host}: passes with the guard modules shipped but unregistered`, r.missing.length === 0 && r.unverified.length === 0);
+  }
+  {
+    const { spec, hooksDir } = buildMergedFixture(host);
+    fs.rmSync(path.join(hooksDir, 'trailhead-commit-guard.js'));
+    const r = verifyInstall(spec);
+    ok(`${host}: a shipped guard module that is missing is still reported`, r.missing.includes('hook script trailhead-commit-guard.js'));
+  }
+  {
+    const { configDir, spec } = buildMergedFixture(host);
+    write(path.join(configDir, host === 'codex' ? 'hooks.json' : 'settings.json'), JSON.stringify({ hooks: {} }));
+    const r = verifyInstall(spec);
+    ok(`${host}: fails when the registered entrypoint is not registered`,
+      r.missing.some((m) => m.startsWith('hook registration trailhead-bash-guards.js')));
+  }
+  {
+    const { spec, hooksDir } = buildMergedFixture(host);
+    fs.rmSync(path.join(hooksDir, 'trailhead-bash-guards.js'));
+    const r = verifyInstall(spec);
+    ok(`${host}: fails when the registered entrypoint file is missing`,
+      r.missing.includes('hook script trailhead-bash-guards.js') && r.missing.some((m) => m.startsWith('registered hook target')));
+  }
+}
+
 // --- formatters --------------------------------------------------------------
 {
   const out = formatVerifyFailure('Claude Code', '/c/dir', { missing: ['skill trailhead-work/SKILL.md'], unverified: ['/x/trailhead-y.js (PreToolUse, settings.json: $Y undefined)'] });

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