@marcomigozzi/trailhead 0.14.0 → 0.16.0

package/bin/auto-review-rounds-docs.test.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Docs test for #284: the autonomous run asks the external review rounds at start-up and
+// parks a ticket whose plan review does not converge. Plain asserts, no framework.
+// Run: node bin/auto-review-rounds-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const plugin = path.resolve(__dirname, '..', 'plugins', 'trailhead');
+const read = (rel) => fs.readFileSync(path.join(plugin, rel), 'utf8');
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const auto = read('skills/trailhead-work/references/auto.md');
+const review = read('skills/_shared/techniques/plan-review.md');
+const config = read('skills/_shared/configuration-reference.md');
+
+ok('auto.md has the External review rounds bullet', auto.includes('**External review rounds.**'));
+ok('auto.md names the ask call', auto.includes('trailhead-plan-review-rounds.js ask'));
+ok('auto.md: skip when plan review is off or no independent reviewer CLI is installed', /`skip`[^.]*plan review off[^.]*no independent reviewer CLI/.test(auto));
+ok('auto.md: one AskUserQuestion with the helper options, at most four, config Recommended first', /one `AskUserQuestion`[^.]*`options`[^.]*at most four[^.]*Recommended/.test(auto));
+ok('auto.md names the five choices', /as in config, 1, 2, 3, or until convergence/.test(auto));
+ok('auto.md: until convergence stops on no progress, hard ceiling 5', /no progress[^.]*hard ceiling 5/.test(auto));
+ok('auto.md: numbered list of all five without a structured question tool', /full five as a numbered list/.test(auto));
+ok('auto.md: an ask error hands back before any claim', /`error`[^.]*reports it and hands back before any claim/.test(auto));
+ok('auto.md: the ask is the human\'s, no delegate, also under <n>', /no delegate[^.]*before any claim/.test(auto) && /also under `\/trailhead:auto <n>`/.test(auto));
+ok('auto.md: the choice holds for every build ticket, each slot included', /holds for every `build` ticket of the run[^.]*slot/.test(auto));
+ok('auto.md: the wired-separately aside is gone', !/wired separately/.test(auto));
+ok('auto.md: names the parking trigger statuses', /`exhausted`[^.]*`no-progress`[^.]*`ceiling`/.test(auto));
+ok('auto.md: parks after PLAN and PLAN-REVIEW are posted, quoting each concern\'s full text', /after the `PLAN` and `PLAN-REVIEW` comments are posted/.test(auto) && /full `text`[^.]*`surviving`[^.]*never just (its|the) key/.test(auto));
+ok('auto.md: names the round call', auto.includes('trailhead-plan-review-rounds.js round'));
+
+ok('auto.md: the ask helper warnings are printed in chat before the ask or skip', /non-empty `warnings`[\s\S]{0,200}printed in chat first, before the ask or the skip/.test(auto));
+ok('plan-review.md: rounds come from config or the run start-up choice', /`config\.plan_review\.rounds`[^.]*autonomous run[^.]*start-up choice/.test(review));
+ok('plan-review.md: calls the round helper and follows its decision', review.includes('trailhead-plan-review-rounds.js round') && /follows its decision/.test(review));
+ok('plan-review.md: under an autonomous run the checkpoint is not posed, the ticket is parked', /autonomous run[^.]*checkpoint is not posed[\s\S]{0,400}trailhead-needs-you\.js park/.test(review));
+ok('plan-review.md: the park reason lists the surviving blocking concerns', /reason listing the surviving blocking concerns/.test(review));
+ok('plan-review.md: interactive behaviour unchanged', /interactive[^.]*unchanged/i.test(review));
+
+ok('configuration-reference.md: plan_review.rounds notes the run ask override', /plan_review\.rounds[^\n]*autonomous run asks at start[^\n]*overrides the key for that run/.test(config));
+
+for (const [name, text] of [['auto.md', auto], ['plan-review.md', review], ['configuration-reference.md', config]]) {
+  ok(`${name}: no em-dash`, !text.includes(String.fromCharCode(0x2014)));
+}
+console.log(`auto-review-rounds-docs.test.js: ${passed} checks passed`);

