@marcomigozzi/trailhead 0.17.0 → 0.18.0

package/bin/repo-target-docs.test.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Docs test for #351: the skill prose names the repo-target helper's check/record
+// before the first tracker write, in load-first.md and in the capture cluster's
+// compact core, and the marker stays gitignored.
+// Run: node repo-target-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const root = path.join(__dirname, '..');
+const shared = path.join(root, 'plugins', 'trailhead', 'skills', '_shared');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const read = (f) => fs.readFileSync(path.join(shared, f), 'utf8');
+const loadFirst = read('load-first.md');
+const captureCore = read('capture-core.md');
+const teamwork = read('teamwork.md');
+const gitignore = fs.readFileSync(path.join(root, '.gitignore'), 'utf8');
+
+const HEAD = '**Repo target check, once per session, before the first tracker write.**';
+ok('load-first.md carries the repo target paragraph', loadFirst.includes(HEAD));
+ok('capture-core.md carries a drift marker to it', captureCore.includes(`<!-- core: load-first.md | ${HEAD} |`));
+
+for (const [name, text] of [['load-first.md', loadFirst], ['capture-core.md', captureCore], ['teamwork.md', teamwork]]) {
+  ok(`${name} has no em-dash`, !text.includes('—'));
+}
+for (const [name, text] of [['load-first.md', loadFirst], ['capture-core.md', captureCore]]) {
+  ok(`${name} names check`, text.includes('trailhead-repo-target.js check'));
+  ok(`${name} names record`, text.includes('trailhead-repo-target.js record'));
+  ok(`${name} says record gitignores the marker`, text.includes('`.gitignore` if absent'));
+  ok(`${name} names the marker`, text.includes('.trailhead/repo-target.json'));
+}
+ok('capture-core.md places the check before the create commands',
+  captureCore.indexOf('## Repo target check') !== -1 && captureCore.indexOf('## Repo target check') < captureCore.indexOf('gh issue create'));
+ok('capture-core.md tells trailhead-capture.js callers to pass the target', captureCore.includes('as `--repo`'));
+ok('teamwork.md lists the marker with its siblings', teamwork.includes('**Repo target record.**') && teamwork.includes('isolation-answer.json'));
+ok('.gitignore carries the record', gitignore.split('\n').includes('.trailhead/repo-target.json'));
+
+console.log(`repo-target-docs.test.js: ${passed} checks passed`);

