@marcomigozzi/trailhead 0.14.0 → 0.15.0

package/bin/trailhead.test.js

@@ -118,6 +118,12 @@ 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));
@@ -129,6 +135,24 @@ 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) &&
@@ -140,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
@@ -210,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,
@@ -287,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-
@@ -543,6 +622,30 @@ ok('source: trailhead-work SKILL.md work step 1 points to the named-ticket activ
 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));
@@ -580,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',
@@ -721,6 +824,89 @@ 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));
@@ -851,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 });
@@ -932,6 +1137,12 @@ ok('claude: hooks/lib/model-defaults.json exists (#186)',
 // #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));
@@ -944,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.
@@ -1251,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',
@@ -1841,6 +2066,121 @@ ok('source: the declared module file exists, relative to hooks.json (#202)',
 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 });
 }

package/bin/uat-setup-docs.test.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// Docs test for #252: the skill prose wires the UAT setup step into every UAT start
+// (after the stale-base preflight, before the drive-mode ask) and documents the
+// uat.setup / uat.accounts config keys.
+// Run: node uat-setup-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const skills = path.join(__dirname, '..', 'plugins', 'trailhead', 'skills');
+const read = (rel) => fs.readFileSync(path.join(skills, rel), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const HELPER = 'trailhead-uat-setup.js';
+const EXPECT = {
+  '_shared/techniques/acceptance-testing.md': [
+    '**UAT setup comes next.**', HELPER, '`uat.setup`', '`uat.accounts`', '`unconfigured`', '`invalid`', 'retry', 'treat as a defect', 'Never a silent fallback',
+    'never a value', 'step names and results only', 'declined again, it is not re-offered this session', '--config-root',
+    '`run --from <failedStep>`', '`run --from <failedStep + 1>`', '`--only <i>`', '`--step-timeout`', '`--ready-timeout`', 'kills only its `sh`', '> /tmp/dev.log 2>&1 &',
+  ],
+  '_shared/configuration-reference.md': [
+    '| `uat.setup` |', '| `uat.accounts` |', '**UAT setup.**', '`missing-env`', 'References, never values', 'the nested form wins', '`testing.webapp` / `testing.url` are unchanged',
+    '**🧰 UAT setup**', '**👤 Test account**', 'never the secret\'s value',
+    '`\\$NAME`', 'outside single quotes', 'redirect its own output', '> /tmp/dev.log 2>&1 &',
+  ],
+  'trailhead-work/references/auto.md': ['**UAT setup in `auto`**', 'no probe, no proposal, no save offer', 'run-end summary'],
+};
+for (const [rel, needles] of Object.entries(EXPECT)) {
+  const text = read(rel);
+  for (const needle of needles) ok(`${rel} names: ${needle}`, text.includes(needle));
+}
+
+// In the technique: preflight bullet < setup bullet < drive-mode ask.
+const tech = read('_shared/techniques/acceptance-testing.md');
+const pre = tech.indexOf('- **Stale-base preflight comes first.**');
+const setup = tech.indexOf('- **UAT setup comes next.**');
+const ask = tech.indexOf('- **Drive mode: ask who drives the UAT.**');
+ok('setup bullet sits between the preflight bullet and the drive-mode ask', pre >= 0 && pre < setup && setup < ask);
+ok('setup names all three start paths', ['`build`/`bug` Verify', 'Pending-UAT guard', '`UAT of:`'].every((s) => tech.slice(setup, ask).includes(s)));
+
+// Each engine start path names the setup after the preflight and before the drive-mode ask.
+const engines = read('trailhead-work/references/ticket-engines.md');
+const lines = engines.split('\n');
+const step = (prefix, from = 0) => lines.findIndex((l, i) => i >= from && l.startsWith(prefix));
+const buildVerify = step('4. **Verify**');
+const buildResolve = step('5. **Resolve**', buildVerify + 1);
+const bugVerify = step('4. **Verify**', buildResolve + 1);
+for (const [name, idx] of [['build Verify', buildVerify], ['bug Verify', bugVerify]]) {
+  const l = lines[idx];
+  const s = l.indexOf('opening with the UAT setup');
+  ok(`${name} names the UAT setup`, s >= 0);
+  ok(`${name}: preflight, then setup, then the drive-mode ask`, l.indexOf('Stale-base preflight') < s && s < l.indexOf('then the drive-mode ask'));
+}
+ok('Pending-UAT option (a) runs preflight, setup, then the ask (build and bug)',
+  engines.split('with no ticket (the stale-base preflight first, then the UAT setup, then the drive-mode ask').length === 3);
+ok('UAT follow-up: preflight, then setup, then the ask',
+  /starting with the stale-base preflight[^;]*, then the UAT setup \(`trailhead-uat-setup\.js`[^;]*, and then the drive-mode ask/.test(engines));
+
+for (const rel of ['_shared/configuration-reference.md', '_shared/techniques/acceptance-testing.md', 'trailhead-work/references/ticket-engines.md', 'trailhead-work/references/auto.md']) {
+  ok(`${rel} has no em-dash`, !read(rel).includes('—'));
+}
+
+console.log(`uat-setup-docs.test.js: ${passed} checks passed`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcomigozzi/trailhead",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Start and drive large projects as a map of tickets on GitHub Issues. Map-based onboarding + a discuss→plan→execute→verify engine, all on the Issues. Installs the trailhead skill, commands, and hooks into your agent's config dir.",
   "bin": {
     "trailhead": "bin/trailhead.js"

package/plugins/trailhead/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trailhead",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Start and drive large projects as a map of tickets on GitHub Issues, resolving one at a time. Map-based onboarding + a discuss→plan→execute→verify engine with atomic commits, all on the Issues. Ships as a dispatcher plus cohesion-clustered skills over a shared core; depends on nothing beyond an authenticated gh CLI.",
   "author": {
     "name": "Marco Migozzi",

package/plugins/trailhead/agents/trailhead-code-review.md

@@ -7,6 +7,19 @@ tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
 
 trailhead's code-review subagent. Review the ticket's diff adversarially on the Code review technique's axes, verifying each finding before reporting. Do not defer to a convention or a settled-decision memory.
 
-The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/code-review.md`); follow that, not any embedded copy. Read-only by policy: it reviews and reports into trailhead's `VERIFY` comment, it must never Edit/Write or commit. Model-agnostic by design: the engine passes the `config.models.review` model as the spawn-time override, so config stays authoritative.
+The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/code-review.md`); follow that, not any embedded copy. Read-only by policy: it reviews and returns the report (the orchestrator posts it as the `VERIFY` comment), it must never Edit/Write or commit. Model-agnostic by design: the engine passes the `config.models.review` model as the spawn-time override, so config stays authoritative.
 
-**Search-command hygiene.** Prefer the Grep and Read tools over shelling out; when a Bash `grep`/read is genuinely needed, pass the path as an explicit argument (`grep -niE "<patterns>" <abs>/<file>`, `wc -l <abs>/<file>`) and run git as `git -C <abs> ...`. **Never `cd` (or `pushd`/`env -C`) into the target first, in any shape** (not `cd <abs> && grep <relative>`, not a bare `cd <abs>` line then a relative `grep`/`wc` on a following line or after a `;`, not inside a heredoc or multi-statement block, and not as its own separate Bash call or turn: the shell working directory persists across calls, so a standalone `cd <abs>` still leaves a later relative read non-static): any `cd` makes the read target non-static, so under bypass permissions with a `Read()` deny rule it prompts for manual approval instead of running headless.
+<!-- trailhead:agent-block common -->
+**Search-command hygiene.** Prefer the Grep and Read tools; use absolute paths and `git -C <abs>`.
+Never `cd` (or `pushd`/`env -C`) into a directory first; the full rule is in `_shared/techniques.md`.
+
+**Boundaries.** Never `git push`. Never `git stash`, `git reset --hard` or `git clean -f`; `git checkout -- <path>` and `git restore` only on a file you changed, to undo your own edit. Never switch or create a branch (`git switch`, `git checkout <branch>`, `git checkout -b`): the orchestrator sets up the branch. Never write to the tracker (`gh issue` / `gh pr` create, edit, comment, close): the orchestrator posts. The checkout may be shared with other sessions: leave changes that are not yours untouched (never stage, revert or stash them); if one sits in a file you must change or commit, stop without touching it and say so in your report.
+<!-- /trailhead:agent-block common -->
+
+<!-- trailhead:agent-block reviewing -->
+**Return contract.** Return the complete report as your final message. Do not post it anywhere (no issue comment, no PR comment): the orchestrator posts the `VERIFY` comment after it checks the status line.
+- The first line of the report is the technique's `status:` line, verbatim: `status: <token>`, with nothing before it and no other `status:` line.
+- trailhead-verify: `<token>` is one of `met` | `gaps_found` | `inconclusive`.
+- trailhead-code-review: `<token>` is one of `clean` | `issues_found`, and line 2 is the counts line `critical: <n> · warning: <n> · info: <n>`.
+- Read-only: never Edit/Write, never commit.
+<!-- /trailhead:agent-block reviewing -->

package/plugins/trailhead/agents/trailhead-codebase-map.md

@@ -9,4 +9,23 @@ trailhead's codebase-map reader subagent. Map ONE non-overlapping facet of the r
 
 The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/codebase-map.md`); follow that, not any embedded copy. Read-only by policy: read-only by construction. Model-agnostic by design: the engine passes the session model at spawn (no dedicated model key), so config stays authoritative.
 
-**Search-command hygiene.** Prefer the Grep and Read tools over shelling out; when a Bash `grep`/read is genuinely needed, pass the path as an explicit argument (`grep -niE "<patterns>" <abs>/<file>`, `wc -l <abs>/<file>`) and run git as `git -C <abs> ...`. **Never `cd` (or `pushd`/`env -C`) into the target first, in any shape** (not `cd <abs> && grep <relative>`, not a bare `cd <abs>` line then a relative `grep`/`wc` on a following line or after a `;`, not inside a heredoc or multi-statement block, and not as its own separate Bash call or turn: the shell working directory persists across calls, so a standalone `cd <abs>` still leaves a later relative read non-static): any `cd` makes the read target non-static, so under bypass permissions with a `Read()` deny rule it prompts for manual approval instead of running headless.
+<!-- trailhead:agent-block common -->
+**Search-command hygiene.** Prefer the Grep and Read tools; use absolute paths and `git -C <abs>`.
+Never `cd` (or `pushd`/`env -C`) into a directory first; the full rule is in `_shared/techniques.md`.
+
+**Boundaries.** Never `git push`. Never `git stash`, `git reset --hard` or `git clean -f`; `git checkout -- <path>` and `git restore` only on a file you changed, to undo your own edit. Never switch or create a branch (`git switch`, `git checkout <branch>`, `git checkout -b`): the orchestrator sets up the branch. Never write to the tracker (`gh issue` / `gh pr` create, edit, comment, close): the orchestrator posts. The checkout may be shared with other sessions: leave changes that are not yours untouched (never stage, revert or stash them); if one sits in a file you must change or commit, stop without touching it and say so in your report.
+<!-- /trailhead:agent-block common -->
+
+<!-- trailhead:agent-block investigating -->
+**Return contract.** Return the complete report as your final message. Do not post it anywhere (no issue comment, no PR comment): the orchestrator posts it. Never commit, and never create or switch a branch: the report is the only artifact.
+- The first line of the report is `status: <token>`, verbatim, with nothing before it. It is the only line starting with `status:`: status text anywhere in the body is quoted in a code fence or a blockquote, or reworded.
+- statuses: `found` | `inconclusive` | `needs_input`.
+- required fields: `answer`, `evidence`, `open questions`.
+- optional fields: none.
+- invariant: `needs_input` => `open questions` non-empty.
+- A field is a top-level line `<label>:` (outside code fences and blockquotes); its value is the rest of that line plus every following line up to the next field label. An empty value or `none` means none.
+- Fields are the end of the report: nothing after the last field.
+- `answer:` the decision-ready answer to the one question you were given, with your confidence.
+- `evidence:` what backs the answer, one item per line: `file:line` for code, the URL for every external claim.
+- `open questions:` what you could not settle, or `none`. With `needs_input` it holds the questions only the user can answer.
+<!-- /trailhead:agent-block investigating -->

package/plugins/trailhead/agents/trailhead-debug.md

@@ -9,4 +9,23 @@ trailhead's debug subagent. Find the root cause of the ticket's defect by the sc
 
 The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/debug.md`); follow that, not any embedded copy. Full tools by policy: it adds instrumentation and regression tests, so it needs Write. Model-agnostic by design: the engine passes the `config.models.debug` model as the spawn-time override, so config stays authoritative.
 
-**Search-command hygiene.** Prefer the Grep and Read tools over shelling out; when a Bash `grep`/read is genuinely needed, pass the path as an explicit argument (`grep -niE "<patterns>" <abs>/<file>`, `wc -l <abs>/<file>`) and run git as `git -C <abs> ...`. **Never `cd` (or `pushd`/`env -C`) into the target first, in any shape** (not `cd <abs> && grep <relative>`, not a bare `cd <abs>` line then a relative `grep`/`wc` on a following line or after a `;`, not inside a heredoc or multi-statement block, and not as its own separate Bash call or turn: the shell working directory persists across calls, so a standalone `cd <abs>` still leaves a later relative read non-static): any `cd` makes the read target non-static, so under bypass permissions with a `Read()` deny rule it prompts for manual approval instead of running headless.
+<!-- trailhead:agent-block common -->
+**Search-command hygiene.** Prefer the Grep and Read tools; use absolute paths and `git -C <abs>`.
+Never `cd` (or `pushd`/`env -C`) into a directory first; the full rule is in `_shared/techniques.md`.
+
+**Boundaries.** Never `git push`. Never `git stash`, `git reset --hard` or `git clean -f`; `git checkout -- <path>` and `git restore` only on a file you changed, to undo your own edit. Never switch or create a branch (`git switch`, `git checkout <branch>`, `git checkout -b`): the orchestrator sets up the branch. Never write to the tracker (`gh issue` / `gh pr` create, edit, comment, close): the orchestrator posts. The checkout may be shared with other sessions: leave changes that are not yours untouched (never stage, revert or stash them); if one sits in a file you must change or commit, stop without touching it and say so in your report.
+<!-- /trailhead:agent-block common -->
+
+<!-- trailhead:agent-block investigating -->
+**Return contract.** Return the complete report as your final message. Do not post it anywhere (no issue comment, no PR comment): the orchestrator posts it. Never commit, and never create or switch a branch: the report is the only artifact.
+- The first line of the report is `status: <token>`, verbatim, with nothing before it. It is the only line starting with `status:`: status text anywhere in the body is quoted in a code fence or a blockquote, or reworded.
+- statuses: `found` | `inconclusive` | `needs_input`.
+- required fields: `answer`, `evidence`, `open questions`.
+- optional fields: none.
+- invariant: `needs_input` => `open questions` non-empty.
+- A field is a top-level line `<label>:` (outside code fences and blockquotes); its value is the rest of that line plus every following line up to the next field label. An empty value or `none` means none.
+- Fields are the end of the report: nothing after the last field.
+- `answer:` the decision-ready answer to the one question you were given, with your confidence.
+- `evidence:` what backs the answer, one item per line: `file:line` for code, the URL for every external claim.
+- `open questions:` what you could not settle, or `none`. With `needs_input` it holds the questions only the user can answer.
+<!-- /trailhead:agent-block investigating -->