package/bin/auto-run-docs.test.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Docs test for #295: the autonomous run persists its start-up choices and lists in
+// .trailhead/auto-run.json so it survives a compaction. Plain asserts, no framework.
+// Run: node bin/auto-run-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const plugin = path.resolve(__dirname, '..', 'plugins', 'trailhead');
+const auto = fs.readFileSync(path.join(plugin, 'skills/trailhead-work/references/auto.md'), 'utf8');
+const gitignore = fs.readFileSync(path.resolve(__dirname, '..', '.gitignore'), 'utf8');
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+ok('auto.md: read runs at engagement, before the asks', /trailhead-auto-run\.js read --repo <main-checkout>[^\n]*before (any|the) ask/i.test(auto));
+ok('auto.md: found with sameSession true is reused without asking and announced', /`sameSession: true`[^\n]*reuse it without asking/.test(auto) && /announced in one chat line naming the reused scope, slots and review/.test(auto));
+ok('auto.md: another session\'s record asks once to resume or start fresh', /`sameSession: false`[^\n]*run still active elsewhere[^\n]*ask once/.test(auto) && /no delegate option/.test(auto) && /replaces the three asks/.test(auto));
+ok('auto.md: resume reloads the skip and unmerged lists', /reload the record's skip and unmerged lists/.test(auto));
+ok('auto.md: an explicit <n> that differs starts fresh with start --replace', /explicit `\/trailhead:auto <n>`[^\n]*differs[^\n]*starts a fresh run[^\n]*start --replace/.test(auto));
+ok('auto.md: corrupt is reported then start --replace', /`corrupt`[^\n]*start --replace[^\n]*plain `start` would answer `exists`/.test(auto));
+ok('auto.md: start runs after the last ask and before anything is claimed', /trailhead-auto-run\.js start --repo <main-checkout>[^\n]*--scope[^\n]*--slots[^\n]*--review/.test(auto) && /right after the last start-up ask and before anything is claimed/.test(auto));
+ok('auto.md: the record is gitignored', auto.includes('.trailhead/auto-run.json') && /\.gitignore/.test(auto) && /^\.trailhead\/auto-run\.json$/m.test(gitignore));
+ok('auto.md: every skipped outcome is reported and never blocks', /Any `skipped` result[^\n]*one chat line[^\n]*the run continues/.test(auto) && /skipped `read` is treated as `absent`/.test(auto) && /safety net, not a gate/.test(auto));
+ok('auto.md: skip runs on each skip-list add', /trailhead-auto-run\.js skip --repo <main-checkout> --ticket <n>/.test(auto) && /every time a ticket joins the run's skip list/i.test(auto));
+ok('auto.md: unmerged is recorded right after the abort, before the tracker call', /trailhead-auto-run\.js unmerged --repo <main-checkout> --ticket <n> --branch trailhead\/t<n>[^\n]*--file/.test(auto) && /before any tracker call/.test(auto));
+ok('auto.md: unmerged again with --merge-ticket after the add succeeds', /--merge-ticket <n>/.test(auto) && /after the merge-ticket `add` succeeds/.test(auto));
+ok('auto.md: a crash or failed add still leaves the branch on the persisted list', /still leaves the branch on the persisted unmerged list/.test(auto));
+const parallel = auto.slice(auto.indexOf('## Parallel slots'), auto.indexOf('## Parking a ticket'));
+const outside = auto.replace(parallel, '');
+ok('auto.md: a general compaction rule sits outside Parallel slots and holds whatever the slot count and sameSession', /After a context compaction mid-run[^\n]*whatever the slot count[^\n]*trailhead-auto-run\.js read --repo <main-checkout>[^\n]*whatever `sameSession` says[^\n]*without asking/.test(outside) && /scope, slots, review choice, skip and unmerged lists/.test(outside));
+ok('auto.md: the orchestrator knows it is mid-run from its own context', /mid-run from its own context/.test(outside));
+ok('auto.md: the sameSession ask applies only at engagement', /`sameSession` ask applies only at engagement/.test(auto) && /fresh `\/trailhead:auto` invocation/.test(auto));
+ok('auto.md: no session id host note (Codex)', /`sameSession` is always false on a host with no session id \(Codex\)/.test(auto) && /re-invocation after a crash always gets the resume-or-fresh ask/.test(auto) && /mid-run compaction never does/.test(auto));
+ok('auto.md: the slot table bullet points at the general rule', /slot table from `trailhead-auto-slot\.js list`[^\n]*general compaction rule/.test(parallel) && !/trailhead-auto-run\.js read/.test(parallel));
+ok('auto.md: run end unites the in-memory lists with the record', /in-memory skip and unmerged lists[^\n]*united with the record's/.test(auto));
+ok('auto.md: run end clears the record, then resets the work states', /trailhead-auto-run\.js clear --repo <main-checkout>[^\n]*then[^\n]*--auto false/.test(auto) && /Clearing first means a crash between the two/.test(auto));
+ok('auto.md: a host interrupt writes nothing, so Esc leaves the crash signature', !/graceful interrupt clears it too/.test(auto) && !/a graceful interrupt clears the record/.test(auto) && /same on disk as a crash/.test(auto) && /signature of both an Esc and a crash/.test(auto));
+ok('auto.md: after Esc the same session reuses the record, a new session is asked again', /Esc[^\n]*reuses the record/.test(auto) && /new session[^\n]*(asked again|resume-or-fresh)/.test(auto));
+ok('auto.md: step 2 writes the missing PAUSED checkpoint and label before resuming a crash-signature ticket', /Reconstruct the missing checkpoint/.test(auto) && /reconstructed at resume/.test(auto) && /adds `trailhead:paused` \(after the comment, so a failed comment never leaves a label without a checkpoint\)/.test(auto) && /resumes the ticket through the `resume` engine, which drops the label/.test(auto) && /no second checkpoint/.test(auto));
+ok('auto.md: no run-end summary at a host interrupt, the resumed run covers it', /not emitted at the interrupt/.test(auto) && /resumed run's own (run-end )?summary/.test(auto));
+ok('auto.md: crash signature and idempotence are stated on the latest checkpoint', /whose latest checkpoint is not a `PAUSED` comment/.test(auto) && /skipped only when the latest checkpoint is already a `PAUSED` comment or the label is present/.test(auto));
+ok('auto.md: a slot ticket at the resolve step is exempt from reconstruction', /work state step is `resolve`[^\n]*exempt from (the )?reconstruction/.test(auto));
+ok('auto.md: reconstruction happens when the ticket is resumed, not for a waiting extra', /Reconstruction happens when the ticket is actually resumed[^\n]*untouched/.test(auto));
+const docs = {
+  'README.md': 'README.md',
+  'README.it.md': 'README.it.md',
+  'workflow.md': 'site/src/content/docs/docs/workflow.md',
+  'commands/work.md': 'site/src/content/docs/docs/commands/work.md',
+};
+const root = path.resolve(__dirname, '..');
+for (const [name, rel] of Object.entries(docs)) {
+  const t = fs.readFileSync(path.join(root, rel), 'utf8');
+  const it = name === 'README.it.md';
+  ok(`${name}: no interrupt-time PAUSED checkpoint promise`, !/(Stop\/Esc|Esc or Stop|Esc)[^\n]*(keeps its claim and gets|keeps its claim with|mantiene il claim e riceve)[^\n]*`PAUSED`/.test(t) && !/gets a `PAUSED` checkpoint naming/.test(t));
+  ok(`${name}: Esc writes nothing and the next auto writes the missing PAUSED checkpoint`, it
+    ? /Esc[^\n]*non scrive nulla[^\n]*stessa traccia di un crash[^\n]*`\/trailhead:auto`[^\n]*checkpoint `PAUSED` mancante[^\n]*workspace e branch/.test(t) && /stessa sessione[^\n]*riusa[^\n]*nuova sessione[^\n]*chiede di nuovo/.test(t)
+    : /Esc[^\n]*writes nothing[^\n]*same trace as a crash[^\n]*`\/trailhead:auto`[^\n]*missing `PAUSED` checkpoint[^\n]*workspace and branch/.test(t) && /same session[^\n]*reuses[^\n]*new session[^\n]*asks again/.test(t));
+}
+ok('auto.md: no em-dash', !auto.includes(String.fromCharCode(0x2014)));
+console.log(`auto-run-docs.test.js: ${passed} checks passed`);

package/bin/auto-scope-docs.test.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// Docs test for #280: auto.md documents the run scope (asked at start, `<n>` skips),
+// the queue order rule, the helper, the helper-error stop, and the report split.
+// Run: node auto-scope-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const plugin = path.join(__dirname, '..', 'plugins', 'trailhead');
+const read = (rel) => fs.readFileSync(path.join(plugin, rel), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const auto = read('skills/trailhead-work/references/auto.md');
+for (const needle of [
+  '**Pick the run scope.**', 'trailhead-auto-queue.js', "trailhead-auto-queue.js scopes", '`AskUserQuestion`', 'one map, the whiteboard, or everything',
+  '`/trailhead:auto <n>`', 'without asking', 'no delegate option', 'before anything is claimed',
+  'trailhead-auto-queue.js queue --scope', '--skip', '`next`', 'whiteboard last', 'ascending map number', 'oldest workable ticket first',
+  'A helper error stops the run', '`drift`', '`resume`', '--map none',
+  'each touched map gets a comment with **only its own part**', 'the whiteboard part stays in chat only', 'a map the run never touched gets no comment',
+]) ok(`auto.md names: ${needle}`, auto.includes(needle));
+
+for (const rel of ['skills/trailhead-work/references/auto.md', 'skills/trailhead-work/SKILL.md', 'commands/auto.md', 'templates/trailhead-auto-queue.js']) {
+  ok(`${rel} has no em-dash`, !read(rel).includes('—'));
+}
+for (const rel of ['skills/trailhead-work/SKILL.md', 'commands/auto.md']) {
+  ok(`${rel} describes a chosen scope`, /run scope/.test(read(rel)));
+  ok(`${rel} no longer says "the map's frontier"`, !read(rel).includes("the map's frontier"));
+}
+ok('commands/auto.md keeps the [map] hint', read('commands/auto.md').includes('argument-hint: "[map]"'));
+
+console.log(`auto-scope-docs.test.js: ${passed} checks passed`);

package/bin/auto-slots-docs.test.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Docs test for #283: the autonomous run asks for parallel slots and works each slot
+// ticket in its own worktree. Plain asserts, no framework. Run: node bin/auto-slots-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const plugin = path.resolve(__dirname, '..', 'plugins', 'trailhead');
+const read = (rel) => fs.readFileSync(path.join(plugin, rel), 'utf8');
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const auto = read('skills/trailhead-work/references/auto.md');
+const work = read('skills/trailhead-work/SKILL.md');
+const team = read('skills/_shared/teamwork.md');
+
+ok('auto.md asks the slot count, 1 to 4, proposed 2', /Parallel slots: 1, 2, 3 or 4/.test(auto) && /\*\*2 proposed\*\*/.test(auto) && auto.includes('AskUserQuestion'));
+ok('auto.md asks the slot count even with <n>', /`\/trailhead:auto <n>` skips only the scope ask: it \*\*still asks the slot count\*\*/.test(auto));
+ok('auto.md slot ask is the human\'s, no delegate', /there is no delegate option, and it is asked before anything is claimed/.test(auto));
+ok('auto.md names the open helper call with --base', auto.includes('trailhead-auto-slot.js open --repo <main-checkout> --ticket <n> --base <sha>'));
+ok('auto.md names the list helper call', auto.includes('trailhead-auto-slot.js list --repo <main-checkout>'));
+ok('auto.md handles clone-required', auto.includes('clone-required') && auto.includes('checkout -b trailhead/t<n> <base>'));
+ok('auto.md writes sessionless slot work state', auto.includes('env -u CLAUDE_CODE_SESSION_ID node <templates>/trailhead-work-state.js set --repo <workspace>'));
+ok('auto.md resumes a ticket in its own workspace', /resumed \*\*in that workspace\*\*, whatever the slot count/.test(auto) && auto.includes('left alone'));
+ok('auto.md: a slot never writes the active-map marker', /A slot never writes the `\.trailhead\/active-map` marker/.test(auto) && /every map-scoped call[^.]*names the map explicitly/.test(auto));
+ok('auto.md: isolation override above 1 slot, none and auto included', /Above 1 slot[^.]*a worktree whatever `isolation:` says\*\* \(`none` and `auto` included\)/.test(auto));
+ok('auto.md: background dispatch, nothing inline', auto.includes('background subagent') && auto.includes('nothing runs inline'));
+ok('auto.md: in-flight tickets join --skip when filling a slot', /in-flight ticket/.test(auto) && /--skip <csv>` with the run's skip list \*\*plus every in-flight ticket\*\*/.test(auto));
+ok('auto.md: integration held under git: pr and for a clone slot, branch and workspace kept', /Integration stays held under `git: pr`, and for a clone slot/.test(auto) && /parked needs-you for integration/.test(auto) && /\*\*kept\*\*/.test(auto));
+ok('auto.md: no interrupt-time PAUSED for slot tickets, resume reconstructs it per workspace, run end per workspace', !/every in-flight slot ticket\*\* gets its `PAUSED` checkpoint/.test(auto) && /naming the slot workspace path and branch/.test(auto) && auto.includes('each remaining workspace'));
+
+ok('auto.md: every set on a slot workspace is sessionless', /every `set` on a slot workspace[^.]*`env -u CLAUDE_CODE_SESSION_ID`/.test(auto));
+ok('auto.md: the run-end reset on a workspace is sessionless too', /env -u CLAUDE_CODE_SESSION_ID node <templates>\/trailhead-work-state\.js set --repo <workspace> --auto false/.test(auto));
+ok('auto.md: open statuses explained (reentered clone as is, stale worktree parks needs-you)', /`reentered` clone is used as is/.test(auto) && /stale worktree[\s\S]{0,400}park it needs-you/.test(auto) && auto.includes('git worktree prune'));
+
+for (const [name, text] of [['teamwork.md', team], ['SKILL.md', work]]) {
+  ok(`${name}: no longer says the run is always the current checkout`, !/sequential work, no concurrency|works tickets sequentially/.test(text));
+  ok(`${name}: names the worktree per ticket above one slot`, /current checkout with one parallel slot and to a worktree per ticket above one/.test(text));
+}
+ok('teamwork.md worktree bullet names the slot helper', team.includes('through the `trailhead-auto-slot.js` helper'));
+
+for (const [name, text] of [['auto.md', auto], ['SKILL.md', work], ['teamwork.md', team]]) {
+  ok(`${name}: no em-dash`, !text.includes(String.fromCharCode(0x2014)));
+}
+console.log(`auto-slots-docs.test.js: ${passed} checks passed`);

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

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Docs test for #281: an autonomous run resolves a ticket through a UAT follow-up
+// (found first, reused on resume), writes every record when it arises, and documents
+// the hard-stop guarantee. Run: node auto-uat-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const plugin = path.join(__dirname, '..', 'plugins', 'trailhead');
+const read = (rel) => fs.readFileSync(path.join(plugin, rel), 'utf8');
+
+const DASH = String.fromCharCode(0x2014);
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const AUTO = 'skills/trailhead-work/references/auto.md';
+const ACCEPT = 'skills/_shared/techniques/acceptance-testing.md';
+const ENGINES = 'skills/trailhead-work/references/ticket-engines.md';
+const SUBSTRATE = 'skills/_shared/substrate-commands.md';
+
+const auto = read(AUTO);
+for (const needle of [
+  'trailhead-uat-followup.js find', '## Records as it goes', 'never the only record', 'UAT of:', 'trailhead:uat',
+  'A helper error is not a "none found"', 'Only an open follow-up is reused', 'closed ones never count',
+  'a crash in the instant between the claim and the work-state write', 'leftover work state', 'whose work state has `auto: true`', 'already names the same action', 'its own checklist is already the record', 'trailhead-work-state.js',
+  'loses nothing that has arisen', 'UAT follow-ups opened this run',
+  'each touched map gets a comment with **only its own part**', 'the whiteboard part stays in chat only', 'a map the run never touched gets no comment',
+]) ok(`auto.md names: ${needle}`, auto.includes(needle));
+ok('auto.md no longer sets a ticket aside for a human-only UAT step', !auto.includes('leaves that step incomplete and sets the ticket aside'));
+ok('auto.md names the needs-you label (#282)', auto.includes('trailhead:needs-you'));
+
+const accept = read(ACCEPT);
+for (const needle of ['trailhead-uat-followup.js find', 'autonomous run', 'auto.md', 'opens no duplicate'])
+  ok(`acceptance-testing.md names: ${needle}`, accept.includes(needle));
+
+const engines = read(ENGINES);
+ok('ticket-engines.md names the autonomous exception in build and bug Resolve', engines.split('Under an autonomous run the guard takes option (b) itself').length - 1 >= 2);
+
+const substrate = read(SUBSTRATE);
+for (const needle of ['trailhead-uat-followup.js find --parent <n> --repo <owner/name>', '"reuse"', 'paginated GraphQL `repository.issues` query', 'lagging search index'])
+  ok(`substrate-commands.md names: ${needle}`, substrate.includes(needle));
+
+for (const rel of [AUTO, ACCEPT, ENGINES, SUBSTRATE, 'templates/trailhead-uat-followup.js', 'hooks/lib/uat-followup.test.js'])
+  ok(`${rel} has no em-dash`, !read(rel).includes(DASH));
+ok('this test file has no em-dash', !fs.readFileSync(__filename, 'utf8').includes(DASH));
+
+console.log(`auto-uat-docs.test.js: ${passed} checks passed`);

package/bin/base-preflight-docs.test.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// Docs test for #243: the skill prose wires the stale-base preflight into UAT and
+// integration, and documents the preflight.checks config key.
+// Run: node base-preflight-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-base-preflight.js';
+// file -> strings it must carry
+const EXPECT = {
+  '_shared/teamwork.md': [
+    '**Stale-base preflight.**', HELPER, '--config-root', 'preflight -> sync -> checks -> tests -> Code review -> goal check -> UAT', 'preflight -> sync -> checks -> tests -> integration', 're-run the Code review on it before integrating', 'start of Verify',
+    '`git: pr` without isolation', 'immediately before the push and PR',
+    '`current`', '`synced`', '`conflict`', '`dirty`', '`unverified`', '`trunk-diverged`', '`sync-failed`', 'Fail closed',
+    'right before the trunk push', 'integration target', 'non-fast-forward', 'testsRequired', 'preflight.checks',
+  ],
+  '_shared/configuration-reference.md': ['`preflight.checks`', '**Preflight checks.**', 'migration', 'uniq -d'],
+  '_shared/techniques/acceptance-testing.md': ['Stale-base preflight comes first', HELPER, 'already ran at the start of Verify'],
+  'trailhead-work/references/auto.md': ['stale-base preflight never auto-resolves', '`conflict`'],
+};
+for (const [rel, needles] of Object.entries(EXPECT)) {
+  const text = read(rel);
+  for (const needle of needles) ok(`${rel} names: ${needle}`, text.includes(needle));
+}
+
+// Each engine call site names the preflight.
+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);
+const bugResolve = step('5. **Resolve**', bugVerify + 1);
+for (const [name, idx] of [['build Verify', buildVerify], ['build Resolve', buildResolve], ['bug Verify', bugVerify], ['bug Resolve', bugResolve]]) {
+  ok(`${name} step found`, idx >= 0);
+  ok(`${name} names the stale-base preflight`, lines[idx].includes('Stale-base preflight'));
+}
+ok('build/bug Verify start with the preflight, before the tests and Code review',
+  [buildVerify, bugVerify].every((i) => {
+    const l = lines[i];
+    const p = l.indexOf('Stale-base preflight');
+    return p >= 0 && p < l.indexOf('**Code review**') && p < l.indexOf('**Goal-backward verification**') && p < l.indexOf('**Acceptance testing**');
+  }));
+ok('Verify runs the tests after the sync, before the Code review',
+  [buildVerify, bugVerify].every((i) => lines[i].indexOf('then re-run the tests') > 0 && lines[i].indexOf('then re-run the tests') < lines[i].indexOf('**Code review**')));
+ok('Resolve names git: pr without isolation',
+  [buildResolve, bugResolve].every((i) => lines[i].includes('`git: pr` without isolation: on the ticket branch, immediately before the push and PR')));
+ok('Resolve runs it before the Pending-UAT guard',
+  [buildResolve, bugResolve].every((i) => lines[i].indexOf('Stale-base preflight') < lines[i].indexOf('Pending-UAT guard')));
+ok('Pending-UAT option (a) runs the preflight first',
+  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 starts with the preflight', engines.includes('starting with the stale-base preflight'));
+
+for (const rel of ['_shared/teamwork.md', '_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(`base-preflight-docs.test.js: ${passed} checks passed`);

package/bin/execute-split-docs.test.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// Pins the Execute/Fix split (#251): the executor-side text lives in
+// trailhead-work/references/executor-brief.md (the one text injected at spawn),
+// while the Execute (build) and Fix (bug) steps of ticket-engines.md keep only
+// the orchestrator moves. Run: node execute-split-docs.test.js. No framework.
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const plugin = path.join(__dirname, '..', 'plugins', 'trailhead');
+const refs = path.join(plugin, 'skills', 'trailhead-work', 'references');
+const briefPath = path.join(refs, 'executor-brief.md');
+const exists = fs.existsSync(briefPath);
+ok('executor-brief.md exists', exists);
+const brief = fs.readFileSync(briefPath, 'utf8');
+const lb = brief.toLowerCase();
+const engines = fs.readFileSync(path.join(refs, 'ticket-engines.md'), 'utf8');
+const lines = engines.split('\n');
+
+const block = (startPrefix, from = 0) => {
+  const s = lines.findIndex((l, i) => i >= from && l.startsWith(startPrefix));
+  if (s === -1) return '';
+  const e = lines.findIndex((l, i) => i > s && l.startsWith('4. **Verify**'));
+  return lines.slice(s, e === -1 ? undefined : e).join('\n');
+};
+const execute = block('3. **Execute**');
+const fix = block('3. **Fix**');
+ok('the build Execute block was found', execute.length > 500);
+ok('the bug Fix block was found', fix.length > 500);
+
+// --- the brief: what the executor does ---------------------------------------------------
+const has = (src, ...needles) => needles.every((n) => src.includes(n));
+ok('brief: atomic conventional commits with a Refs trailer', has(lb, 'atomic', 'conventional', 'refs: #<n>'));
+ok('brief: a fix takes the confirmed DIAGNOSIS as its spec', brief.includes('the confirmed `DIAGNOSIS` (bug)'));
+ok('brief: a resumed spawn continues from the commits already made', has(brief, 'Resumed spawn', 'never redo or revert'));
+ok('brief: stop and report finishes the unaffected work first', brief.includes('finish the work it does not affect'));
+ok('Execute and Fix: inline, the session applies the brief and asks the user directly',
+  execute.includes('asking the user directly') && fix.includes('asking the user directly'));
+ok('brief: one commit = one verifiable step', brief.includes('One commit = one verifiable step'));
+ok('brief: TDD per the config.tdd value passed', has(brief, 'config.tdd', '`seams`', '`on`', '`off`'));
+ok('brief: a fix gets a test that fails before and passes after', lb.includes('fails before and passes after'));
+ok('brief: dependency vetting criteria', has(lb, 'typosquat', 'age', 'downloads', 'repository metadata'));
+ok('brief: the sentinel re-run of the exact command', has(brief, 'TRAILHEAD_VERIFIED_INSTALL=1', 'exact'));
+ok('brief: sentinel only when clean or passed as user-approved', lb.includes('user-approved') && lb.includes('clean'));
+ok('brief: a suspicious package: stop and report, never install, never set the sentinel',
+  lb.includes('suspicious') && lb.includes('stop and report') && lb.includes('never install') && lb.includes('never set'));
+ok('brief: 100% fidelity to a passed approved mockup', brief.includes('100% fidelity') && lb.includes('approved mockup'));
+ok('brief: infeasible element: stop and report, never silently deviate',
+  lb.includes('infeasible') && lb.includes('never silently deviate'));
+ok('brief: returns the enumerated fidelity list in its report', brief.includes('enumerated fidelity list'));
+ok('brief: new scope is reported, not worked', lb.includes('scope') && lb.includes('reported, not worked'));
+const report = brief.slice(brief.indexOf('## Report'));
+ok('brief: has a Report section', brief.includes('## Report'));
+ok('brief: Report names flagged packages with exact install command and evidence',
+  has(lb.slice(lb.indexOf('## report')), 'flagged package', 'exact install command', 'evidence'));
+ok('brief: Report names the fidelity list as element/state -> reproduced or infeasible with why',
+  has(report, 'element/state', 'reproduced or infeasible', 'why'));
+ok('brief: Report names surfaced scope', report.toLowerCase().includes('surfaced scope'));
+ok('brief: the report takes the shape of the implementing Return contract',
+  has(report, 'implementing `Return contract`', 'status: done | partial | blocked', '`commits:`', '`blockers:`', '`fidelity:`', '`surfaced scope:`'));
+ok('brief: no longer defers the report shape to a later ticket', !report.includes('#249'));
+
+// --- the brief carries none of the orchestrator-only moves ---------------------------------
+ok('brief: no AskUserQuestion', !brief.includes('AskUserQuestion'));
+ok('brief: no "ask the user"', !lb.includes('ask the user'));
+ok('brief: no config.design', !brief.includes('config.design'));
+ok('brief: no Prototype technique instruction', !lb.includes('prototype technique'));
+ok('brief: no gh issue / gh pr tracker write', !/gh (issue|pr)\b/.test(lb));
+ok('brief: no branch or PR creation', !/(create|creates|creating|open|opens) (the |a )?(branch|pr\b|pull request)/.test(lb));
+ok('brief: no em-dash', !brief.includes('—'));
+
+// --- the build Execute block: the orchestrator part --------------------------------------------
+const lx = execute.toLowerCase();
+ok('Execute: Prototype FIRST', execute.includes('Prototype technique') && execute.includes('FIRST'));
+ok('Execute: config.design routing, never a hosted mode to a local disk mockup',
+  has(execute, 'config.design', 'never shortcut a hosted mode to a local disk mockup'));
+ok('Execute: config.design.approval gate', has(execute, 'config.design.approval', '`explicit`', '`auto`'));
+ok('Execute: branch before the spawn and PR after under git: pr',
+  has(execute, 'git: pr', 'the orchestrator creates the branch before the spawn and opens the PR'));
+ok('Execute: worktree under isolation: worktree', has(execute, 'isolation: worktree', 'git worktree'));
+ok('Execute: posts the fidelity list as a ticket comment',
+  has(execute, 'returns the enumerated fidelity list in its report', 'the orchestrator posts it as a ticket comment'));
+ok('Execute: an infeasible element is raised with the user and settled',
+  lx.includes('infeasible') && lx.includes('revise and re-approve the mockup') && lx.includes('accepts a named deviation'));
+ok('Execute: re-spawns with the settled mockup and accepted deviations',
+  lx.includes('re-spawn') && lx.includes('accepted deviations'));
+ok('Execute: block-and-ask on a flagged package', lx.includes('block-and-ask') && lx.includes('flagged package'));
+ok('Execute: only on an explicit yes re-spawn with the package as user-approved',
+  lx.includes('explicit yes') && lx.includes('user-approved'));
+ok('Execute: on a no the package is not installed and the plan is revisited',
+  lx.includes('not installed') && lx.includes('revisited with the user'));
+ok('Execute: captures surfaced scope', lx.includes('surfaced scope') && lx.includes('captured'));
+ok('Execute: dispatches trailhead-executor on config.models.execute',
+  has(execute, '`trailhead-executor`', 'config.models.execute'));
+ok('Execute: the brief is the only protocol text', has(execute, 'executor-brief.md', 'only protocol text'));
+ok('Execute: lists the runtime inputs',
+  has(lx, 'ticket number', 'plan', 'base sha', 'config.tdd', 'mockup link', 'accepted mockup deviations'));
+ok('Execute: inline when the model is unset or equals the session model', lx.includes('inline') && lx.includes('session'));
+
+// --- the bug Fix block: self-contained ------------------------------------------------------------
+const lf = fix.toLowerCase();
+ok('Fix: dispatches trailhead-fix on config.models.execute with the brief as the only protocol text',
+  has(fix, '`trailhead-fix`', 'config.models.execute', 'executor-brief.md', 'only protocol text'));
+ok('Fix: lists the runtime inputs',
+  has(lf, 'ticket number', 'base sha', 'config.tdd', 'mockup link', 'accepted mockup deviations'));
+ok('Fix: UI-fix Prototype + approval',
+  has(fix, 'Prototype technique', 'config.design', 'config.design.approval') && lf.includes('ui'));
+ok('Fix: posts the fidelity list as a ticket comment',
+  has(fix, 'enumerated fidelity list', 'the orchestrator posts it as a ticket comment'));
+ok('Fix: infeasible element settle-and-re-spawn loop',
+  lf.includes('infeasible') && lf.includes('revise and re-approve the mockup') && lf.includes('accepts a named deviation') && lf.includes('re-spawn'));
+ok('Fix: block-and-ask on a flagged package with explicit-yes resume',
+  lf.includes('block-and-ask') && lf.includes('flagged package') && lf.includes('explicit yes') && lf.includes('user-approved'));
+ok('Fix: captures surfaced scope', lf.includes('surfaced scope') && lf.includes('captured'));
+ok('Fix: branch before the spawn and PR under git: pr',
+  has(fix, 'git: pr', 'the orchestrator creates the branch before the spawn and opens the PR'));
+ok('Fix: worktree under isolation: worktree', has(fix, 'isolation: worktree', 'git worktree'));
+
+// --- agents point to the brief -----------------------------------------------------------------------------
+for (const a of ['trailhead-executor', 'trailhead-fix']) {
+  const md = fs.readFileSync(path.join(plugin, 'agents', `${a}.md`), 'utf8');
+  ok(`${a}.md points to executor-brief.md`, md.includes('trailhead-work/references/executor-brief.md'));
+}
+const techniques = fs.readFileSync(path.join(plugin, 'skills', '_shared', 'techniques.md'), 'utf8');
+ok('techniques.md: Execute and Fix inject executor-brief.md, not the whole step',
+  techniques.includes('trailhead-work/references/executor-brief.md'));
+
+// --- no behaviour lost from the pre-split Execute paragraph ------------------------------------------------------
+const both = execute + '\n' + brief;
+for (const needle of [
+  'Prototype technique', 'FIRST', 'config.design', 'never shortcut a hosted mode to a local disk mockup',
+  'config.design.approval', '100% fidelity', 'fidelity list', 'Acceptance testing', 'Goal-backward verification',
+  'atomic commits', 'Refs: #<n>', '`git:`', 'git worktree', 'config.models.execute', '`trailhead-executor`',
+  'verify-before-install', 'TRAILHEAD_VERIFIED_INSTALL', 'block-and-ask', 'captured',
+]) {
+  ok(`no behaviour lost: "${needle}" is in the Execute block or the brief`, both.includes(needle));
+}
+
+for (const [label, src] of [['executor-brief.md', brief], ['ticket-engines.md', engines], ['techniques.md', techniques]]) {
+  ok(`${label}: no em-dash`, !src.includes('—'));
+}
+
+console.log(`execute-split-docs.test.js: ${passed} checks passed`);

package/bin/grilling-holistic-review-docs.test.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// Docs test for #301: every grilling close runs a holistic review pass before the final
+// confirmation. The rule is stated once (Grilling technique); call-sites only point at it.
+// Run: node grilling-holistic-review-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const skills = path.join(__dirname, '..', 'plugins', 'trailhead', 'skills');
+const read = (rel) => fs.readFileSync(path.join(skills, rel), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const ANCHOR = 'Holistic review before the final confirmation';
+const DEFINITION = `**${ANCHOR}.**`;
+
+const walk = (dir) => fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+  e.isDirectory() ? walk(path.join(dir, e.name)) : [path.join(dir, e.name)]);
+
+// 1. the bold definition exists exactly once, in the Grilling technique
+const defs = walk(skills).filter((f) => fs.readFileSync(f, 'utf8').includes(DEFINITION));
+ok('definition appears in exactly one file', defs.length === 1);
+ok('definition lives in grilling.md', defs[0] === path.join(skills, '_shared', 'techniques', 'grilling.md'));
+const grilling = read('_shared/techniques/grilling.md');
+ok('definition appears once', grilling.split(DEFINITION).length === 2);
+
+// 2. the definition bullet carries the normative fragments
+const lines = grilling.split('\n');
+const rule = lines.find((l) => l.includes(DEFINITION));
+for (const frag of [
+  'Once the frontier is empty and before the final confirmation',
+  'as a whole',
+  'against each other and against the destination',
+  'proposed amendments',
+  'non-working combinations',
+  'contradictions, gaps, choices that break each other or the destination',
+  'by question number',
+  'say so in one line and go straight to the confirmation',
+  'accept, amend or reject',
+  'reject keeps the choices as they were',
+  'consciously accepted risk',
+  'reopens that branch',
+  'the review runs again on the new set',
+  're-confirmed in one play-back',
+  'at most once more',
+  'Only then is the final set played back, confirmed and recorded',
+  '`AskUserQuestion` menu',
+  'without the delegate option',
+]) ok(`rule carries: ${frag}`, rule.includes(frag));
+
+// 3. the Stop bullet is followed by the review
+const stop = lines.find((l) => l.startsWith('- **Stop only when the frontier is empty'));
+ok('stop bullet found', !!stop);
+ok('stop bullet references the anchor', stop.includes(ANCHOR));
+ok('stop bullet scopes the hold to the final set', stop.includes('the final set is not confirmed or recorded before it has run'));
+
+// 4. call-sites only point at the rule
+const pointer = (name, text, startsWith) => {
+  const l = text.split('\n').find((x) => x.startsWith(startsWith));
+  ok(`${name} found`, !!l);
+  ok(`${name} references the anchor`, l.includes(ANCHOR));
+  ok(`${name} does not restate the rule`, !l.includes('accepted risk') && !l.includes('reject keeps'));
+};
+pointer('chart SKILL standalone grill', read('trailhead-chart/SKILL.md'), 'Run a standalone **Grilling**');
+const engines = read('trailhead-work/references/ticket-engines.md');
+pointer('decision Converge', engines, '2. **Converge.**');
+pointer('build Discuss', engines, '1. **Discuss**');
+ok('build Discuss records the set after the review', engines.split('\n').find((l) => l.startsWith('1. **Discuss**')).includes('after the review'));
+const charting = read('trailhead-chart/references/charting.md');
+pointer('charting Mode 1 step 3', charting, '3. **Create the map**');
+pointer('charting Mode 1-bis step 2', charting, '2. **Name the destination of the remaining stretch.**');
+pointer('charting Mode 1-bis step 4', charting, '4. **Map the frontier of the remainder**');
+ok('charting Mode 1 step 3 covers the destination too', charting.split('\n').find((l) => l.startsWith('3. **Create the map**')).includes('step 1 destination'));
+const choices = read('_shared/choices.md');
+const row = choices.split('\n').find((l) => l.startsWith('| Grilling holistic review'));
+ok('choices row found', !!row);
+const cells = row.split('|').map((c) => c.trim());
+ok('choices row delegate No', cells[2].startsWith('No'));
+ok('choices row defer No', cells[3] === 'No');
+const prose = choices.split('\n').find((l) => l.startsWith('**Prose / conversational call-sites'));
+ok('prose paragraph references the anchor', prose.includes(ANCHOR));
+
+// 5. no em-dash in the touched files
+for (const rel of ['_shared/techniques/grilling.md', '_shared/choices.md', 'trailhead-chart/SKILL.md',
+  'trailhead-work/references/ticket-engines.md', 'trailhead-chart/references/charting.md'])
+  ok(`${rel} has no em-dash`, !read(rel).includes(String.fromCharCode(8212)));
+ok('this test has no em-dash', !fs.readFileSync(__filename, 'utf8').includes(String.fromCharCode(8212)));
+
+console.log(`grilling-holistic-review-docs.test.js: ${passed} checks passed`);

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

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

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

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Docs test for #242: the skill prose names the gitignored-file copy helper for new
+// isolation workspaces and documents the isolation.copy config key.
+// Run: node isolation-copy-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const skills = path.join(__dirname, '..', 'plugins', 'trailhead', 'skills');
+const read = (rel) => fs.readFileSync(path.join(skills, rel), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// file -> strings it must carry
+const EXPECT = {
+  'trailhead-work/SKILL.md': ['trailhead-isolation-copy.js --from <main-checkout> --to <working-root>', 'Gitignored files in a new workspace'],
+  '_shared/teamwork.md': ['trailhead-isolation-copy.js --from <main-checkout> --to <working-root>', 'Gitignored files in a new workspace', 'isolation.copy', 'before any install', '`rejected`', '`warnings`', '`status: skipped`'],
+  '_shared/configuration-reference.md': ['`isolation.copy`', 'Isolation copy', '.example', '.sample'],
+};
+
+for (const [rel, needles] of Object.entries(EXPECT)) {
+  const text = read(rel);
+  for (const needle of needles) ok(`${rel} names: ${needle}`, text.includes(needle));
+  ok(`${rel} has no em-dash`, !text.includes('—'));
+}
+
+console.log(`isolation-copy-docs.test.js: ${passed} checks passed`);