@marcomigozzi/trailhead 0.13.0 → 0.15.0

package/bin/trailhead.test.js

@@ -118,11 +118,41 @@ ok('codex: commit-msg template projected', fs.existsSync(codexTemplate));
 ok('codex: commit-msg template is verbatim (not converted)',
   fs.readFileSync(codexTemplate, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-commit-msg'), 'utf8'));
 
+// #257: the hook logic ships as a .cjs beside the sh wrapper.
+const codexCommitMsgCjs = path.join(codexDir, 'skills', 'trailhead', 'templates', 'trailhead-commit-msg.cjs');
+ok('codex: commit-msg .cjs logic projected', fs.existsSync(codexCommitMsgCjs));
+ok('codex: commit-msg .cjs logic is verbatim (not converted)',
+  fs.readFileSync(codexCommitMsgCjs, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-commit-msg.cjs'), 'utf8'));
+
 // #185: the commit-msg hook sync script ships wholesale with templates/ too.
 const codexCommitMsgSync = path.join(codexDir, 'skills', 'trailhead', 'templates', 'trailhead-commit-msg-sync.js');
 ok('codex: commit-msg-sync script projected', fs.existsSync(codexCommitMsgSync));
 ok('codex: commit-msg-sync script is byte-identical to source',
   fs.readFileSync(codexCommitMsgSync, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-commit-msg-sync.js'), 'utf8'));
+// #205: the work state helper rides in templates/ on Codex too, executable.
+const codexWorkState = path.join(codexDir, 'skills', 'trailhead', 'templates', 'trailhead-work-state.js');
+ok('codex: work-state helper projected', fs.existsSync(codexWorkState));
+ok('codex: work-state helper is byte-identical to source',
+  fs.readFileSync(codexWorkState, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-work-state.js'), 'utf8'));
+ok('codex: work-state helper keeps its executable bit', (fs.statSync(codexWorkState).mode & 0o111) !== 0);
+// #242: the isolation copy helper rides in templates/ on Codex too, executable.
+const codexIsolationCopy = path.join(codexDir, 'skills', 'trailhead', 'templates', 'trailhead-isolation-copy.js');
+ok('codex: isolation-copy helper projected', fs.existsSync(codexIsolationCopy));
+ok('codex: isolation-copy helper is byte-identical to source',
+  fs.readFileSync(codexIsolationCopy, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-isolation-copy.js'), 'utf8'));
+ok('codex: isolation-copy helper keeps its executable bit', (fs.statSync(codexIsolationCopy).mode & 0o111) !== 0);
+// #243: the stale-base preflight helper rides in templates/ on Codex too, executable.
+const codexBasePreflight = path.join(codexDir, 'skills', 'trailhead', 'templates', 'trailhead-base-preflight.js');
+ok('codex: base-preflight helper projected', fs.existsSync(codexBasePreflight));
+ok('codex: base-preflight helper is byte-identical to source',
+  fs.readFileSync(codexBasePreflight, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-base-preflight.js'), 'utf8'));
+ok('codex: base-preflight helper keeps its executable bit', (fs.statSync(codexBasePreflight).mode & 0o111) !== 0);
+// #252: the UAT setup helper rides in templates/ on Codex too, executable.
+const codexUatSetup = path.join(codexDir, 'skills', 'trailhead', 'templates', 'trailhead-uat-setup.js');
+ok('codex: uat-setup helper projected', fs.existsSync(codexUatSetup));
+ok('codex: uat-setup helper is byte-identical to source',
+  fs.readFileSync(codexUatSetup, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-uat-setup.js'), 'utf8'));
+ok('codex: uat-setup helper keeps its executable bit', (fs.statSync(codexUatSetup).mode & 0o111) !== 0);
 // Il sync del label guard (migrazione all'if a livello di job) viaggia con templates/.
 const codexLabelGuardSync = path.join(codexDir, 'skills', 'trailhead', 'templates', 'trailhead-label-guard-sync.js');
 ok('codex: label-guard-sync script is byte-identical to source', fs.existsSync(codexLabelGuardSync) &&
@@ -134,6 +164,18 @@ ok('codex: audit-walk script is byte-identical to source',
   fs.readFileSync(codexAuditWalk, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-audit-walk.js'), 'utf8'));
 ok('codex: audit-walk script keeps its executable bit', (fs.statSync(codexAuditWalk).mode & 0o111) !== 0);
 
+// #253: the Resolve bookkeeping helpers ride in templates/ on Codex too, executable,
+// and find the secret-guard module from their installed location.
+for (const helper of ['trailhead-issue-body.js', 'trailhead-dashboard.js']) {
+  const projected = path.join(codexDir, 'skills', 'trailhead', 'templates', helper);
+  ok(`codex: ${helper} projected`, fs.existsSync(projected));
+  ok(`codex: ${helper} is byte-identical to source`,
+    fs.readFileSync(projected, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', helper), 'utf8'));
+  ok(`codex: ${helper} keeps its executable bit`, (fs.statSync(projected).mode & 0o111) !== 0);
+}
+ok('codex: the installed issue-body helper finds the secret guard',
+  require(path.join(codexDir, 'skills', 'trailhead', 'templates', 'trailhead-issue-body.js')).loadGuard() !== null);
+
 ok('codex: no commands dir', !fs.existsSync(path.join(codexDir, 'commands')));
 ok('codex: no settings.json file', !fs.existsSync(path.join(codexDir, 'settings.json')));
 // #46: per-verb discoverability now projects one Codex SKILL per verb
@@ -143,6 +185,8 @@ ok('codex: no settings.json file', !fs.existsSync(path.join(codexDir, 'settings.
 // dir, so its discoverability is the cluster itself; use a non-colliding verb.
 ok('codex: per-verb skills/trailhead-bug/SKILL.md exists', fs.existsSync(path.join(codexDir, 'skills', 'trailhead-bug', 'SKILL.md')));
 ok('codex: trailhead-bug SKILL.md frontmatter is at byte 0', fs.readFileSync(path.join(codexDir, 'skills', 'trailhead-bug', 'SKILL.md'), 'utf8').startsWith('---\nname: trailhead-bug\n'));
+// #208: /trailhead:panel is answered by the Claude Code mod only: no Codex skill for it.
+ok('codex: no per-verb skill for the mod-only panel verb', !fs.existsSync(path.join(codexDir, 'skills', 'trailhead-panel')));
 ok('codex: trailhead-bug skill delegates to $trailhead bug', fs.readFileSync(path.join(codexDir, 'skills', 'trailhead-bug', 'SKILL.md'), 'utf8').includes('$trailhead bug'));
 // #190: audit verb projected per-verb on Codex, description from commands/audit.md.
 const auditCmdSrc190 = fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'commands', 'audit.md'), 'utf8');
@@ -202,6 +246,28 @@ for (const cl of ['trailhead', 'trailhead-chart', 'trailhead-work', 'trailhead-v
   ok(`source: ${cl}/SKILL.md does NOT duplicate the core-list signature line`, !fs.readFileSync(path.join(sourceSkillsDir, cl, 'SKILL.md'), 'utf8').includes(loadFirstSignature));
 }
 
+// --- #237: the shared core is loaded by ABSOLUTE path with the Read tool -----
+const clusters237 = ['trailhead', 'trailhead-chart', 'trailhead-work', 'trailhead-view', 'trailhead-capture', 'trailhead-manage'];
+const loadFirst237 = fs.readFileSync(loadFirstSourcePath, 'utf8');
+for (const cl of clusters237) {
+  const src = fs.readFileSync(path.join(sourceSkillsDir, cl, 'SKILL.md'), 'utf8');
+  const start = src.indexOf('## Load first');
+  const rest = src.slice(start + 3);
+  const nextH = rest.search(/\n## /);
+  const para = start < 0 ? '' : (nextH < 0 ? rest : rest.slice(0, nextH));
+  ok(`#237: ${cl} Load first names the base directory`, /base directory/i.test(para));
+  ok(`#237: ${cl} Load first requires an absolute path`, /absolute path/i.test(para));
+  ok(`#237: ${cl} Load first requires the Read tool`, /Read tool/.test(para));
+  ok(`#237: ${cl} Load first has no bare relative "read ../_shared/load-first.md"`, !/read `\.\.\/_shared\/load-first\.md`/i.test(para));
+  ok(`#237: ${cl} SKILL.md has no shell read of a relative _shared/ path`, !/\b(cat|head|tail|sed\s+-n\s+\S+)\s+(\.\.\/)*_shared\//.test(src));
+  ok(`#237: ${cl} SKILL.md has no cd-and-read compound`, !/\bcd\s+\S+\s*&&\s*(cat|head|tail|sed|grep)\b/.test(src));
+}
+ok('#237: load-first.md states the absolute-path rule with the Read tool', /absolute path/i.test(loadFirst237) && /Read tool/.test(loadFirst237));
+ok('#237: load-first.md resolves <lib> and <templates> to absolute paths', loadFirst237.includes('`<lib>` (an absolute path') && loadFirst237.includes('`<templates>` (an absolute path)'));
+ok('#237: load-first.md covers every other ../_shared/ or references/ path', loadFirst237.includes('references/') && /every other/i.test(loadFirst237));
+ok('#237: load-first.md no longer says paths are relative to the cluster SKILL.md', !loadFirst237.includes('relative to the cluster `SKILL.md`') && !loadFirst237.includes('relative to the cluster SKILL.md that'));
+ok('#237: load-first.md has no shell read of a relative _shared/ path', !/\b(cat|head|tail|sed\s+-n\s+\S+)\s+(\.\.\/)*_shared\//.test(loadFirst237) && !/\bcd\s+\S+\s*&&\s*(cat|head|tail|sed|grep)\b/.test(loadFirst237));
+
 // --- #146: single-sourced ticket-language directive (anti-drift) -------------
 // The standing ticket-language rule (write Issue prose + commit bodies in
 // config.ticket.language, decoupled from the chat language) lives in ONE place,
@@ -279,6 +345,27 @@ ok('source: capture.md offers /trailhead:quick as the lighter alternative, after
 ok('source: capture.md says quick is offered alongside work, never in its place', captureSource.includes('never in its place'));
 ok('source: capture.md keeps /trailhead:work the anchor even for a whiteboard capture', /whiteboard[\s\S]{0,200}the anchor stays `\/trailhead:work <n>`/.test(captureSource));
 
+// --- #246: `bug --of <ticket>` inherits the origin's destination ------------
+// Source-level invariant: capture.md's `bug` bullet makes `--of` inherit the origin
+// ticket's map (open) or the whiteboard without the which-map ask, checks the origin
+// map's state before inheriting, falls back to the Map or whiteboard rule on a closed
+// map / absent or contradictory labels, and names the inherited destination and the
+// origin (each by name and number) in the confirmation line. The Map or whiteboard
+// paragraph cross-references the exception (single source stays in the `bug` bullet).
+const captureBugBullet = (captureSource.match(/^- \*\*`bug`\*\*.*$/m) || [''])[0];
+const captureMapParagraph = (captureSource.match(/^\*\*Map or whiteboard:\*\*.*$/m) || [''])[0];
+ok('source: capture.md `bug --of` inherits the origin destination instead of asking', /\*\*`--of` also inherits the origin's destination instead of asking/.test(captureBugBullet));
+ok('source: capture.md `bug --of` lands on an OPEN origin map with no ask, and a closed one falls back',
+  /\*\*open\*\* -> land on map `<n>`[\s\S]{0,120}no ask; \*\*closed\*\* -> fall back/.test(captureBugBullet));
+ok('source: capture.md `bug --of` lands on the whiteboard for a whiteboard origin, no ask, with the dashboard refresh',
+  /carries `trailhead:whiteboard`[\s\S]{0,80}land on the whiteboard, no ask \(dashboard refresh/.test(captureBugBullet));
+ok('source: capture.md `bug --of` checks the origin map state (--json state) before inheriting', /gh issue view <n> --json state/.test(captureBugBullet));
+ok('source: capture.md `bug --of` falls back to the Map or whiteboard rule on closed map, absent or contradictory labels',
+  /[Ff]all back to the existing Map or whiteboard rule[\s\S]{0,600}closed[\s\S]{0,300}neither label[\s\S]{0,300}contradictory/.test(captureBugBullet));
+ok('source: capture.md `bug --of` confirmation names the inherited destination and the origin, each by name and number',
+  /[Cc]onfirmation line[\s\S]{0,300}inherited[\s\S]{0,200}by name and number[\s\S]{0,200}origin[\s\S]{0,100}by name and number/.test(captureBugBullet));
+ok('source: capture.md Map or whiteboard paragraph cross-references the `bug --of` ask exception', /`bug --of`[\s\S]{0,200}skip/.test(captureMapParagraph));
+
 // --- #179: `quick <n>` on a map ticket is never "off the map" ----------------
 // Source-level invariant: `quick <n>` on an EXISTING ticket does not leave the
 // map (it keeps its trailhead:map-<n> label and sub-issue edge, and dependent-
@@ -512,6 +599,53 @@ const workSkillSource = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-wo
 ok('source: trailhead-work SKILL.md out-of-scope close drops the native sub-issue edge',
   /out of scope\*\* \(label, then \*\*drop its native sub-issue edge\*\*/.test(workSkillSource));
 
+// The text of a structural unit of a source, from its anchor: a missing anchor fails loudly.
+const unitFrom = (source, anchor, endPattern) => {
+  const start = source.indexOf(anchor);
+  if (start === -1) throw new Error(`anchor not found in source: ${anchor}`);
+  const rest = source.slice(start);
+  const end = rest.slice(anchor.length).search(endPattern);
+  return end === -1 ? rest : rest.slice(0, anchor.length + end);
+};
+// work step 1: its paragraph, up to the next numbered step or blank line.
+const workStep1 = unitFrom(workSkillSource, '1. Load the **map**', /\n(?:\d+\. |\s*\n)/);
+// quick's isolation bullet: up to the end of its line.
+const quickIsolationBullet = unitFrom(workSkillSource, '- **Same isolation setup as `work`.**', /\n/);
+// The rule is stated once, in multi-map.md; the work places point to it.
+const multiMapSource = fs.readFileSync(path.join(sourceSkillsDir, '_shared', 'multi-map.md'), 'utf8');
+const namedTicketMapSentence = /a named ticket that carries a `trailhead:map-<n>` label makes that map the active map \(write `\.trailhead\/active-map`\); a whiteboard ticket leaves the active map alone/i;
+const namedTicketMapPointer = /named ticket's map becomes the active map[\s\S]*whiteboard ticket leaves it alone[\s\S]*multi-map\.md/i;
+ok('source: multi-map.md Active map paragraph states the named-ticket rule',
+  namedTicketMapSentence.test(unitFrom(multiMapSource, '**Active map.**', /\n/)));
+ok('source: trailhead-work SKILL.md work step 1 points to the named-ticket active-map rule',
+  /its map becomes the active map, a whiteboard ticket leaves it alone[\s\S]*multi-map\.md/i.test(workStep1));
+ok('source: trailhead-work SKILL.md quick isolation bullet points to the named-ticket active-map rule',
+  namedTicketMapPointer.test(quickIsolationBullet));
+
+// --- #234: the ticket-start scope confirm is a host menu, not free text ------
+const workStep3 = unitFrom(workSkillSource, '3. **Brief the ticket and confirm scope', /\n(?:\d+\. |\s*\n)/);
+const quickBriefBullet = unitFrom(workSkillSource, '- **Briefs and confirms scope first', /\n/);
+const choicesScopeSource = fs.readFileSync(path.join(sourceSkillsDir, "_shared", "choices.md"), "utf8");
+ok('source: work step 3 poses the scope confirm as an AskUserQuestion menu, Proceed (Recommended) first, Change something second',
+  /`AskUserQuestion`[\s\S]{0,300}\*\*Proceed\*\* \(Recommended\)[\s\S]{0,200}\*\*Change something\*\*/.test(workStep3));
+ok('source: work step 3 offers the delegate option on the scope confirm',
+  /\*\*delegate\*\*[\s\S]{0,200}choices\.md/i.test(workStep3));
+ok('source: work step 3 divergent change is a menu (as-is vs separate ticket) without delegate',
+  /diverges[\s\S]{0,500}`AskUserQuestion`[\s\S]{0,300}without the delegate option/.test(workStep3));
+ok('source: work step 3 has a plain-text numbered list fallback for hosts without a question tool (Codex)',
+  /no structured question tool[\s\S]{0,120}plain-text numbered list/.test(workStep3));
+ok('source: work step 3 keeps the auto sentence (proceeds without stopping to brief)',
+  /`auto` proceeds \(takes the delegate option\) without stopping to brief/.test(workStep3));
+ok('source: work step 3 no longer asks the change question as free text',
+  !/ask whether they want to change anything/.test(workStep3));
+ok('source: quick brief bullet poses the same menu and keeps a one-line note for quick "<text>"',
+  /`AskUserQuestion`/.test(quickBriefBullet) && /\*\*Proceed\*\* \(Recommended\)/.test(quickBriefBullet) &&
+  /one-line note/.test(quickBriefBullet) && !/one-line confirmation/.test(quickBriefBullet));
+ok('source: choices.md call-site table has the ticket-start scope confirm row (delegate yes, defer no)',
+  /\| Ticket-start scope confirm \(`work`\/`quick` brief\) \| Yes[^|]*\| No[^|]*\|/.test(choicesScopeSource));
+ok('source: choices.md call-site table has the divergent-change row (delegate no, defer no)',
+  /\| Divergent change at the brief \(as-is vs separate ticket\) \| No[^|]*\| No[^|]*\|/.test(choicesScopeSource));
+
 const inboxSource = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-chart', 'references', 'inbox.md'), 'utf8');
 ok('source: inbox.md out-of-scope close drops the native sub-issue edge',
   /`trailhead:out-of-scope`, \*\*drop its native sub-issue edge\*\*/.test(inboxSource));
@@ -549,7 +683,7 @@ for (const phrase of [
   '**wait for an explicit answer**',
   '**silence or an ambiguous reply re-asks**',
   '**One-path skip**',
-  '**state the reason in one line**',
+  '**states the reason in one line**',
   'VERIFY',
   'only for the steps it cannot perform',
   'runs unchanged',
@@ -634,6 +768,11 @@ ok('source: auto.md states the drive-mode-ask outcomes together (grouped, not sc
 const choicesSourcePath = path.join(sourceSkillsDir, '_shared', 'choices.md');
 const choicesSource = fs.readFileSync(choicesSourcePath, 'utf8');
 ok('source: choices.md call-site table carries the drive-mode ask row', /\|[^\n]*[Dd]rive-mode ask[^\n]*\|/.test(choicesSource));
+// Formato della scelta: fino a 4 opzioni reali -> menu; oltre -> lista a lettere in prosa.
+ok('source: choices.md routes a choice of up to 4 real options to the AskUserQuestion menu',
+  /\*\*Which format\.\*\*[\s\S]{0,400}up to 4 real options[\s\S]{0,200}`AskUserQuestion` menu/.test(choicesSource));
+ok('source: choices.md routes a choice of more than 4 real options to a lettered prose list',
+  /\*\*Which format\.\*\*[\s\S]{0,800}more than 4 real options[\s\S]{0,200}lettered list/.test(choicesSource));
 
 // --- #178 (3/4): acceptance.browser off keeps AI-driven UAT via commands ----
 const configReferencePath = path.join(sourceSkillsDir, '_shared', 'configuration-reference.md');
@@ -685,22 +824,124 @@ ok('source: auto.md Run-end summary section exists', runEndSummarySection.length
 ok('source: auto.md Run-end summary "what remains" list includes human-only UAT steps',
   /what remains[\s\S]{0,400}human-only UAT steps/.test(runEndSummarySection));
 
+// --- #254: skip option at the drive-mode ask (a waiver, not a deferral) -----
+// The waiver's operational contract is single-sourced in the Drive-mode bullet
+// (acceptance-testing.md); the other call-sites carry only the routing /
+// closure consequence and name the bullet.
+const driveModeMarkerLine = driveModeSpan.split('\n')[0] || '';
+ok('source: Drive-mode marker line names the skip option alongside AI-driven / human-driven',
+  driveModeMarkerLine.includes('AI-driven') && driveModeMarkerLine.includes('human-driven') && driveModeMarkerLine.includes('skip (waive acceptance)'));
+const skipSubBullet = driveModeSpan.split('\n').find((l) => l.startsWith('  - **Skip (waive acceptance).**')) || '';
+ok('source: Drive-mode span carries the "Skip (waive acceptance)" sub-bullet', skipSubBullet.length > 0);
+for (const phrase of [
+  'waived by the user (unconfirmed)',
+  'never a pass',
+  'the Pending-UAT guard does not fire',
+  'no follow-up',
+  'The delegate option never picks skip',
+  '`auto` never picks skip',
+  'UAT of:',
+  'closes as waived',
+  'resolution comment',
+  'all three start paths',
+]) {
+  ok(`source: Skip sub-bullet pins "${phrase}"`, skipSubBullet.includes(phrase));
+}
+const oneAskLine = driveModeSpan.split('\n').find((l) => l.startsWith('  - **One-path skip**')) || '';
+ok('source: one-path skip no longer suppresses the ask outright (drops only the AI-driven option)',
+  oneAskLine.includes('drops only the AI-driven option') && oneAskLine.includes('human-driven or skip') && !oneAskLine.includes('skip the ask'));
+ok('source: one-path skip still states the reason in one line, naming the blocking class',
+  oneAskLine.includes('**states the reason in one line**') && oneAskLine.includes('blocking class') && !oneAskLine.includes('prefaced by'));
+ok('source: on the reduced ask (no performable step) the delegate option resolves to human-driven, never skip',
+  /delegate option resolves to human-driven \(never skip\)/.test(oneAskLine));
+ok('source: Pending-UAT bullet distinguishes a waiver from a deferral', pendingUatLine.includes('a waiver is not a deferral'));
+ok('source: Pending-UAT bullet pins the waiver exception (picked skip, recorded as unconfirmed, nothing opened)',
+  /The one exception is an explicit waiver[^.]*\. The human picked skip at the drive-mode ask[^.]*unconfirmed in `VERIFY`[^.]*nothing is opened/.test(pendingUatLine));
+const waiverResolveRe = /resolv(e|ing) on a confirmed pass, or on an explicit waiver if the user skips at the ask/;
+ok('source: Pending-UAT bullet option (a) resolves on a confirmed pass or an explicit waiver',
+  waiverResolveRe.test(pendingUatLine) && !pendingUatLine.includes('only on a confirmed pass'));
+ok('source: both ticket-engines Resolve lines let option (a) resolve on a confirmed pass or an explicit waiver',
+  guardLines254Early().length === 2 && guardLines254Early().every((l) => waiverResolveRe.test(l) && !l.includes('only on a confirmed pass')));
+ok('source: with-no-ticket preflight-then-ask phrase still occurs exactly twice in ticket-engines.md',
+  ticketEnginesSource.split('with no ticket (the stale-base preflight first, then the UAT setup, then the drive-mode ask').length - 1 === 2);
+ok('source: both Verify steps let the user skip, recorded as waived',
+  verifyStepLines.length === 2 && verifyStepLines.every((l) => /or skip \(waive acceptance\), recorded as waived/.test(l)));
+ok('source: techniques.md index row and auto.md lead-in name skip',
+  /ask who drives \(AI or human, or skip\)/.test(fs.readFileSync(path.join(sourceSkillsDir, '_shared', 'techniques.md'), 'utf8')) &&
+  autoSource.includes('drive-mode ask (AI-driven, human-driven, or skip)'));
+
+function guardLines254Early() { return ticketEnginesSource.split('\n').filter((l) => l.includes('Pending-UAT guard (before the close)')); }
+const guardLines254 = ticketEnginesSource.split('\n').filter((l) => l.includes('Pending-UAT guard (before the close)'));
+ok('source: both Pending-UAT guard lines say the guard does not fire when acceptance was explicitly waived',
+  guardLines254.length === 2 && guardLines254.every((l) => l.includes('explicitly waived')));
+ok('source: both Resolve steps state the waiver in the resolution comment',
+  guardLines254.length === 2 && guardLines254.every((l) => /resolution comment states the waiver/.test(l)));
+ok('source: the UAT follow-ups section closes on a confirmed pass or an explicit waiver',
+  uatFollowupSection.includes('confirmed pass or an explicit waiver') && uatFollowupSection.includes('closes as waived'));
+const driveRowLine = choicesSource.split('\n').find((l) => /^\|[^\n]*[Dd]rive-mode ask/.test(l)) || '';
+ok('source: choices.md drive-mode row names skip and states delegate never picks it',
+  driveRowLine.includes('skip') && /delegate never picks skip/.test(driveRowLine) && driveRowLine.includes('reduced ask') && driveRowLine.includes('human-driven'));
+ok('source: configuration-reference.md acceptance.browser paragraph names skip alongside AI-driven / human-driven',
+  /\*\*acceptance\.browser\.\*\*[\s\S]{0,200}human-driven,? or skip/.test(configReferenceSource));
+ok('source: auto.md states auto never picks skip', /never picks skip[^\n]*waiving acceptance/.test(autoSource));
+
+// Docs mirror: README, README.it, site (waiver recorded as unconfirmed; no unconditional "never closes").
+ok('README.md acceptance testing section names the waiver (skip) recorded as unconfirmed',
+  /\*\*Skip is a waiver, not a deferral\*\*[^\n]{0,80}`waived by the user \(unconfirmed\)`, never as a pass/.test(readmeSource));
+ok('README.md no-performable-step case asks human-driven or skip', /human-driven\*\* or \*\*skip\*\*/.test(readmeSource));
+ok('README.md point 6 allows an explicit waiver', /never closes on a UAT nobody ran unless you explicitly waive it/.test(readmeSource));
+const siteAcceptanceSource = fs.readFileSync(path.join(repoRoot, 'site', 'src', 'content', 'docs', 'docs', 'acceptance-testing.md'), 'utf8');
+ok('docs: auto never-picks-skip antecedent is the auto run, in all three docs',
+  /listed in the run's summary; `\/trailhead:auto` never picks skip/.test(readmeSource) && /listed in the run's summary; `\/trailhead:auto` never picks skip/.test(siteAcceptanceSource) && /elencato nel riepilogo della run; `\/trailhead:auto` non sceglie mai skip/.test(readmeItSource));
+ok('README.md build row and acceptance.browser row name skip',
+  /🔨 `build`[\s\S]{0,500}or skip/.test(readmeSource) && /`acceptance\.browser`[\s\S]{0,300}or skip/.test(readmeSource));
+ok('README.it.md acceptance testing section names the waiver (skip) recorded as unconfirmed',
+  /\*\*Skip è una rinuncia, non un rinvio\*\*[^\n]{0,160}`waived by the user \(unconfirmed\)`, cioè non confermata/.test(readmeItSource));
+ok('README.it.md no-performable-step case asks human-driven o skip', /human-driven\*\* o \*\*skip\*\*/.test(readmeItSource));
+ok('README.it.md point 6 allows an explicit waiver', /non si chiude mai su una UAT che nessuno ha eseguito, salvo che tu ci rinunci esplicitamente/.test(readmeItSource));
+ok('README.it.md build row and acceptance.browser row name skip',
+  /🔨 `build`[\s\S]{0,500}o skip/.test(readmeItSource) && /`acceptance\.browser`[\s\S]{0,300}o skip/.test(readmeItSource));
+ok('site acceptance-testing.md names the waiver (skip) recorded as unconfirmed', /\*\*Skip is a waiver, not a deferral\*\*[^\n]{0,80}`waived by the user \(unconfirmed\)`, never as a pass/.test(siteAcceptanceSource));
+ok('site acceptance-testing.md no-performable-step case asks human-driven or skip', /human-driven\*\* or \*\*skip\*\*/.test(siteAcceptanceSource));
+ok('site acceptance-testing.md point 6 allows an explicit waiver', /never closes on a UAT nobody ran unless you explicitly waive it/.test(siteAcceptanceSource));
+ok('site ticket-types.md build row and configuration.mdx acceptance.browser row name skip',
+  /`build`[\s\S]{0,500}or skip/.test(ticketTypesSource) && /`acceptance\.browser`[\s\S]{0,300}or skip/.test(configurationMdxSource));
+
 // --- codex hooks (#29) --------------------------------------------------------
 const codexHooksJsonPath = path.join(codexDir, 'hooks.json');
 ok('codex: hooks.json exists', fs.existsSync(codexHooksJsonPath));
 const codexHooksJson = JSON.parse(fs.readFileSync(codexHooksJsonPath, 'utf8'));
 const codexHooksJsonStr = JSON.stringify(codexHooksJson);
-ok('codex: hooks.json registers commit-guard under PreToolUse', codexHooksJsonStr.includes('trailhead-commit-guard.js') &&
-  (codexHooksJson.hooks.PreToolUse || []).some((g) => (g.hooks || []).some((h) => h.command.includes('trailhead-commit-guard.js'))));
-ok('codex: hooks.json registers secret-guard under PreToolUse', (codexHooksJson.hooks.PreToolUse || []).some((g) => (g.hooks || []).some((h) => h.command.includes('trailhead-secret-guard.js'))));
+ok('codex: hooks.json registers the merged Bash guards under PreToolUse', (codexHooksJson.hooks.PreToolUse || []).some((g) => g.matcher === 'Bash' &&
+  (g.hooks || []).some((h) => h.command.includes('trailhead-bash-guards.js') && h.command.endsWith(' --guards=commit,secret,install,body'))));
+ok('codex: hooks.json registers none of the per-guard scripts on their own', !/trailhead-(commit|secret|install|search|body)-guard\.js/.test(codexHooksJsonStr));
+ok('codex: the five guard modules the merged hook requires are still shipped (no search)',
+  ['commit', 'secret', 'install', 'body'].every((n) => fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', `trailhead-${n}-guard.js`))) &&
+  fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'trailhead-bash-guards.js')));
 ok('codex: hooks.json registers injection-scanner under PostToolUse', (codexHooksJson.hooks.PostToolUse || []).some((g) => (g.hooks || []).some((h) => h.command.includes('trailhead-issue-injection-scanner.js'))));
 ok('codex: hooks.json registers check-update under SessionStart', (codexHooksJson.hooks.SessionStart || []).some((g) => (g.hooks || []).some((h) => h.command.includes('trailhead-check-update.js'))));
 
+// #202: the mod (hooks/mod/register.tsx + the "modules" key) is Claude Code only;
+// the Codex projection must carry neither.
+function listFilesRecursive(dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+    const full = path.join(dir, e.name);
+    return e.isDirectory() ? listFilesRecursive(full) : [full];
+  });
+}
+ok('codex: hooks.json has no "modules" key (mod is Claude-only, #202)', !('modules' in codexHooksJson));
+ok('codex: no register.tsx under the install dir (#202)', !listFilesRecursive(codexDir).some((f) => path.basename(f) === 'register.tsx'));
+ok('codex: no .ts or .tsx file anywhere under the install dir (#202)', !listFilesRecursive(codexDir).some((f) => f.endsWith('.ts') || f.endsWith('.tsx')));
+
 ok('codex: skills/trailhead/hooks/trailhead-secret-guard.js exists', fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'trailhead-secret-guard.js')));
 ok('codex: skills/trailhead/hooks/lib/commit-message-check.js exists (commit-guard require target)',
   fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'commit-message-check.js')));
 ok('codex: skills/trailhead/hooks/lib/gh-subcommand.js exists (body-guard/secret-guard require target, #153)',
   fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'gh-subcommand.js')));
+ok('codex: skills/trailhead/hooks/lib/body-sources.js exists (secret-guard require target, #210)',
+  fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'body-sources.js')));
+ok('codex: skills/trailhead/hooks/lib/unmodelled.js exists (guards require target, #227)',
+  fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'unmodelled.js')));
 ok('codex: skills/trailhead/hooks/lib/model-defaults-review.js exists (check-update require target, #186)',
   fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'model-defaults-review.js')));
 ok('codex: skills/trailhead/hooks/lib/model-defaults.json exists (#186)',
@@ -796,6 +1037,25 @@ ok('codex: every trailhead-*.toml is pin-less when models.codex.* is unset', (()
   return tomls.every((f) => !/^model = /m.test(fs.readFileSync(path.join(dir, f), 'utf8')));
 })());
 
+// #250: the reviewing block (single source scripts/agent-blocks.md) is projected
+// verbatim into the two reviewing agents' TOMLs and into none of the other six.
+{
+  const sync250 = require(path.join(repoRoot, 'scripts', 'sync-agent-blocks.js'));
+  const reviewingBlock250 = sync250.parseSource(fs.readFileSync(path.join(repoRoot, 'scripts', 'agent-blocks.md'), 'utf8')).reviewing;
+  ok('#250: the source defines a reviewing block', typeof reviewingBlock250 === 'string' && reviewingBlock250.length > 0);
+  const agentsDir250 = path.join(unsetCodexHomeDir, 'agents');
+  const reviewingNames250 = new Set(['trailhead-verify', 'trailhead-review']); // the code-review agent projects as trailhead-review.toml
+  const tomls250 = fs.readdirSync(agentsDir250).filter((f) => /^trailhead-.*\.toml$/.test(f));
+  ok('#250: all 8 TOMLs are checked', tomls250.length === 8);
+  for (const f of tomls250) {
+    const name = f.replace(/\.toml$/, '');
+    const text = fs.readFileSync(path.join(agentsDir250, f), 'utf8');
+    const has = typeof reviewingBlock250 === 'string' && reviewingBlock250.length > 0 && text.includes(reviewingBlock250);
+    ok(`#250: ${f} ${reviewingNames250.has(name) ? 'carries' : 'does not carry'} the reviewing block verbatim`,
+      has === reviewingNames250.has(name));
+  }
+}
+
 // --- codex migration (#46): install over old prompt shims sweeps them --------
 const migCodexDir = mktmp();
 fs.mkdirSync(path.join(migCodexDir, 'prompts'), { recursive: true });
@@ -829,7 +1089,7 @@ ok('codex uninstall: cluster trailhead-view gone', !fs.existsSync(path.join(code
 ok('codex uninstall: hooks.json no longer contains trailhead commands', (() => {
   const h = JSON.parse(fs.readFileSync(codexHooksJsonPath, 'utf8'));
   const str = JSON.stringify(h);
-  return !str.includes('trailhead-commit-guard.js') && !str.includes('trailhead-secret-guard.js') &&
+  return !str.includes('trailhead-bash-guards.js') && !/trailhead-(commit|secret|install|search|body)-guard\.js/.test(str) &&
     !str.includes('trailhead-issue-injection-scanner.js') && !str.includes('trailhead-check-update.js');
 })());
 
@@ -858,17 +1118,31 @@ ok('claude: trailhead-work/../_shared/ticket-language.md resolves', fs.existsSyn
 
 ok('claude: commands/trailhead/work.md exists', fs.existsSync(path.join(claudeDir, 'commands', 'trailhead', 'work.md')));
 ok('claude: commands/trailhead/audit.md projected', fs.existsSync(path.join(claudeDir, 'commands', 'trailhead', 'audit.md')));
+ok('claude: commands/trailhead/panel.md projected (the mod answers it)', fs.existsSync(path.join(claudeDir, 'commands', 'trailhead', 'panel.md')));
 ok('claude: commands/trailhead/auto.md exists', fs.existsSync(path.join(claudeDir, 'commands', 'trailhead', 'auto.md')));
 ok('claude: hooks/trailhead-commit-guard.js exists', fs.existsSync(path.join(claudeDir, 'hooks', 'trailhead-commit-guard.js')));
 ok('claude: hooks/lib/commit-message-check.js exists (commit-guard require target)',
   fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'commit-message-check.js')));
 ok('claude: hooks/lib/gh-subcommand.js exists (body-guard/secret-guard require target, #153)',
   fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'gh-subcommand.js')));
+ok('claude: hooks/lib/body-sources.js exists (secret-guard require target, #210)',
+  fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'body-sources.js')));
+ok('claude: hooks/lib/unmodelled.js exists (guards require target, #227)',
+  fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'unmodelled.js')));
 ok('claude: hooks/lib/model-defaults-review.js exists (check-update require target, #186)',
   fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'model-defaults-review.js')));
 ok('claude: hooks/lib/model-defaults.json exists (#186)',
   fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'model-defaults.json')));
 
+// #202: the mod is not delivered by the npm installer yet.
+ok('claude: no hooks/mod/ dir in the npm install (#202)', !fs.existsSync(path.join(claudeDir, 'hooks', 'mod')));
+
+// #257: the hook logic ships as a .cjs beside the sh wrapper.
+const claudeCommitMsgCjs = path.join(claudeDir, 'trailhead', 'templates', 'trailhead-commit-msg.cjs');
+ok('claude: commit-msg .cjs logic projected', fs.existsSync(claudeCommitMsgCjs));
+ok('claude: commit-msg .cjs logic is byte-identical to source',
+  fs.readFileSync(claudeCommitMsgCjs, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-commit-msg.cjs'), 'utf8'));
+
 // #185: the commit-msg hook sync script ships wholesale with templates/ too.
 const claudeCommitMsgSync = path.join(claudeDir, 'trailhead', 'templates', 'trailhead-commit-msg-sync.js');
 ok('claude: commit-msg-sync script projected', fs.existsSync(claudeCommitMsgSync));
@@ -881,6 +1155,17 @@ const claudeAuditWalk = path.join(claudeDir, 'trailhead', 'templates', 'trailhea
 ok('claude: audit-walk script projected', fs.existsSync(claudeAuditWalk));
 ok('claude: audit-walk script is byte-identical to source',
   fs.readFileSync(claudeAuditWalk, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-audit-walk.js'), 'utf8'));
+// #253: the Resolve bookkeeping helpers are installed, and (npm layout: templates at
+// <config>/trailhead/templates, hooks at <config>/hooks) find the secret guard.
+for (const helper of ['trailhead-issue-body.js', 'trailhead-dashboard.js']) {
+  const installed = path.join(claudeDir, 'trailhead', 'templates', helper);
+  ok(`claude: ${helper} installed`, fs.existsSync(installed));
+  ok(`claude: ${helper} is byte-identical to source`,
+    fs.readFileSync(installed, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', helper), 'utf8'));
+  ok(`claude: ${helper} keeps its executable bit`, (fs.statSync(installed).mode & 0o111) !== 0);
+}
+ok('claude: the installed issue-body helper finds the secret guard',
+  require(path.join(claudeDir, 'trailhead', 'templates', 'trailhead-issue-body.js')).loadGuard() !== null);
 // Regression: the commit-guard does require('./lib/commit-message-check.js'), so
 // it only loads if the lib was copied alongside it. Run it with a benign Bash
 // payload and assert it does not crash with a missing-module error.
@@ -1018,7 +1303,15 @@ for (const nm of ['trailhead', 'trailhead-chart', 'trailhead-work', 'trailhead-v
 const settingsPath = path.join(claudeDir, 'settings.json');
 ok('claude: settings.json exists', fs.existsSync(settingsPath));
 const settingsContent = fs.readFileSync(settingsPath, 'utf8');
-ok('claude: settings.json references commit-guard', settingsContent.includes('trailhead-commit-guard.js'));
+ok('claude: settings.json registers the merged Bash guards', settingsContent.includes('trailhead-bash-guards.js'));
+ok('claude: settings.json registers none of the per-guard scripts on their own',
+  !/trailhead-(commit|secret|install|search|body)-guard\.js/.test(settingsContent));
+ok('claude: exactly one PreToolUse/Bash trailhead-bash-guards registration', (() => {
+  const s = JSON.parse(settingsContent);
+  return (s.hooks.PreToolUse || []).flatMap((g) => g.hooks || []).filter((h) => h.command.includes('trailhead-bash-guards.js')).length === 1;
+})());
+ok('claude: hooks/trailhead-bash-guards.js and its five modules exist', ['bash-guards', 'commit-guard', 'secret-guard', 'install-guard', 'search-guard', 'body-guard']
+  .every((n) => fs.existsSync(path.join(claudeDir, 'hooks', `trailhead-${n}.js`))));
 // mockup-link-guard: Claude-only PreToolUse(AskUserQuestion) backstop for the
 // Prototype "link in the same message as the approval ask" rule.
 ok('claude: hooks/trailhead-mockup-link-guard.js exists', fs.existsSync(path.join(claudeDir, 'hooks', 'trailhead-mockup-link-guard.js')));
@@ -1180,6 +1473,9 @@ ok('source: teamwork.md fallback resolves the hooks dir via rev-parse --git-path
   teamworkSource.includes('git -C <working-root> rev-parse --git-path hooks'));
 ok('source: teamwork.md fallback classifies by the trailhead header line',
   teamworkSource.includes('// trailhead commit-msg hook (git).'));
+ok('source: teamwork.md fallback knows the sh wrapper header and the .cjs logic file (#257)',
+  teamworkSource.includes('# trailhead commit-msg hook (git).') && teamworkSource.includes('trailhead-commit-msg.cjs'));
+ok('source: substrate-commands.md names the .cjs logic file (#257)', substrateCommandsSource.includes('trailhead-commit-msg.cjs'));
 ok('source: teamwork.md fallback checks the executable bit (test -x)',
   teamworkSource.includes('test -x'));
 ok('source: teamwork.md fallback reads only the first 5 lines',
@@ -1342,6 +1638,78 @@ const missingBodyGuardPkg = brokenPkg((p) => fs.rmSync(path.join(p, 'plugins', '
   ok('(h) pre-#169 search-guard migration: the stale entry is gone', !afterHooksJson.includes('trailhead-search-guard.js'));
 }
 
+// (#207) Migration to the merged Bash guard hook. An install that registered
+// each guard on its own ends with only the merged entry; install and uninstall
+// are idempotent; uninstall removes the merged entry and every legacy one.
+const LEGACY_GUARD_RE = /trailhead-(commit|secret|install|search|body)-guard\.js/;
+const bashGuardCommands = (registry) => (registry.hooks.PreToolUse || [])
+  .flatMap((g) => (g.matcher === 'Bash' ? g.hooks || [] : []))
+  .map((h) => h.command)
+  .filter((c) => c.includes('trailhead-bash-guards.js') || LEGACY_GUARD_RE.test(c));
+{
+  const mDir = mktmp();
+  runInstaller([`--claude`, `--dir=${mDir}`]);
+  const settingsFile = path.join(mDir, 'settings.json');
+  const settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8'));
+  const hooksDirM = path.join(mDir, 'hooks');
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse.map((g) => ({
+    ...g,
+    hooks: g.hooks.filter((h) => !h.command.includes('trailhead-bash-guards.js')),
+  })).filter((g) => g.hooks.length);
+  const legacyGroup = { matcher: 'Bash', hooks: ['commit', 'secret', 'install', 'search', 'body']
+    .map((n) => ({ type: 'command', command: `node "${path.join(hooksDirM, `trailhead-${n}-guard.js`)}"` })) };
+  settings.hooks.PreToolUse.push(legacyGroup);
+  fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2));
+  const out = runPkg(repoRoot, [`--claude`, `--dir=${mDir}`]);
+  ok('(#207) claude migration: exit 0', out.status === 0);
+  const after = JSON.parse(fs.readFileSync(settingsFile, 'utf8'));
+  const cmds = bashGuardCommands(after);
+  ok('(#207) claude migration: only the merged entry remains', cmds.length === 1 && cmds[0].includes('trailhead-bash-guards.js'));
+  const once = fs.readFileSync(settingsFile, 'utf8');
+  runInstaller([`--claude`, `--dir=${mDir}`]);
+  ok('(#207) claude install twice leaves the same settings.json', fs.readFileSync(settingsFile, 'utf8') === once);
+  runInstaller([`--claude`, `--dir=${mDir}`, '--uninstall']);
+  const gone = fs.readFileSync(settingsFile, 'utf8');
+  ok('(#207) claude uninstall strips the merged entry', !gone.includes('trailhead-bash-guards.js'));
+  runInstaller([`--claude`, `--dir=${mDir}`, '--uninstall']);
+  ok('(#207) claude uninstall twice leaves the same settings.json', fs.readFileSync(settingsFile, 'utf8') === gone);
+}
+{
+  const mDir = mktmp();
+  const hooksJsonFile = path.join(mDir, 'hooks.json');
+  const scriptsDir = path.join(mDir, 'skills', 'trailhead', 'hooks');
+  runInstaller([`--codex`, `--dir=${mDir}`]);
+  const reg = JSON.parse(fs.readFileSync(hooksJsonFile, 'utf8'));
+  reg.hooks.PreToolUse = reg.hooks.PreToolUse.map((g) => ({
+    ...g,
+    hooks: g.hooks.filter((h) => !h.command.includes('trailhead-bash-guards.js')),
+  })).filter((g) => g.hooks.length);
+  reg.hooks.PreToolUse.push({ matcher: 'Bash', hooks: ['commit', 'secret', 'install', 'search', 'body']
+    .map((n) => ({ type: 'command', command: `node "${path.join(scriptsDir, `trailhead-${n}-guard.js`)}"` })) });
+  fs.writeFileSync(hooksJsonFile, JSON.stringify(reg, null, 2));
+  const out = runPkg(repoRoot, [`--codex`, `--dir=${mDir}`]);
+  ok('(#207) codex migration: exit 0', out.status === 0);
+  const cmds = bashGuardCommands(JSON.parse(fs.readFileSync(hooksJsonFile, 'utf8')));
+  ok('(#207) codex migration: only the merged entry remains', cmds.length === 1 &&
+    cmds[0].endsWith(' --guards=commit,secret,install,body'));
+  const once = fs.readFileSync(hooksJsonFile, 'utf8');
+  runInstaller([`--codex`, `--dir=${mDir}`]);
+  ok('(#207) codex install twice leaves the same hooks.json', fs.readFileSync(hooksJsonFile, 'utf8') === once);
+  // A legacy registration reappearing next to the merged one is removed on uninstall too.
+  const withLegacy = JSON.parse(once);
+  withLegacy.hooks.PreToolUse.push({ matcher: 'Bash', hooks: [
+    { type: 'command', command: `node "${path.join(scriptsDir, 'trailhead-search-guard.js')}"` },
+    { type: 'command', command: `node "${path.join(scriptsDir, 'trailhead-commit-guard.js')}"` },
+  ] });
+  fs.writeFileSync(hooksJsonFile, JSON.stringify(withLegacy, null, 2));
+  runInstaller([`--codex`, `--dir=${mDir}`, '--uninstall']);
+  const gone = fs.readFileSync(hooksJsonFile, 'utf8');
+  ok('(#207) codex uninstall strips the merged entry and every legacy one',
+    !gone.includes('trailhead-bash-guards.js') && !LEGACY_GUARD_RE.test(gone));
+  runInstaller([`--codex`, `--dir=${mDir}`, '--uninstall']);
+  ok('(#207) codex uninstall twice leaves the same hooks.json', fs.readFileSync(hooksJsonFile, 'utf8') === gone);
+}
+
 // (i) an unresolved env var on a registered target warns instead of failing.
 {
   const vDir = mktmp();
@@ -1481,6 +1849,12 @@ ok('source: manage SKILL.md routes audit to references/auditing.md', /\*\*`audit
 const dispatcherSrc190 = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead', 'SKILL.md'), 'utf8');
 ok('source: dispatcher argument-hint lists audit', /argument-hint: "[^"]*\|audit\|[^"]*"/.test(dispatcherSrc190));
 ok('source: dispatcher manage-cluster routing list includes audit', /manage cluster is built[^\n]*`prune`, and `audit`/.test(dispatcherSrc190));
+// #208: panel is a verb the Claude Code mod answers; the dispatcher lists it but routes it to no skill.
+ok('source: dispatcher argument-hint lists panel', /argument-hint: "[^"]*\|panel\|[^"]*"/.test(dispatcherSrc190));
+ok('source: dispatcher says panel is mod-only and routes it to no skill', /`panel`\*\* verb routes to no skill[^\n]*Claude Code[^\n]*mod/.test(dispatcherSrc190));
+const panelCmdSrc208 = fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'commands', 'panel.md'), 'utf8');
+ok('source: commands/panel.md invokes no skill', !/Skill tool|skill name|\$trailhead|trailhead-(view|work|chart|capture|manage)/.test(panelCmdSrc208));
+ok('source: commands/panel.md tells the model the panel is unavailable in one line', /2\.1\.287\+[^\n]*not available/.test(panelCmdSrc208));
 
 const auditingPath190 = path.join(sourceSkillsDir, 'trailhead-manage', 'references', 'auditing.md');
 const auditingSrc = fs.existsSync(auditingPath190) ? fs.readFileSync(auditingPath190, 'utf8') : '';
@@ -1684,6 +2058,129 @@ for (const doc of ['README.md', 'README.it.md', siteManageDoc]) {
   }
 }
 
+// #202: the plugin's own hooks.json declares exactly one mod module, and it exists.
+const pluginHooksJson = JSON.parse(fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'hooks', 'hooks.json'), 'utf8'));
+ok('source: hooks.json declares exactly one module (#202)', Array.isArray(pluginHooksJson.modules) && pluginHooksJson.modules.length === 1);
+ok('source: the declared module file exists, relative to hooks.json (#202)',
+  fs.existsSync(path.resolve(repoRoot, 'plugins', 'trailhead', 'hooks', pluginHooksJson.modules[0])));
+ok('source: hooks.json keeps its command hooks next to the module (#202)',
+  ['PreToolUse', 'PostToolUse', 'SessionStart'].every((ev) => (pluginHooksJson.hooks?.[ev] || []).length > 0));
+
+// --- #259: `trailhead:paused` label marks a paused ticket (pause adds, resume/claim drop) ---
+const firstUseLine = (substrateCommandsSource.match(/^1\. Create any missing labels.*$/m) || [''])[0];
+ok('source: first-use setup lists twenty labels including trailhead:paused and trailhead:uat',
+  /all twenty:/.test(firstUseLine) && firstUseLine.includes('`trailhead:paused`') && firstUseLine.includes('`trailhead:uat`'));
+ok('source: no stale "eighteen" or "nineteen" label count remains in the shared skills',
+  !/eighteen|nineteen/.test(substrateCommandsSource) && !/eighteen|nineteen/.test(substrateSource));
+ok('source: substrate-commands.md ensures trailhead:paused idempotently',
+  /gh label create trailhead:paused --color FBCA04 --description "Paused: a PAUSED checkpoint holds its next step" 2>\/dev\/null \|\| true/.test(substrateCommandsSource));
+ok('source: substrate.md documents trailhead:paused as set by pause, cleared by resume or claim, off the frontier (#263)',
+  /\*\*`trailhead:paused`\*\*[\s\S]{0,500}pause[\s\S]{0,200}resume[\s\S]{0,200}claim[\s\S]{0,400}excluded from the frontier/.test(substrateSource));
+const pauseBullet = (teamworkSource.match(/^- \*\*Pause\*\*.*$/m) || [''])[0];
+const resumeBullet = (teamworkSource.match(/^- \*\*Resume\*\*.*$/m) || [''])[0];
+ok('source: teamwork.md pause adds trailhead:paused (created idempotently) after the PAUSED comment',
+  /post a \*\*`PAUSED`\*\* checkpoint comment[\s\S]{0,1200}add the `trailhead:paused` label[\s\S]{0,120}creating it idempotently first[\s\S]{0,200}after the `PAUSED` comment/.test(pauseBullet));
+ok('source: teamwork.md resume removes trailhead:paused only after the claim is confirmed',
+  /gh issue edit <n> --remove-label trailhead:paused/.test(resumeBullet) &&
+  /only after the claim is confirmed[\s\S]{0,300}a refused resume leaves the ticket visibly paused/.test(resumeBullet));
+ok('source: work SKILL.md claim step drops trailhead:paused from a claimed paused ticket',
+  /\*\*Claim\*\* it:[\s\S]{0,1200}carries `trailhead:paused`[\s\S]{0,120}drops it at the claim/.test(workSkillSource));
+ok('source: work SKILL.md quick isolation bullet drops trailhead:paused at the claim',
+  /^- \*\*Same isolation setup as `work`\.\*\*.*claimed ticket that carries `trailhead:paused` drops it at the claim/m.test(workSkillSource));
+
+// --- #261: `trailhead:uat` label marks a pending UAT follow-up (marker, not a state) ---
+{
+  ok('source: substrate-commands.md ensures trailhead:uat idempotently',
+    /gh label create trailhead:uat --color [0-9A-Fa-f]{6} --description "Pending UAT: an acceptance test still to run" 2>\/dev\/null \|\| true/.test(substrateCommandsSource));
+  {
+    const helperSource = fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-uat-backfill.js'), 'utf8');
+    const docColor = (substrateCommandsSource.match(/gh label create trailhead:uat --color ([0-9A-Fa-f]{6})/) || [])[1];
+    const helperColor = (helperSource.match(/const COLOR = '([0-9A-Fa-f]{6})'/) || [])[1];
+    ok('source: the backfill helper creates trailhead:uat with the same colour as substrate-commands.md',
+      docColor !== undefined && docColor === helperColor);
+  }
+  ok('source: substrate-commands.md has no create-then-backfill chain and invokes the backfill helper',
+    /trailhead-uat-backfill\.js/.test(substrateCommandsSource) && !/trailhead:uat[^\n]*&&[^\n]*backfill/.test(substrateCommandsSource));
+  ok('source: first-use setup runs the backfill helper after the labels',
+    /^1\. Create any missing labels[\s\S]{0,1500}?trailhead-uat-backfill\.js/m.test(substrateCommandsSource));
+  ok('source: substrate.md documents trailhead:uat as a marker label right after the state labels, not a state, not a frontier filter',
+    /\*\*`trailhead:uat`\*\*[\s\S]{0,700}marker[\s\S]{0,400}not a state[\s\S]{0,400}never a frontier filter/.test(substrateSource)
+    && substrateSource.indexOf('**`trailhead:uat`**') > substrateSource.indexOf('**`trailhead:paused`**')
+    && substrateSource.indexOf('**`trailhead:uat`**') < substrateSource.indexOf('**Frontier**'));
+  ok('source: acceptance-testing.md option (b) opens the follow-up with trailhead:uat in the gh issue create --label list, label ensured first',
+    /open a follow-up ticket before that close[\s\S]{0,900}--label[^\n]{0,200}`?trailhead:uat/.test(acceptanceTestingSource)
+    && /ensur\w* (the )?`?trailhead:uat`? (label )?idempotently/.test(acceptanceTestingSource));
+  ok('source: ticket-engines.md UAT follow-ups section names the label',
+    /UAT follow-up[\s\S]{0,1500}`trailhead:uat`/.test(ticketEnginesSource.split('\n').filter((l) => /^A ticket whose body carries/.test(l)).join('\n')));
+  ok('source: work SKILL.md work-start runs the backfill helper once per clone, marker gated',
+    /trailhead-uat-backfill\.js[^\n]*--marker[^\n]*\.trailhead\/uat-backfill/.test(workSkillSource));
+  ok('source: work SKILL.md passes the backfill marker as an absolute path under the working root',
+    /trailhead-uat-backfill\.js[^\n]*--marker <working-root>\/\.trailhead\/uat-backfill/.test(workSkillSource));
+  ok('source: .gitignore ignores .trailhead/uat-backfill',
+    /^\.trailhead\/uat-backfill$/m.test(fs.readFileSync(path.join(repoRoot, '.gitignore'), 'utf8')));
+  ok('source: work SKILL.md mentions the uat-backfill marker as gitignored per-clone state',
+    /`\.trailhead\/uat-backfill`[^\n]*(gitignored|never committed)/.test(workSkillSource));
+  const producerSources = { 'acceptance-testing.md': acceptanceTestingSource, 'site acceptance-testing.md': siteAcceptanceSource };
+  for (const [name, src] of Object.entries(producerSources)) {
+    ok(`source: ${name} writes the pointer as UAT of: [<parent name>](<parent url>)`,
+      src.includes('UAT of: [<parent name>](<parent url>)') && !/UAT of: <parent name>\(link\)|UAT of: #<n>/.test(src));
+  }
+}
+
+// --- #263: a paused ticket is off the frontier on every surface ---
+{
+  const viewSkillSource = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-view', 'SKILL.md'), 'utf8');
+  const siteDocs = path.join(repoRoot, 'site', 'src', 'content', 'docs', 'docs');
+  const siteViewSource = fs.readFileSync(path.join(siteDocs, 'commands', 'view.md'), 'utf8');
+  const siteWorkSource = fs.readFileSync(path.join(siteDocs, 'commands', 'work.md'), 'utf8');
+  const changelogSource = fs.readFileSync(path.join(repoRoot, 'CHANGELOG.md'), 'utf8');
+  const searchExprs = (src) => [...src.matchAll(/--search\s+"([^"]*no:assignee[^"]*)"/g)].map((m) => m[1]);
+  const base = 'no:assignee -label:trailhead:blocked -label:trailhead:unverified -label:trailhead:paused';
+  const wbExcl = `${base} -label:trailhead:whiteboard`;
+  const tally = (exprs) => exprs.reduce((acc, e) => ({ ...acc, [e]: (acc[e] || 0) + 1 }), {});
+  const sameTally = (got, want) => JSON.stringify(Object.entries(got).sort()) === JSON.stringify(Object.entries(want).sort());
+
+  ok('source: substrate-commands.md frontier queries each exclude paused (two repo-wide, four label-scoped or whiteboard or count)',
+    sameTally(tally(searchExprs(substrateCommandsSource)), { [wbExcl]: 2, [base]: 4 }));
+  ok('source: multi-map.md scoped frontier query excludes paused', sameTally(tally(searchExprs(multiMapSource)), { [base]: 1 }));
+  ok('source: trailhead-view SKILL.md whiteboard frontier query excludes paused', sameTally(tally(searchExprs(viewSkillSource)), { [base]: 1 }));
+  ok('source: the cookbook frontier comment says not paused',
+    /# the frontier: open, unassigned, not blocked, not unverified, not paused, one query/.test(substrateCommandsSource));
+
+  ok('source: substrate.md Frontier definition excludes trailhead:paused',
+    /\*\*Frontier\*\* = open, unassigned tickets that are \*\*not\*\* `trailhead:blocked`, \*\*not\*\* `trailhead:unverified` and \*\*not\*\* `trailhead:paused`/.test(substrateSource));
+  const pausedBullet = (substrateSource.match(/^- \*\*`trailhead:paused`\*\*.*$/m) || [''])[0];
+  ok('source: substrate.md paused bullet: excluded from the frontier, taken back with /trailhead:resume',
+    /excluded from the frontier/.test(pausedBullet) && /\/trailhead:resume/.test(pausedBullet));
+  ok('source: the old "does not change the frontier query" wording is gone',
+    !/does not change the frontier query/.test(substrateSource));
+
+  const paused = /^- \*\*In progress\*\*[^\n]*\n- \*\*Paused\*\*[^\n]*\/trailhead:resume <n>`[^\n]*\n- \*\*Blocked\*\*/gm;
+  ok('source: the map and whiteboard renders both list a Paused group between In progress and Blocked',
+    (viewSkillSource.match(paused) || []).length === 2);
+  ok('source: both render Frontier bullets say not paused',
+    (viewSkillSource.match(/^- \*\*Frontier\*\*:[^\n]*not[^\n]*`trailhead:paused`/gm) || []).length === 2);
+
+  ok('source: multi-map.md park & switch resumes with /trailhead:resume only',
+    /Resume later with `\/trailhead:resume`/.test(multiMapSource) && !/just `\/trailhead:work` once that map is active/.test(multiMapSource));
+
+  ok('source: work SKILL.md: bare work takes the paused-excluding frontier, a named work or quick still works a paused ticket',
+    /Otherwise take a frontier ticket[\s\S]{0,600}never a `trailhead:paused` ticket/.test(workSkillSource) &&
+    /\*\*named\*\* ticket may also be a `trailhead:paused` one, which `work <n>` \/ `quick <n>` takes back/.test(workSkillSource) &&
+    /carries `trailhead:paused` drops it at the claim/.test(workSkillSource));
+
+  ok('source: auto.md resumes owned paused tickets in step 2 and no longer says they come back on the frontier',
+    /\*\*each\*\* ticket you own[\s\S]{0,200}`trailhead:paused`/.test(autoSource) &&
+    !/paused\/stuck tickets are back on the frontier/.test(autoSource) && !/paused[^.\n]{0,40}back on the frontier/.test(autoSource));
+  ok('source: site work.md says a paused ticket is off the frontier until resumed',
+    /off the frontier until (it is )?resumed/.test(siteWorkSource));
+  ok('source: site view.md describes the Paused group off the frontier', /Paused/.test(siteViewSource) && /not paused|off the frontier/.test(siteViewSource));
+  const conceptsSource = fs.readFileSync(path.join(siteDocs, 'concepts.md'), 'utf8');
+  ok('source: concepts.md, README.md and README.it.md frontier definitions mention paused',
+    /not paused/.test(conceptsSource) && /not paused/.test(readmeSource) && /in pausa/.test(readmeItSource));
+  ok('source: CHANGELOG Unreleased > Changed has a #263 entry', /### Changed[\s\S]*?\(#263\)/.test(changelogSource.split('## 0.14.0')[0]));
+}
+
 for (const d of tmpDirs) {
   fs.rmSync(d, { recursive: true, force: true });
 }