@marcomigozzi/trailhead 0.16.1 → 0.18.0

package/bin/plan-review-budget-docs.test.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// Docs test for #353: plan review skips a reviewer whose prompt exceeds its context.
+// Plain asserts, no framework. Run: node bin/plan-review-budget-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 review = read('skills/_shared/techniques/plan-review.md');
+const config = read('skills/_shared/configuration-reference.md');
+
+ok('plan-review.md: runs the budget call before each reviewer call', /trailhead-plan-review-rounds\.js budget --repo[^\n]*--reviewer[^\n]*--prompt/.test(review));
+ok('plan-review.md: names the three decisions arg, file, skip', /`arg`:[\s\S]*`file`:[\s\S]*`skip`:/.test(review));
+ok('plan-review.md: file passes the pointer, never the brief as one argument', /`file`:[^\n]*`pointer`[^\n]*never the brief itself as one argument/.test(review));
+ok('plan-review.md: notes the E2BIG limit of a single argument', /128 KiB[^\n]*E2BIG/.test(review));
+ok('plan-review.md: skip does not invoke the reviewer and records the reason', /`skip`:\s*do not invoke[^\n]*`reason`/.test(review));
+ok('plan-review.md: captures stdout and stderr together into one output file', /> <dir>\/<cli>\.out 2>&1/.test(review));
+ok('plan-review.md: a shell-tool launch failure is written into the same file', /shell tool itself fails to launch[^\n]*same file/.test(review));
+ok('plan-review.md: runs the overflow call on a failed call', /trailhead-plan-review-rounds\.js overflow --output/.test(review));
+ok('plan-review.md: overflow true means no retry, recorded as skipped with its reason', /`overflow: true`[^\n]*do not retry[^\n]*skipped[^\n]*`reason`/.test(review));
+ok('plan-review.md: the one-retry rule never applies after an overflow', /One retry \(never after a context overflow\)/.test(review));
+ok('plan-review.md: PLAN-REVIEW lists every skipped or dropped reviewer with its reason, never silent', /`PLAN-REVIEW`[^\n]*every reviewer skipped or dropped, with its reason[^\n]*budget skip[^\n]*context overflow[^\n]*second timeout[^\n]*hard error[^\n]*never a silent drop/.test(review));
+ok('plan-review.md: all reviewers skipped falls back to the no-reviewer rule', /every reviewer ends up skipped[^\n]*no-reviewer-left rule/.test(review));
+
+ok('configuration-reference.md: has the plan_review.context row', /^\| `plan_review\.context` \|/m.test(config));
+ok('configuration-reference.md: explains the 65% rule, the estimate and the post-check', /\*\*plan_review\.context\.\*\*[^\n]*ceil\(bytes \/ 3\)[^\n]*65%[^\n]*not a guarantee[^\n]*not retried/.test(config));
+ok('configuration-reference.md: documents the per-reviewer merge', /\*\*plan_review\.context\.\*\*[^\n]*merge per reviewer[^\n]*project wins/.test(config));
+
+ok('plan-review.md: the overflow call passes the brief so echoed lines are ignored', /overflow --output <dir>\/<cli>\.out --prompt <brief file>/.test(review));
+ok('plan-review.md: a failing budget or overflow helper has a stated fallback', /When `budget` or `overflow` itself fails[^\n]*never guess[^\n]*at most 100 KiB/.test(review));
+
+// #368: every reviewer call is bounded by the run helper.
+ok('plan-review.md: every reviewer call goes through the run subcommand, whatever the launch mode', /Every reviewer call goes through the `run` subcommand, whatever the launch mode[^\n]*trailhead-plan-review-rounds\.js run --output <dir>\/<cli>\.out -- /.test(review));
+ok('plan-review.md: the helper bounds the call because the Bash timeout does not apply to a background call', /helper is what bounds[^\n]*`timeout` parameter does not apply to a background call/.test(review));
+ok('plan-review.md: a timeout skips overflow and takes the one-retry rule', /- `timeout`:[^\n]*\*\*Do not run `overflow`\*\*[^\n]*one-retry rule/.test(review));
+ok('plan-review.md: a second timeout drops the reviewer, recorded with the seconds', /A second timeout \*\*drops\*\*[^\n]*`second timeout`[^\n]*seconds/.test(review));
+ok('plan-review.md: failed or error runs overflow then the one-retry rule', /- `failed` or `error`: run `node <templates>\/trailhead-plan-review-rounds\.js overflow/.test(review));
+ok('plan-review.md: the helper-fails fallback names no JSON line and excludes a status error line', /helper is missing, exits non-zero with no JSON line \(a helper killed by a signal prints none\), or prints non-JSON output\*\*[^\n]*`status: error` JSON line is not this case[^\n]*`failed`\/`error` branch/.test(review));
+ok('plan-review.md: no human prompt on this path, never reported as still running past the bound', /No human prompt anywhere on this path[^\n]*never reported as "still running" past the bound/.test(review));
+ok('plan-review.md: a missing run helper falls back to timeout -k 10 600, 124 or 137 meaning timeout', /helper is missing, exits non-zero[^\n]*`timeout -k 10 600 <cmd> < \/dev\/null > <dir>\/<cli>\.out 2>&1`[^\n]*`gtimeout`[^\n]*124 or 137/.test(review));
+ok('plan-review.md: with no bound available the reviewer is skipped, recorded', /neither available, skip the reviewer, recording that no bound was available/.test(review));
+ok('plan-review.md: the stdin line is not evidence of a stdin hang', /`Reading additional input from stdin\.\.\.` is \*\*not evidence of a stdin hang\*\*/.test(review));
+ok('plan-review.md: the synchronous case still goes through run with the tool timeout above the helper deadline', /still goes through `run`[^\n]*`600000`[^\n]*above the helper's deadline/.test(review));
+ok('plan-review.md: the raw-shell 0% CPU stuck check is gone', !/0% CPU/.test(review));
+const techniques = read('skills/_shared/techniques.md');
+ok('techniques.md: the outcome is awaited up to the bound, a stalled plan reviewer ends as a recorded drop', /the outcome always awaited \(up to its bound[^\n]*stalled reviewer ends as a dropped reviewer, recorded in `PLAN-REVIEW`, never an open wait/.test(techniques));
+
+const root = path.resolve(__dirname, '..');
+const readme = fs.readFileSync(path.join(root, 'README.md'), 'utf8');
+const readmeIt = fs.readFileSync(path.join(root, 'README.it.md'), 'utf8');
+const site = fs.readFileSync(path.join(root, 'site', 'src', 'content', 'docs', 'docs', 'configuration.mdx'), 'utf8');
+for (const [name, text] of [['README.md', readme], ['README.it.md', readmeIt], ['configuration.mdx', site]]) {
+  ok(`${name}: has the plan_review.context row`, /^\| `plan_review\.context` \|/m.test(text));
+}
+
+for (const [name, text] of [['plan-review.md', review], ['configuration-reference.md', config], ['techniques.md', techniques]]) {
+  ok(`${name}: no em-dash`, !text.includes(String.fromCharCode(0x2014)));
+}
+console.log(`plan-review-budget-docs.test.js: ${passed} checks passed`);

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/report-status-docs.test.js

@@ -35,16 +35,18 @@ ok('the paragraph sits next to "Reviews never block the session"',
   start !== -1 && neverBlock !== -1 && Math.abs(start - neverBlock) < 2500 && start > neverBlock);
 const para = start === -1 ? '' : techniques.slice(start, techniques.indexOf('\n| Technique |', start));
 const lc = para.toLowerCase();
+ok('an inline grill round writes no report, so it is not checked',
+  para.includes('An inline `grill` round writes no report') && lc.includes('only a dispatched `trailhead-grill` report is checked'));
 ok('the paragraph section was found and is bounded', para.length > 1000 && !para.includes('| **Grilling**'));
 
 ok('it MUST run on every engine-agent report, the two reviews included', /MUST run on every/.test(para)
   && para.includes('Code review') && para.includes('Goal-backward verification'));
 ok('it names every technique it covers',
-  ['plan', 'executor', 'fix', 'debug', 'research', 'codebase-map'].every((t) => para.includes(t)) && lc.includes('every engine-agent report'));
+  ['plan', 'executor', 'fix', 'debug', 'research', 'codebase-map', 'grill'].every((t) => para.includes(t)) && lc.includes('every engine-agent report'));
 ok('the checker line carries fields and body', para.includes('{"action","verdict","problem","report","fields","body"}'));
 ok('it covers subagent, inline and the lean inline pass', lc.includes('subagent') && lc.includes('inline') && lc.includes('lean inline pass'));
 ok('the checker command with its technique flag and a report file',
-  para.includes('node <templates>/trailhead-report-status.js --technique <verify|code-review|plan|executor|fix|debug|research|codebase-map> --file <that dir>/report.md'));
+  para.includes('node <templates>/trailhead-report-status.js --technique <verify|code-review|plan|executor|fix|debug|research|codebase-map|grill> --file <that dir>/report.md'));
 ok('the three templates dirs, in order',
   (() => {
     const a = para.indexOf('${CLAUDE_PLUGIN_ROOT}/templates/');
@@ -52,6 +54,12 @@ ok('the three templates dirs, in order',
     const c = para.indexOf('~/.codex/skills/trailhead/templates/');
     return a !== -1 && b > a && c > b;
   })());
+ok('a background agent is checked straight from its task output file, no temp dir',
+  para.includes('--task-output <that output file>') && lc.includes('once the agent has finished') && lc.includes('no temp dir, no copy and no cleanup'));
+ok('the temp-dir route is for any other report', lc.includes('any other report (inline, foreground, or a host without that file)'));
+ok('each step is its own Bash call, never bash -c, never chained',
+  lc.includes('its own bash call') && para.includes('never wrapped in `bash -c` / `sh -c`') && lc.includes('never chained')
+  && lc.includes('cannot statically check'));
 ok('the plugin root dir is skipped when unset', lc.includes('skipped when unset'));
 ok('a private temp dir from mktemp -d, once per report', para.includes('`mktemp -d`') && lc.includes('once') && lc.includes('0700'));
 ok('the raw report is written to report.md at the literal printed path with the Write tool',

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/session-trust-docs.test.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// Docs test for #333: the in-session trust rule accepts the same labellers as the label guard
+// (github-actions[bot], TRAILHEAD_LABEL_ALLOWLIST logins, write+ collaborators). Plain asserts.
+// Run: node bin/session-trust-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const root = path.resolve(__dirname, '..');
+const skills = path.join(root, 'plugins', 'trailhead', 'skills');
+const tw = fs.readFileSync(path.join(skills, '_shared', 'teamwork.md'), 'utf8');
+const inbox = fs.readFileSync(path.join(skills, 'trailhead-chart', 'references', 'inbox.md'), 'utf8');
+const s = tw.indexOf('## Trust & provenance');
+const e = tw.indexOf('**Repo-side enforcement');
+const trust = s < 0 || e < s ? '' : tw.slice(s, e);
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+ok('teamwork.md has the trust section', trust !== '');
+ok('bot is a trusted labeller', /`github-actions\[bot\]`[^]*trusted/i.test(trust));
+ok('bot why: GITHUB_TOKEN events trigger no workflow', /GITHUB_TOKEN[^]*(trigger|run)s? no workflow[^]*guard/i.test(trust));
+ok('allowlist read command', trust.includes('gh variable get TRAILHEAD_LABEL_ALLOWLIST'));
+ok('allowlist: not found means empty', /not found[^]*(means|->|is) empty/i.test(trust));
+ok('allowlist: other failure means unknown, not empty', /any other failure[^]*unknown/i.test(trust) && /unknown, not empty/i.test(trust));
+ok('allowlist compare: comma-separated, trimmed, case-insensitive', /comma-separated[^]*trimmed[^]*case-insensitive/i.test(trust));
+ok('unknown allowlist: held off frontier, provenance not checkable', /unknown[^]*held? off the frontier[^]*provenance not checkable/i.test(trust));
+ok('never labelled unverified on a guess', /never[^.]*`trailhead:unverified`[^.]*guess/i.test(trust));
+ok('failed permission lookup is unresolved too', /permission lookup (failed|fails)/i.test(trust) && /`404`[^]*real answer/i.test(trust));
+ok('per-label provenance: latest labeled event of every label', /every `trailhead:\*` label[^]*latest `labeled` event[^]*all[^.]*trusted/i.test(trust));
+ok('one trusted label does not vouch for another', /does not vouch for another/i.test(trust));
+ok('still quarantines other non-write labellers', /`read`\/`none`[^]*not trusted/i.test(trust) && trust.includes('`trailhead:unverified`'));
+ok('session and guard agree', /never strips/i.test(trust));
+ok('inbox: session applies unverified, guard strips', /`trailhead:unverified`[^.]*applied by a session[^]*guard Action strips/i.test(inbox));
+ok('inbox: rogue means outside the trusted labellers', /trusted labellers[^]*Trust rule|Trust rule[^]*trusted labellers/i.test(inbox) && /teamwork\.md#trust--provenance/.test(inbox));
+ok('inbox: jq includes quarantined issues', /\| any\(startswith\("trailhead:"\)\) \| not\) or \(\[\.labels\[\]\.name\] \| any\(\. == "trailhead:unverified"\)\)/.test(inbox));
+ok('no em-dash', !tw.includes(String.fromCharCode(0x2014)) && !inbox.includes(String.fromCharCode(0x2014)));
+console.log(`session-trust-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/surfaced-scope-docs.test.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Docs test: un ticket aperto a metà lavoro va sulla mappa corrente (o su quella giusta)
+// se il tema è suo; altrimenti si chiede fra mappe aperte e whiteboard, mai whiteboard
+// in silenzio; dopo la creazione si dice dove è stato aperto. I rimandi puntano al file.
+// Plain asserts, no framework. Run: node bin/surfaced-scope-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const root = path.resolve(__dirname, '..');
+const read = (rel) => fs.readFileSync(path.join(root, rel), 'utf8');
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+const EM = String.fromCharCode(0x2014);
+
+const SK = 'plugins/trailhead/skills';
+const REF = 'Scope that surfaces while working a ticket';
+
+// La regola condivisa
+const rule = read(`${SK}/_shared/surfaced-scope.md`);
+ok('rule: titled after the referenced name', rule.startsWith(`# ${REF}`));
+ok('rule: do it, split it, or capture it', /\*\*`split`\*\* X/.test(rule) && /capture and continue/.test(rule));
+ok('rule: Surfaced from lineage line', /`Surfaced from: /.test(rule));
+ok('rule: current map first when the topic is its own', /1\. \*\*The current map[^\n]*no ask/.test(rule));
+ok('rule: another open map when the topic clearly is its', /2\. \*\*Another open map[^\n]*no ask/.test(rule));
+ok('rule: otherwise ask, listing every open map and the whiteboard', /3\. \*\*Otherwise, ask\.\*\*[^\n]*AskUserQuestion[^\n]*every open map[^\n]*whiteboard/.test(rule));
+ok('rule: never the whiteboard silently while a map is open', /Never route to the whiteboard without this ask while any map is open/.test(rule));
+ok('rule: no map open falls to the whiteboard', /4\. \*\*No map open → whiteboard, no ask\*\*/.test(rule));
+ok('rule: auto defers an ask case instead of guessing', /autonomous run[^\n]*rule 3[^\n]*Pending follow-up guard/.test(rule));
+ok('rule: announce the ticket and where it landed', /## Say what you opened, and where/.test(rule) && /\*\*where it landed\*\*/.test(rule));
+ok('rule: no em-dash', !rule.includes(EM));
+
+// Ogni rimando al nome porta al file (nessun rimando orfano)
+const referrers = [
+  `${SK}/_shared/session-handoff.md`,
+  `${SK}/_shared/techniques/code-review.md`,
+  `${SK}/trailhead-work/SKILL.md`,
+  `${SK}/trailhead-work/references/ticket-engines.md`,
+];
+for (const rel of referrers) {
+  const text = read(rel);
+  const lines = text.split('\n').filter((l) => l.includes(REF));
+  ok(`${rel}: mentions the rule`, lines.length > 0);
+  ok(`${rel}: every mention links surfaced-scope.md`, lines.every((l) => /surfaced-scope\.md/.test(l)));
+  ok(`${rel}: no "served by the capture cluster" dangling pointer`, lines.every((l) => !/served by the capture cluster/.test(l)));
+}
+
+// Capture e UAT seguono la stessa regola
+const capture = read(`${SK}/trailhead-capture/references/capture.md`);
+// #330: capture.md no longer links the full core; it states the routing inline and
+// capture-core.md carries drift markers on the surfaced-scope.md rules it restates.
+ok('capture: a mid-ticket capture states the surfaced-scope routing inline', /\*\*A capture fired mid-ticket\*\*[^\n]*the current map[^\n]*Surfaced from:/.test(capture));
+ok('capture-core: surfaced-scope.md rules are drift-stamped', /<!-- core: surfaced-scope\.md \|/.test(read(`${SK}/_shared/capture-core.md`)));
+const uat = read(`${SK}/_shared/techniques/acceptance-testing.md`);
+ok('uat: the failing-step follow-up lands per surfaced-scope.md', /On a failing step[^\n]*surfaced-scope\.md/.test(uat));
+
+console.log(`surfaced-scope-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

@@ -160,7 +160,9 @@ function readCodexModels(codexHome) {
     const globalCfg = readJSON(path.join(codexHome, 'trailhead', 'config.json')) || {};
     const globalCodex = globalCfg.models && typeof globalCfg.models === 'object' && typeof globalCfg.models.codex === 'object' && globalCfg.models.codex ? globalCfg.models.codex : {};
     const projectCodex = projectCfg.models && typeof projectCfg.models === 'object' && typeof projectCfg.models.codex === 'object' && projectCfg.models.codex ? projectCfg.models.codex : {};
-    return { ...globalCodex, ...projectCodex };
+    // #323: una layer con plan ma senza grill implica grill = plan, prima del merge.
+    const { withImplicitGrill } = require(path.join(SRC, 'hooks', 'lib', 'model-defaults-review.js'));
+    return { ...withImplicitGrill(globalCodex), ...withImplicitGrill(projectCodex) };
   } catch {
     return {};
   }
@@ -246,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
@@ -260,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', 'mockup-link.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
@@ -613,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);
@@ -686,12 +693,12 @@ function installCodex(configDir, { useSymlink }) {
     featureManual = true;
   }
 
-  // Per-technique agent registry: project ALL 8 committed agents
+  // Per-technique agent registry: project ALL 9 committed agents
   // (readAgentDefs, sourced from plugins/trailhead/agents/*.md) as
   // trailhead-<technique>.toml under the real ~/.codex/agents/ dir, uniformly.
-  // A keyed technique (plan/execute/research/review/debug/verify/codebase-map)
+  // A keyed technique (plan/execute/research/review/debug/verify/codebase-map/grill)
   // carries its models.codex.<key> pin (merged project + global config) when
-  // set, else is pin-less; the 1 keyless agent (fix) is always pin-less.
+  // set, else is pin-less; fix tracks the models.codex.execute pin.
   // Sweep only trailhead's own files first, so a stale pin from a prior
   // install (or a removed technique) never lingers, without touching the
   // user's other custom-agent TOMLs.