package/bin/seam-coverage-docs.test.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// Docs test for #356: every seam a PLAN names carries one line saying what it
+// catches and what it misses, stated by the TDD technique, the Plan step and
+// the plan agent's return contract.
+// Run: node seam-coverage-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');
+const read = (...p) => fs.readFileSync(path.join(...p), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const LINE = '`<seam>: catches <what a test here fails on>; misses <what gets through it>`';
+
+const tdd = read(skills, '_shared', 'techniques', 'tdd.md');
+const engines = read(skills, 'trailhead-work', 'references', 'ticket-engines.md');
+const blocks = read(root, 'scripts', 'agent-blocks.md');
+const agent = read(root, 'plugins', 'trailhead', 'agents', 'trailhead-plan.md');
+
+ok('tdd: states the seam line', tdd.includes(LINE));
+ok('tdd: a seam line is required in the PLAN', tdd.includes('the PLAN lists each one with its one line'));
+ok('tdd: misses is never empty', tdd.includes('`misses` is never empty'));
+
+const planStep = engines.split('\n').find((l) => l.startsWith('2. **Plan**:')) || '';
+ok('plan step: the PLAN comment carries the seam line',
+  planStep.includes('The step produces a `PLAN` comment: the steps, the seams (each with its one-line catches/misses, per **TDD**), the files touched, the verification criteria.'));
+
+const contract = `\`ready\`: the rest of the report is the PLAN (the \`body\`): the steps, the seams (one line each, ${LINE}), the files touched and the verification criteria.`;
+ok('agent blocks: the plan contract carries the seam line', blocks.includes(contract));
+ok('plan agent: the contract carries the seam line', agent.includes(contract));
+
+for (const [name, text] of Object.entries({
+  'tdd.md': tdd,
+  'ticket-engines.md': engines,
+  'agent-blocks.md': blocks,
+  'trailhead-plan.md': agent,
+  'seam-coverage-docs.test.js': read(__dirname, 'seam-coverage-docs.test.js'),
+})) {
+  ok(`${name} has no em-dash`, !text.includes(String.fromCharCode(0x2014)));
+}
+
+console.log(`seam-coverage-docs.test.js: ${passed} checks passed`);

package/bin/standards-brief-docs.test.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// Docs test for #359: before a code review the orchestrator lists the repo's
+// standards files, the brief carries the paths, and the reviewer reads them and
+// cites the file for each standards finding.
+// Run: node standards-brief-docs.test.js
+const assert = require('assert');
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const root = path.join(__dirname, '..');
+const skills = path.join(root, 'plugins', 'trailhead', 'skills');
+const agents = path.join(root, 'plugins', 'trailhead', 'agents');
+const read = (...p) => fs.readFileSync(path.join(...p), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const review = read(skills, '_shared', 'techniques', 'code-review.md');
+const techniques = read(skills, '_shared', 'techniques.md');
+const agent = read(agents, 'trailhead-code-review.md');
+
+const lines = review.split('\n');
+const route = lines.find((l) => l.startsWith('**First, route it.**')) || '';
+const paraStart = lines.findIndex((l) => l.startsWith('**Standards files: list them before the review.**'));
+const axesIdx = lines.indexOf('Review on five axes:');
+const ticketDiffIdx = lines.findIndex((l) => l.startsWith('**Ticket diff:'));
+const section = paraStart >= 0 ? lines.slice(paraStart, axesIdx).join('\n') : '';
+const axis = lines.find((l) => l.startsWith('- **Standards & spec**')) || '';
+
+// The brief: the spawn prompt carries the list, paths only.
+ok('route: spawn prompt carries the standards files line', route.includes('`standards files: <list>`'));
+ok('route: points at the listing', route.includes('**Standards files**'));
+
+// The listing.
+ok('section exists', section.length > 0);
+ok('section sits after Ticket diff and before the axes', ticketDiffIdx >= 0 && paraStart > ticketDiffIdx && axesIdx > paraStart);
+ok('axes count unchanged', review.includes('Review on five axes:'));
+
+const command = (section.match(/```\n(git -C <repo> ls-files [^\n]+)\n```/) || [])[1] || '';
+ok('section gives the exact listing command', command.length > 0);
+for (const pattern of [
+  'CONTRIBUTING*', 'CODING_STANDARDS*', 'AGENTS.md', 'CLAUDE.md', '.editorconfig', '.eslintrc*', 'eslint.config.*',
+  '.prettierrc*', 'prettier.config.*', 'biome.json*', 'ruff.toml', 'pyproject.toml', '.golangci.*', 'rustfmt.toml',
+]) {
+  ok(`command matches ${pattern} at any depth`, command.includes(`**/${pattern}'`));
+}
+ok('CONTRIBUTING matches in any case', command.includes("':(glob,icase)**/CONTRIBUTING*'"));
+
+for (const sub of [
+  'trailhead:conventions',
+  '**Find a singleton issue** in `../substrate-commands.md`',
+  'the paths only, never their contents',
+  '`standards files: none`',
+  'Recompute the list on every review round',
+  'gh issue view <n> --json body',
+  'cites the file',
+  'not a standards finding',
+  'what tooling already enforces',
+  '**Review adversarially**',
+  'never a correctness or security finding',
+  'runs the same listing itself',
+  'on every pass including the lean inline one',
+]) {
+  ok(`section: ${sub}`, section.includes(sub));
+}
+
+// The axis and the pointers.
+ok('axis: reads the listed files', axis.includes('**Standards files**'));
+ok('axis: cites the file', axis.includes('cite the file'));
+ok('techniques.md: row names the listing', techniques.includes("the brief lists the repo's standards files"));
+ok('techniques.md: 5 axes kept', techniques.includes('on 5 axes'));
+ok('agent: reads the files the spawn names and cites them',
+  agent.includes('the repo\'s standards files, at the paths the spawn names') && agent.includes('cite the file'));
+
+// The command does what it says on a real repo.
+if (command) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'standards-brief-'));
+  try {
+    const git = (...args) => execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
+    git('init', '-q');
+    const wanted = [
+      'CONTRIBUTING.md', '.github/contributing.md', 'CODING_STANDARDS.md', 'AGENTS.md', 'pkg/a/CLAUDE.md',
+      '.editorconfig', 'eslint.config.mjs', 'pkg/b/.prettierrc.json', 'pyproject.toml',
+    ];
+    const unwanted = ['README.md', 'src/index.js', 'docs/AGENTS.txt'];
+    for (const f of [...wanted, ...unwanted, 'ignored/CLAUDE.md']) {
+      fs.mkdirSync(path.dirname(path.join(dir, f)), { recursive: true });
+      fs.writeFileSync(path.join(dir, f), 'x\n');
+    }
+    fs.writeFileSync(path.join(dir, '.gitignore'), 'ignored/\n');
+    git('add', '-A');
+    const out = execFileSync('sh', ['-c', command.replace('<repo>', `'${dir}'`)], { encoding: 'utf8' })
+      .split('\n').filter(Boolean).sort();
+    assert.deepStrictEqual(out, [...wanted].sort(), 'listing finds exactly the tracked standards files');
+    passed++;
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+for (const [name, text] of Object.entries({
+  'code-review.md': review,
+  'techniques.md': techniques,
+  'trailhead-code-review.md': agent,
+  'standards-brief-docs.test.js': read(__dirname, 'standards-brief-docs.test.js'),
+})) {
+  ok(`${name} has no em-dash`, !text.includes(String.fromCharCode(0x2014)));
+}
+
+console.log(`standards-brief-docs.test.js: ${passed} checks passed`);

package/bin/test-once-docs.test.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// Docs test for #363: the engine runs the full test suite once per ticket.
+// Execute/Fix run focused tests, Verify runs the full suite once on the synced
+// tree and records it, the reviewing agents read that record, and no em-dash.
+// Run: node test-once-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');
+const agents = path.join(root, 'plugins', 'trailhead', 'agents');
+const read = (...p) => fs.readFileSync(path.join(...p), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const docs = {
+  'executor-brief.md': read(skills, 'trailhead-work', 'references', 'executor-brief.md'),
+  'ticket-engines.md': read(skills, 'trailhead-work', 'references', 'ticket-engines.md'),
+  'teamwork.md': read(skills, '_shared', 'teamwork.md'),
+  'tdd.md': read(skills, '_shared', 'techniques', 'tdd.md'),
+  'debug.md': read(skills, '_shared', 'techniques', 'debug.md'),
+  'code-review.md': read(skills, '_shared', 'techniques', 'code-review.md'),
+  'verify.md': read(skills, '_shared', 'techniques', 'verify.md'),
+  'configuration-reference.md': read(skills, '_shared', 'configuration-reference.md'),
+  'agent-blocks.md': read(root, 'scripts', 'agent-blocks.md'),
+  'trailhead-code-review.md': read(agents, 'trailhead-code-review.md'),
+  'trailhead-verify.md': read(agents, 'trailhead-verify.md'),
+  'README.md': read(root, 'README.md'),
+  'README.it.md': read(root, 'README.it.md'),
+  'configuration.mdx': read(root, 'site', 'src', 'content', 'docs', 'docs', 'configuration.mdx'),
+};
+
+// Execute/Fix: focused tests only, never the whole suite.
+const brief = docs['executor-brief.md'];
+ok('executor-brief.md: focused tests only', brief.includes('run only the focused tests'));
+ok('executor-brief.md: never the whole suite', brief.includes('never the whole suite'));
+ok('executor-brief.md: targeted run through the helper', brief.includes('--kind targeted --files <a,b>'));
+ok('tdd.md: loop runs focused tests', docs['tdd.md'].includes('focused tests'));
+ok('tdd.md: full suite once at Verify', docs['tdd.md'].includes('once per ticket, at Verify'));
+
+// Verify: one full run on the synced tree, recorded, read by the reviewers.
+const engines = docs['ticket-engines.md'];
+ok('ticket-engines.md: one full run per tree', (engines.match(/runs the full suite once on the synced tree/g) || []).length === 2);
+ok('ticket-engines.md: test record named in build and bug Verify', (engines.match(/\*\*test record\*\*/g) || []).length === 2);
+ok('ticket-engines.md: no double run after the sync', !engines.includes('then sync, then re-run the tests'));
+
+// Each Verify (build, bug) is its own line of ticket-engines.md.
+const verifyLines = engines.split('\n').filter((l) => l.startsWith('4. **Verify**'));
+ok('ticket-engines.md: build and bug Verify found', verifyLines.length === 2);
+for (const [i, line] of verifyLines.entries()) {
+  const which = i === 0 ? 'build' : 'bug';
+  ok(`${which} Verify: exactly one full-run invocation`, (line.match(/trailhead-test-run\.js run --repo/g) || []).length === 1);
+  ok(`${which} Verify: failed record reused on the same tree`, line.includes('reuse it instead of invoking the helper'));
+  ok(`${which} Verify: reviewers never re-run, exactly once`, (line.match(/never re-run the full suite/g) || []).length === 1);
+  ok(`${which} Verify: no legacy second run`, !line.includes('then run the tests') && !line.includes('then re-run the tests'));
+}
+
+// Scoping: the record and single-run rules apply only with testing.full.
+ok('executor-brief.md: scoping names testing.full', /testing\.full[^\n]*focused/.test(brief));
+ok('ticket-engines.md: unconfigured runs once, no record, reviewers get none', verifyLines.every((l) => l.includes('The helper\'s `unconfigured` falls back to the project\'s own command, run once on the synced tree; no test record is built and the reviewing agents get none, so they test as today (Execute and Fix focused runs still use `--kind targeted --files <a,b>`)')));
+ok('ticket-engines.md: no garbled as-before sentence', verifyLines.every((l) => !l.includes('behave as before')));
+ok('ticket-engines.md: Execute/Fix focused clause kept', verifyLines.every((l) => l.includes('--kind targeted --files <a,b>')));
+ok('configuration-reference.md: scoping names testing.full', /without `testing\.full`/i.test(docs['configuration-reference.md']));
+ok('README.md: scoping names testing.full', /without `testing\.full`/i.test(docs['README.md']));
+ok('configuration.mdx: scoping names testing.full', /without `testing\.full`/i.test(docs['configuration.mdx']));
+
+// The reviewers never invoke the helper.
+for (const name of ['code-review.md', 'verify.md', 'trailhead-code-review.md', 'trailhead-verify.md']) {
+  ok(`${name}: no helper run invocation`, !docs[name].includes('trailhead-test-run.js run'));
+}
+
+// Post-sync re-run reuses the cache.
+ok('teamwork.md: post-sync run reuses the cached result', docs['teamwork.md'].includes('`source: cache`'));
+const tw = docs['teamwork.md'];
+ok('teamwork.md: preflight never runs the suite', tw.includes('The preflight itself never runs the suite'));
+ok('teamwork.md: never an extra invocation', tw.includes('never an extra invocation'));
+ok('teamwork.md: Resolve new tree gets one run, record in the resolution comment', tw.includes('its test record is added to the resolution comment, superseding the Verify record'));
+ok('teamwork.md: no separate re-run instruction after synced', !tw.includes('re-run the test suite on the synced tree') && !tw.includes('re-runs the tests'));
+ok('teamwork.md: current needs no re-run', docs['teamwork.md'].includes('`current` needs no re-run'));
+
+// Reviewing agents read the record.
+for (const name of ['code-review.md', 'verify.md', 'agent-blocks.md', 'trailhead-code-review.md', 'trailhead-verify.md']) {
+  ok(`${name}: no record without testing.full`, docs[name].includes('without `testing.full` no test record is passed'));
+  ok(`${name}: reads the test record`, docs[name].includes('test record'));
+  ok(`${name}: never re-runs the full suite`, docs[name].includes('never re-run the full suite'));
+}
+
+// Debug step 9 through the helper.
+ok('debug.md: full suite through the helper', /full suite green[^\n]*trailhead-test-run\.js/.test(docs['debug.md']));
+
+// Config docs.
+ok('configuration-reference.md: once per ticket', docs['configuration-reference.md'].includes('once per ticket'));
+ok('README.md: once per ticket', docs['README.md'].includes('once per ticket'));
+ok('README.it.md: una volta per ticket', docs['README.it.md'].includes('una volta per ticket'));
+ok('configuration.mdx: once per ticket', docs['configuration.mdx'].includes('once per ticket'));
+
+for (const [name, text] of Object.entries(docs)) ok(`${name} has no em-dash`, !text.includes('—'));
+
+console.log(`test-once-docs.test.js: ${passed} checks passed`);

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

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Docs test for #362: the docs name the test-run helper, its config keys, the
+// queue and cache contract, and carry no em-dash.
+// Run: node test-run-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');
+const read = (...p) => fs.readFileSync(path.join(...p), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const docs = {
+  'ticket-engines.md': read(skills, 'trailhead-work', 'references', 'ticket-engines.md'),
+  'executor-brief.md': read(skills, 'trailhead-work', 'references', 'executor-brief.md'),
+  'teamwork.md': read(skills, '_shared', 'teamwork.md'),
+  'configuration-reference.md': read(skills, '_shared', 'configuration-reference.md'),
+  'README.md': read(root, 'README.md'),
+  'README.it.md': read(root, 'README.it.md'),
+  'configuration.mdx': read(root, 'site', 'src', 'content', 'docs', 'docs', 'configuration.mdx'),
+};
+
+for (const name of ['ticket-engines.md', 'executor-brief.md', 'teamwork.md']) {
+  ok(`${name} names the helper`, docs[name].includes('trailhead-test-run.js'));
+}
+ok('ticket-engines.md names the full run command', docs['ticket-engines.md'].includes('trailhead-test-run.js run --repo <working-root> --config-root <project root>'));
+ok('ticket-engines.md names the targeted run', docs['ticket-engines.md'].includes('--kind targeted --files'));
+ok('ticket-engines.md names the unconfigured fallback', docs['ticket-engines.md'].includes('`unconfigured` falls back'));
+
+for (const name of ['configuration-reference.md', 'README.md', 'README.it.md', 'configuration.mdx']) {
+  for (const key of ['testing.full', 'testing.targeted', 'testing.maxParallel']) {
+    ok(`${name} documents ${key}`, docs[name].includes(key));
+  }
+}
+const ref = docs['configuration-reference.md'];
+for (const needle of ['**Test runs.**', 'TRAILHEAD_CACHE_DIR', 'nice -n 10', 'ionice -c 3', '--no-cache', 'tree SHA + command', '🧪 Test suite', 'safe to delete when no test run is active']) {
+  ok(`configuration-reference.md carries: ${needle}`, ref.includes(needle));
+}
+ok('README.md carries the Test runs paragraph', docs['README.md'].includes('**Test runs.**'));
+ok('README.it.md carries the mirrored paragraph', docs['README.it.md'].includes('**Esecuzioni dei test.**'));
+
+for (const [name, text] of Object.entries(docs)) ok(`${name} has no em-dash`, !text.includes('—'));
+
+console.log(`test-run-docs.test.js: ${passed} checks passed`);

package/bin/trailhead.js

@@ -248,7 +248,7 @@ function claudePaths(configDir) {
 // 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', 'trailhead-labels-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', 'trailhead-test-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
@@ -262,10 +262,12 @@ const ENTRYPOINT_FILES = HOOK_FILES.filter((f) => !BASH_GUARD_MODULES.includes(f
 // also does require('./lib/body-sources.js'), #210; trailhead-check-update.js
 // does require('./lib/model-defaults-review.js'), which in turn reads the
 // sibling model-defaults.json, #186; both mockup-link hooks do
-// require('./lib/mockup-link.js')). Copied by name, never a recursive
+// require('./lib/mockup-link.js'); trailhead-check-update.js also does
+// require('./lib/trailhead-git-env.js'), a byte-identical copy of
+// templates/trailhead-git-env.js, #349). Copied by name, never a recursive
 // sweep: the Claude hooks/lib dir is shared with other plugins, so we must
 // not clobber a co-tenant's lib nor ship our own *.test.js files.
-const HOOK_LIB_FILES = ['commit-message-check.js', 'shell-scan.js', 'gh-subcommand.js', 'body-sources.js', 'unmodelled.js', 'model-defaults-review.js', 'model-defaults.json', 'inherit-session.js', 'model-route.js', 'mockup-link.js', 'gh-auth-preflight.js'];
+const HOOK_LIB_FILES = ['commit-message-check.js', 'shell-scan.js', 'gh-subcommand.js', 'body-sources.js', 'unmodelled.js', 'model-defaults-review.js', 'model-defaults.json', 'inherit-session.js', 'model-route.js', 'mockup-link.js', 'gh-auth-preflight.js', 'trailhead-git-env.js'];
 // search-guard is Claude-Code-specific (#169), and so is mockup-link-guard
 // (it gates the AskUserQuestion tool, which Codex lacks): excluded from both
 // the Codex hook copy and the Codex verify spec's expected hookFiles, so a
@@ -615,7 +617,10 @@ function installCodex(configDir, { useSymlink }) {
   for (const f of (fs.existsSync(L.promptsDir) ? fs.readdirSync(L.promptsDir) : [])) {
     if (f.startsWith('trailhead-')) rmrf(path.join(L.promptsDir, f));
   }
-  rmrf(L.legacyEngineDir);
+  // La stessa cartella ospita la config globale di Codex: un aggiornamento non deve cancellarla.
+  for (const f of (fs.existsSync(L.legacyEngineDir) ? fs.readdirSync(L.legacyEngineDir) : [])) {
+    if (f !== 'config.json') rmrf(path.join(L.legacyEngineDir, f));
+  }
 
   // Sweep the whole engine + any prior per-verb skills, then project fresh.
   sweepTrailheadSkills(L.skillsRoot);

package/bin/trailhead.test.js

@@ -471,7 +471,7 @@ ok('both Verify step lines reference the Ticket diff', verifyStepLines181.every(
 ok('ticket-engines.md does NOT contain the old range-scoped diff', !ticketEnginesSource181.includes('git diff <base>...HEAD'));
 
 ok("techniques.md index row updates Code review to the ticket's own commits",
-  techniquesSource181.includes("review the ticket's own commits (its `Refs: #<n>` set) on 4 axes"));
+  techniquesSource181.includes("review the ticket's own commits (its `Refs: #<n>` set) on 5 axes"));
 
 for (const [label, src] of [
   ['code-review.md', codeReviewSource181],
@@ -920,7 +920,7 @@ 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,labels'))));
+  (g.hooks || []).some((h) => h.command.includes('trailhead-bash-guards.js') && h.command.endsWith(' --guards=commit,secret,install,body,labels,test'))));
 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`))) &&
@@ -974,6 +974,8 @@ ok('codex: skills/trailhead/hooks/lib/mockup-link.js exists (mockup-link-stop re
   fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'mockup-link.js')));
 ok('codex: skills/trailhead/hooks/lib/gh-auth-preflight.js exists (check-update require target)',
   fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'gh-auth-preflight.js')));
+ok('codex: skills/trailhead/hooks/lib/trailhead-git-env.js exists (check-update require target)',
+  fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'trailhead-git-env.js')));
 ok('codex: skills/trailhead/hooks/trailhead-mockup-link-guard.js does NOT exist',
   !fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'trailhead-mockup-link-guard.js')));
 ok('codex: skills/trailhead/hooks/lib/shell-scan.js still exists (secret-read-guard require target)',
@@ -1086,6 +1088,15 @@ ok('codex migration: stale prompts/trailhead.md swept on install', !fs.existsSyn
 ok('codex migration: stale prompts/trailhead-work.md swept on install', !fs.existsSync(path.join(migCodexDir, 'prompts', 'trailhead-work.md')));
 ok('codex migration: per-verb skill projected in its place', fs.existsSync(path.join(migCodexDir, 'skills', 'trailhead-work', 'SKILL.md')));
 
+// La config globale di Codex sta nella cartella del vecchio motore: un aggiornamento non deve cancellarla.
+const keepCodexDir = mktmp();
+fs.mkdirSync(path.join(keepCodexDir, 'trailhead', 'references'), { recursive: true });
+fs.writeFileSync(path.join(keepCodexDir, 'trailhead', 'references', 'old.md'), 'stale engine\n');
+fs.writeFileSync(path.join(keepCodexDir, 'trailhead', 'config.json'), '{"testing":{"full":"npm test"}}\n');
+runInstaller([`--codex`, `--dir=${keepCodexDir}`]);
+ok('codex install: global config survives', fs.existsSync(path.join(keepCodexDir, 'trailhead', 'config.json')));
+ok('codex install: old engine files still swept', !fs.existsSync(path.join(keepCodexDir, 'trailhead', 'references')));
+
 // codex migration: a stale trailhead-owned skill dir (pre-split monolith /
 // removed cluster) is swept on reinstall; a co-tenant skill is preserved.
 const migCodexSkillDir = mktmp();
@@ -1335,13 +1346,14 @@ 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 six modules exist', ['bash-guards', 'commit-guard', 'secret-guard', 'install-guard', 'search-guard', 'body-guard', 'labels-guard']
+ok('claude: hooks/trailhead-bash-guards.js and its seven modules exist', ['bash-guards', 'commit-guard', 'secret-guard', 'install-guard', 'search-guard', 'body-guard', 'labels-guard', 'test-guard']
   .every((n) => fs.existsSync(path.join(claudeDir, 'hooks', `trailhead-${n}.js`))));
 // mockup-link-guard: Claude-only PreToolUse(AskUserQuestion) backstop for the
 // Prototype "link in the same message as the approval ask" rule.
 ok('claude: hooks/trailhead-mockup-link-guard.js exists', fs.existsSync(path.join(claudeDir, 'hooks', 'trailhead-mockup-link-guard.js')));
 ok('claude: hooks/lib/mockup-link.js exists (mockup-link-guard require target)', fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'mockup-link.js')));
 ok('claude: hooks/lib/gh-auth-preflight.js exists (check-update require target)', fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'gh-auth-preflight.js')));
+ok('claude: hooks/lib/trailhead-git-env.js exists (check-update require target)', fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'trailhead-git-env.js')));
 ok('claude: hooks/trailhead-mockup-link-stop.js does NOT exist (Codex-only twin)', !fs.existsSync(path.join(claudeDir, 'hooks', 'trailhead-mockup-link-stop.js')));
 ok('claude: settings.json does NOT register mockup-link-stop', !settingsContent.includes('trailhead-mockup-link-stop.js'));
 ok('claude: settings.json registers mockup-link-guard under PreToolUse/AskUserQuestion',
@@ -1732,7 +1744,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,labels'));
+    cmds[0].endsWith(' --guards=commit,secret,install,body,labels,test'));
   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);
@@ -2109,8 +2121,8 @@ ok('source: hooks.json keeps its command hooks next to the module (#202)',
 
 // --- #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: first-use setup lists twenty-two labels including trailhead:paused, trailhead:uat, trailhead:needs-you and trailhead:needs-info',
+  /all twenty-two:/.test(firstUseLine) && firstUseLine.includes('`trailhead:paused`') && firstUseLine.includes('`trailhead:uat`') && firstUseLine.includes('`trailhead:needs-you`') && firstUseLine.includes('`trailhead:needs-info`'));
 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',

package/bin/yes-accepts-recommended-docs.test.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Docs test for #358: in grilling a plain "yes" always accepts the recommended answer.
+// The rule is defined once (Grilling technique); the grill return contract states it for the agent.
+// Run: node yes-accepts-recommended-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const repo = path.join(__dirname, '..');
+const plugin = path.join(repo, 'plugins', 'trailhead');
+const read = (...rel) => fs.readFileSync(path.join(...rel), 'utf8');
+const line = (text, start) => text.split('\n').find((l) => l.startsWith(start));
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const DEFINITION = '**A yes accepts the recommendation.**';
+const walk = (dir) => fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+  e.isDirectory() ? walk(path.join(dir, e.name)) : [path.join(dir, e.name)]);
+
+// 1. defined exactly once, in the Grilling technique
+const techniquePath = path.join(plugin, 'skills', '_shared', 'techniques', 'grilling.md');
+const defs = walk(plugin).filter((f) => read(f).includes(DEFINITION));
+ok('definition appears in exactly one file', defs.length === 1);
+ok('definition lives in grilling.md', defs[0] === techniquePath);
+
+// 2. the definition carries the normative fragments, on the one-question bullet
+const technique = read(techniquePath);
+const rule = line(technique, '- **One question at a time, with your pick.**');
+ok('rule sits on the one-question bullet', rule.includes(DEFINITION));
+for (const frag of [
+  'a plain "yes" accepts your pick',
+  'never an open "should we A or B?" followed by a recommendation',
+  'exactly one meaning',
+  'A play-back',
+]) ok(`rule carries: ${frag}`, rule.includes(frag));
+
+// 3. the relay never rewords the question out of the rule
+const relay = line(technique, '   - `question`: relay');
+ok('relay names the rule', relay.includes('**A yes accepts the recommendation**'));
+
+// 4. the return contract states it, in the source block and in the synced agent
+for (const [name, text] of [
+  ['agent-blocks.md', read(repo, 'scripts', 'agent-blocks.md')],
+  ['trailhead-grill.md', read(plugin, 'agents', 'trailhead-grill.md')],
+]) {
+  const q = line(text, '- `question:` the one numbered question');
+  const r = line(text, '- `recommended:` your pick');
+  ok(`${name}: question is worded so a yes accepts the pick`, q.includes('a plain "yes" accepts `recommended:`'));
+  ok(`${name}: question bans the open form`, q.includes('never an open "should we A or B?"'));
+  ok(`${name}: recommended is what a yes accepts`, r.includes('what a plain "yes" accepts'));
+}
+
+console.log(`yes-accepts-recommended-docs: ${passed} assertions passed`);

package/package.json

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

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

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

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

@@ -7,7 +7,7 @@ tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, TodoWrite
 
 trailhead's code-review subagent. Review the ticket's diff adversarially on the Code review technique's axes, verifying each finding before reporting. Do not defer to a convention or a settled-decision memory.
 
-The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/code-review.md`); follow that, not any embedded copy. Read-only by policy: it reviews and returns the report (the orchestrator posts it as the `VERIFY` comment), it must never Edit/Write or commit. Model-agnostic by design: the engine passes the `config.models.review` model as the spawn-time override, so config stays authoritative.
+The full protocol is injected at spawn from the trailhead skill's single source (`_shared/techniques/code-review.md`); follow that, not any embedded copy. Read-only by policy: it reviews and returns the report (the orchestrator posts it as the `VERIFY` comment), it must never Edit/Write or commit. Model-agnostic by design: the engine passes the `config.models.review` model as the spawn-time override, so config stays authoritative. A pipeline-touching diff also loads `code-review-pipeline.md`, at the path the spawn names. Read the repo's standards files, at the paths the spawn names, for the Standards & spec axis, and cite the file for each standards finding.
 
 <!-- trailhead:agent-block common -->
 **Search-command hygiene.** Prefer the Grep and Read tools; use absolute paths and `git -C <abs>`.
@@ -22,4 +22,5 @@ Never `cd` (or `pushd`/`env -C`) into a directory first; the full rule is in `_s
 - trailhead-verify: `<token>` is one of `met` | `gaps_found` | `inconclusive`; each claim line carries `class: <met|unmet|partial|inconclusive>`, and `met` lists no `unmet`, `partial` or `inconclusive` claim.
 - trailhead-code-review: `<token>` is one of `clean` | `issues_found`, and line 2 is the counts line `critical: <n> · warning: <n> · info: <n>`; `clean` with a non-zero `critical` count requires a ledger line closing every Critical (`fixed`, `deferred` or `accepted`), none `open`.
 - Read-only: never Edit/Write, never commit.
+- When the orchestrator passes a test record (`test record: ...`, the full-suite outcome of Verify), read it and never re-run the full suite (a focused test to probe one finding is fine); with no record passed, test as today (without `testing.full` no test record is passed).
 <!-- /trailhead:agent-block reviewing -->

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

@@ -33,8 +33,8 @@ Never `cd` (or `pushd`/`env -C`) into a directory first; the full rule is in `_s
 - You never talk to the user and never answer on their behalf: the orchestrator relays the question and collects the answer. The recommended answer is only your pick.
 - `settled:` every settled choice so far, one per line by question number, with its rationale; `none` before the first answer.
 - `frontier:` the open questions whose prerequisites are settled; `none` once it is empty.
-- `question:` the one numbered question to ask now. Illustrate each option: what it optimizes and what it sacrifices. Offer defer in prose when the question is blocked on a prerequisite. Play back the user's understanding when it closes a branch.
-- `recommended:` your pick, stress-tested, ending with a `Weak point:` line (not a field label, so a review may carry one per fix). Never the delegate option.
+- `question:` the one numbered question to ask now, worded around your pick so a plain "yes" accepts `recommended:` and has no other meaning; never an open "should we A or B?" followed by a recommendation. Illustrate each option (its label, a one-line summary, its trade-off) so the relay can render them per **The ask is answerable from the chat alone**; never a reference to the ticket in place of the options. Offer defer in prose when the question is blocked on a prerequisite. Play back the user's understanding when it closes a branch.
+- `recommended:` your pick, what a plain "yes" accepts, stress-tested, ending with a `Weak point:` line (not a field label, so a review may carry one per fix). Never the delegate option.
 - `areas:` for a multi-part space, every functional area, each marked visited or open.
 - `facts:` what you looked up, with `file:line` or a URL. A fact you could not reach is written as `not looked up: <what>`; the orchestrator fetches it for the next round.
 - `amendments:` / `conflicts:` the holistic review. Each item names its question numbers; each conflict carries its fix, or one line saying where it goes. Both are `none` when nothing is found, and always `none` on a `question` round.

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

@@ -26,6 +26,6 @@ Never `cd` (or `pushd`/`env -C`) into a directory first; the full rule is in `_s
 - invariant: `needs_input` => `questions` non-empty.
 - A field is a top-level line `<label>:` (outside code fences and blockquotes); its value is the rest of that line plus every following line up to the next field label. An empty value or `none` means none.
 - With `needs_input`, fields are the end of the report: nothing after the last field.
-- `ready`: the rest of the report is the PLAN (the `body`): the steps, the seams, the files touched and the verification criteria. It is posted verbatim, so write nothing in it that is not the PLAN.
+- `ready`: the rest of the report is the PLAN (the `body`): the steps, the seams (one line each, `<seam>: catches <what a test here fails on>; misses <what gets through it>`), the files touched and the verification criteria. It is posted verbatim, so write nothing in it that is not the PLAN.
 - `needs_input`: `questions:` holds the blocking questions only; no PLAN.
 <!-- /trailhead:agent-block plan -->

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

@@ -22,4 +22,5 @@ Never `cd` (or `pushd`/`env -C`) into a directory first; the full rule is in `_s
 - trailhead-verify: `<token>` is one of `met` | `gaps_found` | `inconclusive`; each claim line carries `class: <met|unmet|partial|inconclusive>`, and `met` lists no `unmet`, `partial` or `inconclusive` claim.
 - trailhead-code-review: `<token>` is one of `clean` | `issues_found`, and line 2 is the counts line `critical: <n> · warning: <n> · info: <n>`; `clean` with a non-zero `critical` count requires a ledger line closing every Critical (`fixed`, `deferred` or `accepted`), none `open`.
 - Read-only: never Edit/Write, never commit.
+- When the orchestrator passes a test record (`test record: ...`, the full-suite outcome of Verify), read it and never re-run the full suite (a focused test to probe one finding is fine); with no record passed, test as today (without `testing.full` no test record is passed).
 <!-- /trailhead:agent-block reviewing -->