@marcomigozzi/trailhead 0.14.0 → 0.16.0

package/bin/trailhead.js

@@ -243,19 +243,19 @@ function claudePaths(configDir) {
     settings: path.join(configDir, 'settings.json'),
   };
 }
-// The five Bash guard modules. They are shipped, but only require()d by the
+// The six Bash guard modules. They are shipped, but only require()d by the
 // merged trailhead-bash-guards.js (one process per Bash call), never registered
 // on their own. Legacy installs registered each one; the installers strip those.
-const BASH_GUARD_MODULES = ['trailhead-commit-guard.js', 'trailhead-secret-guard.js', 'trailhead-install-guard.js', 'trailhead-search-guard.js', 'trailhead-body-guard.js'];
+const BASH_GUARD_MODULES = ['trailhead-commit-guard.js', 'trailhead-secret-guard.js', 'trailhead-install-guard.js', 'trailhead-search-guard.js', 'trailhead-body-guard.js', 'trailhead-labels-guard.js'];
 // Every hook script copied into the hooks dir (shipped runtime files).
 const HOOK_FILES = [...BASH_GUARD_MODULES, 'trailhead-bash-guards.js', 'trailhead-issue-injection-scanner.js', 'trailhead-secret-read-guard.js', 'trailhead-mockup-link-guard.js', 'trailhead-mockup-link-stop.js', 'trailhead-check-update.js'];
 // The registered entrypoints: the shipped files that must appear in
 // settings.json / hooks.json (everything but the require()d guard modules).
 const ENTRYPOINT_FILES = HOOK_FILES.filter((f) => !BASH_GUARD_MODULES.includes(f));
 // Runtime libs the hook scripts require (trailhead-commit-guard.js does
-// require('./lib/commit-message-check.js'); trailhead-search-guard.js and
-// trailhead-secret-read-guard.js both do require('./lib/shell-scan.js'), #135
-// follow-up; trailhead-body-guard.js and trailhead-secret-guard.js both do
+// require('./lib/commit-message-check.js'); several guards (grep `lib/shell-scan`:
+// search, secret-read, secret, install, lib/unmodelled.js) do
+// require('./lib/shell-scan.js'), #135 follow-up; trailhead-body-guard.js and trailhead-secret-guard.js both do
 // require('./lib/gh-subcommand.js'), #153 follow-up; trailhead-secret-guard.js
 // also does require('./lib/body-sources.js'), #210; trailhead-check-update.js
 // does require('./lib/model-defaults-review.js'), which in turn reads the
@@ -436,7 +436,7 @@ function installClaude(configDir, { useSymlink }) {
 
   const s = readJSON(P.settings);
   // Migration: an earlier install registered each Bash guard on its own; the
-  // merged entrypoint below replaces all five.
+  // merged entrypoint below replaces all six.
   stripLegacyBashGuards(s);
   const added = [
     addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-bash-guards.js')),

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',
@@ -654,12 +757,12 @@ ok('source: both Pending-UAT guard lines reference the drive-mode ask', pendingU
 // auto.md mentions the ask, AND (plan-review addition) a single localized span
 // states its outcomes TOGETHER: takes it without the confirm gate, picks
 // AI-driven when any step is agent-performable, never fakes a human-only step,
-// and sets the ticket aside listing them in the run-end summary.
+// and routes the human-only steps to a follow-up opened before the parent closes (#281).
 const autoSourcePath = path.join(sourceSkillsDir, 'trailhead-work', 'references', 'auto.md');
 const autoSource = fs.readFileSync(autoSourcePath, 'utf8');
 ok('source: auto.md mentions the drive-mode ask', autoSource.includes('drive-mode ask'));
 ok('source: auto.md states the drive-mode-ask outcomes together (grouped, not scattered)',
-  /drive-mode ask[\s\S]{0,120}without the confirm gate[\s\S]{0,300}AI-driven[\s\S]{0,200}agent-performable[\s\S]{0,300}never fake[\s\S]{0,300}run-end summary/.test(autoSource));
+  /drive-mode ask[\s\S]{0,120}without the confirm gate[\s\S]{0,300}AI-driven[\s\S]{0,200}agent-performable[\s\S]{0,300}never fakes[\s\S]{0,1500}follow-up/.test(autoSource));
 
 // choices.md carries the call-site row for the drive-mode ask.
 const choicesSourcePath = path.join(sourceSkillsDir, '_shared', 'choices.md');
@@ -713,13 +816,95 @@ ok('source: configuration-reference.md acceptance.browser clause does NOT make t
 ok('source: configuration-reference.md acceptance.browser clause states the drive-mode ask always comes first',
   /\*\*acceptance\.browser\.\*\*[\s\S]{0,200}drive-mode ask[\s\S]{0,120}always comes first/.test(configReferenceSource));
 
-// The run-end summary's enumerated set-aside category list is missing the new
-// human-only-UAT-steps class (added by #178); it must be listed there too,
-// matching the wording already used for it at line 29 ("human-only steps").
+// Human-only UAT steps are no longer a set-aside reason (#281): the run-end summary
+// lists the UAT follow-ups opened this run instead.
 const runEndSummarySection = extractSection(autoSource, '## Run-end summary');
 ok('source: auto.md Run-end summary section exists', runEndSummarySection.length > 0);
-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));
+ok('source: auto.md Run-end summary "what remains" lists the UAT follow-ups opened this run',
+  /what remains[\s\S]{0,900}UAT follow-ups opened this run/.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',
+  /the parent ticket resolves; `\/trailhead:auto` never picks skip/.test(readmeSource) && /the parent ticket resolves; `\/trailhead:auto` never picks skip/.test(siteAcceptanceSource) && /il ticket genitore si risolve; `\/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');
@@ -727,10 +912,10 @@ 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 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`))) &&
+  (g.hooks || []).some((h) => h.command.includes('trailhead-bash-guards.js') && h.command.endsWith(' --guards=commit,secret,install,body,labels'))));
+ok('codex: hooks.json registers none of the per-guard scripts on their own', !/trailhead-(commit|secret|install|search|body|labels)-guard\.js/.test(codexHooksJsonStr));
+ok('codex: the six guard modules the merged hook requires are still shipped (no search)',
+  ['commit', 'secret', 'install', 'body', 'labels'].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'))));
@@ -851,6 +1036,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 });
@@ -884,7 +1088,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-bash-guards.js') && !/trailhead-(commit|secret|install|search|body)-guard\.js/.test(str) &&
+  return !str.includes('trailhead-bash-guards.js') && !/trailhead-(commit|secret|install|search|body|labels)-guard\.js/.test(str) &&
     !str.includes('trailhead-issue-injection-scanner.js') && !str.includes('trailhead-check-update.js');
 })());
 
@@ -932,6 +1136,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 +1154,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.
@@ -1083,12 +1304,12 @@ ok('claude: settings.json exists', fs.existsSync(settingsPath));
 const settingsContent = fs.readFileSync(settingsPath, 'utf8');
 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));
+  !/trailhead-(commit|secret|install|search|body|labels)-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']
+ok('claude: hooks/trailhead-bash-guards.js and its six modules exist', ['bash-guards', 'commit-guard', 'secret-guard', 'install-guard', 'search-guard', 'body-guard', 'labels-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.
@@ -1251,6 +1472,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',
@@ -1466,7 +1690,7 @@ const bashGuardCommands = (registry) => (registry.hooks.PreToolUse || [])
   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'));
+    cmds[0].endsWith(' --guards=commit,secret,install,body,labels'));
   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);
@@ -1841,6 +2065,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-one labels including trailhead:paused, trailhead:uat and trailhead:needs-you',
+  /all twenty-one:/.test(firstUseLine) && firstUseLine.includes('`trailhead:paused`') && firstUseLine.includes('`trailhead:uat`') && firstUseLine.includes('`trailhead:needs-you`'));
+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 });
 }