@marcomigozzi/trailhead 0.16.0 → 0.17.0

package/bin/capture-action.test.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+// Test for #334: the composite Action actions/capture is a thin wrapper over the capture
+// helper. Checks the input/output mirror, injection safety, the run block against a stub
+// helper, and the docs. Plain asserts, no framework, no YAML dependency.
+// Run: node bin/capture-action.test.js
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const root = path.resolve(__dirname, '..');
+const actionPath = path.join(root, 'actions', 'capture', 'action.yml');
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+const eq = (name, a, b) => { assert.deepStrictEqual(a, b, name); passed++; };
+const EMDASH = String.fromCharCode(0x2014);
+
+const yml = fs.readFileSync(actionPath, 'utf8');
+const lines = yml.split('\n');
+
+// Top-level keys under a section (2-space indented names) of the minimal YAML.
+function sectionKeys(name) {
+  const i = lines.findIndex((l) => l === `${name}:`);
+  ok(`action.yml has a ${name}: section`, i >= 0);
+  const keys = [];
+  for (let j = i + 1; j < lines.length; j++) {
+    if (lines[j] !== '' && !lines[j].startsWith(' ')) break;
+    const m = /^ {2}([A-Za-z0-9_-]+):/.exec(lines[j]);
+    if (m) keys.push(m[1]);
+  }
+  return keys;
+}
+
+// Mirror
+eq('inputs mirror the helper flags plus token',
+  sectionKeys('inputs').sort(),
+  ['body', 'body-file', 'dedupe-key', 'map', 'no-dashboard', 'of', 'repo', 'title', 'token', 'trigger', 'type', 'unverified']);
+eq('outputs are issue, url, status', sectionKeys('outputs').sort(), ['issue', 'status', 'url']);
+for (const name of ['issue', 'url', 'status']) {
+  ok(`output ${name} reads the capture step`, yml.includes(`value: \${{ steps.capture.outputs.${name} }}`));
+}
+ok('composite action', /^ {2}using: composite$/m.test(yml));
+ok('the step has id: capture', /^ {4}- id: capture$/m.test(yml));
+ok('description notes issues: write', /issues: write/.test(yml.split('\ninputs:')[0]));
+ok('branding present', /^branding:/m.test(yml));
+
+// Extract the literal run block (fixed indentation: `run: |` then 8-space lines).
+const runIdx = lines.findIndex((l) => /^ {6}run: \|$/.test(l));
+assert.ok(runIdx >= 0, 'run: | literal block not found in action.yml');
+const runLines = [];
+for (let j = runIdx + 1; j < lines.length; j++) {
+  if (lines[j] === '') { runLines.push(''); continue; }
+  if (!lines[j].startsWith('        ')) break;
+  runLines.push(lines[j].slice(8));
+}
+const script = runLines.join('\n');
+ok('run block is non-empty', script.trim().length > 0);
+
+// Injection safety
+ok('no ${{ expression inside the run script', !script.includes('${{'));
+ok('inputs reach the script through env:', /^ {6}env:$/m.test(yml) && /INPUT_BODY: \$\{\{ inputs\.body \}\}/.test(yml));
+
+// Runtime against a stub helper
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'capture-action-'));
+const actionDir = path.join(tmp, 'actions', 'capture');
+const tplDir = path.join(tmp, 'plugins', 'trailhead', 'templates');
+fs.mkdirSync(actionDir, { recursive: true });
+fs.mkdirSync(tplDir, { recursive: true });
+fs.writeFileSync(path.join(tmp, 'run.sh'), script);
+fs.writeFileSync(path.join(tplDir, 'trailhead-capture.js'), `
+const fs = require('fs');
+fs.writeFileSync(process.env.STUB_ARGV_FILE, JSON.stringify({ argv: process.argv.slice(2), token: process.env.GH_TOKEN || null }));
+if (process.env.STUB_RAW !== undefined) process.stdout.write(process.env.STUB_RAW);
+else console.log(process.env.STUB_JSON || '{"status":"created","issue":7,"url":"https://github.com/o/r/issues/7"}');
+process.exit(Number(process.env.STUB_EXIT || 0));
+`);
+
+const baseInputs = { INPUT_TYPE: 'bug', INPUT_TITLE: 'T', INPUT_REPO: 'o/r', INPUT_TOKEN: 'tok' };
+function run(inputs, stub = {}) {
+  const out = path.join(tmp, 'output.txt');
+  const argvFile = path.join(tmp, 'argv.json');
+  fs.rmSync(out, { force: true });
+  fs.rmSync(argvFile, { force: true });
+  const env = {
+    PATH: process.env.PATH,
+    GITHUB_ACTION_PATH: actionDir,
+    GITHUB_OUTPUT: out,
+    STUB_ARGV_FILE: argvFile,
+    GH_TOKEN: inputs.INPUT_TOKEN || '',
+    ...inputs,
+    ...stub,
+  };
+  const r = spawnSync('bash', ['--noprofile', '--norc', '-eo', 'pipefail', path.join(tmp, 'run.sh')], { env, encoding: 'utf8' });
+  const outputs = {};
+  if (fs.existsSync(out)) {
+    for (const l of fs.readFileSync(out, 'utf8').split('\n')) {
+      const m = /^([a-z]+)=(.*)$/.exec(l);
+      if (m) outputs[m[1]] = m[2];
+    }
+  }
+  const seen = fs.existsSync(argvFile) ? JSON.parse(fs.readFileSync(argvFile, 'utf8')) : null;
+  return { status: r.status, outputs, seen, stderr: r.stderr };
+}
+
+let r = run(baseInputs);
+eq('minimal argv: empty optionals omitted', r.seen.argv, ['--type', 'bug', '--title', 'T', '--repo', 'o/r']);
+eq('exit 0 on created', r.status, 0);
+eq('outputs from the JSON line', r.outputs, { issue: '7', url: 'https://github.com/o/r/issues/7', status: 'created' });
+eq('GH_TOKEN reaches the helper', r.seen.token, 'tok');
+
+r = run({ ...baseInputs, INPUT_BODY: 'a\nb "c" $HOME\n', INPUT_BODY_FILE: 'f.md', INPUT_MAP: '5', INPUT_OF: '9', INPUT_TRIGGER: 'x y',
+  INPUT_UNVERIFIED: 'true', INPUT_DEDUPE_KEY: 'k1', INPUT_NO_DASHBOARD: 'true' });
+eq('full argv maps 1:1, multi-line body intact, booleans bare',
+  r.seen.argv,
+  ['--type', 'bug', '--title', 'T', '--body', 'a\nb "c" $HOME\n', '--body-file', 'f.md', '--repo', 'o/r', '--map', '5', '--of', '9',
+    '--trigger', 'x y', '--unverified', '--dedupe-key', 'k1', '--no-dashboard']);
+
+r = run({ ...baseInputs, INPUT_UNVERIFIED: 'false', INPUT_NO_DASHBOARD: '' });
+ok('false/empty booleans are absent', !r.seen.argv.includes('--unverified') && !r.seen.argv.includes('--no-dashboard'));
+
+r = run(baseInputs, { STUB_JSON: '{"status":"existing"}' });
+eq('status only when JSON lacks issue/url', r.outputs, { issue: '', url: '', status: 'existing' });
+eq('existing exits 0', r.status, 0);
+
+for (const code of [3, 1, 2]) {
+  r = run(baseInputs, { STUB_EXIT: String(code), STUB_JSON: `{"status":"x${code}","issue":4,"url":"u"}` });
+  eq(`helper exit ${code} propagates`, r.status, code);
+  eq(`status still written on exit ${code}`, r.outputs.status, `x${code}`);
+}
+
+for (const [label, raw] of [['malformed', 'not json\n'], ['empty', '']]) {
+  r = run(baseInputs, { STUB_RAW: raw, STUB_EXIT: '3' });
+  eq(`${label} stdout never masks exit 3`, r.status, 3);
+  eq(`${label} stdout leaves outputs empty`, { issue: r.outputs.issue || '', url: r.outputs.url || '', status: r.outputs.status || '' }, { issue: '', url: '', status: '' });
+  r = run(baseInputs, { STUB_RAW: raw, STUB_EXIT: '0' });
+  eq(`${label} stdout with exit 0 exits 1`, r.status, 1);
+}
+
+fs.rmSync(tmp, { recursive: true, force: true });
+
+// Docs
+const readme = fs.readFileSync(path.join(root, 'README.md'), 'utf8');
+const readmeIt = fs.readFileSync(path.join(root, 'README.it.md'), 'utf8');
+for (const [name, doc] of [['README.md', readme], ['README.it.md', readmeIt]]) {
+  ok(`${name} names the Action`, doc.includes('ToRvaLDz/trailhead/actions/capture@'));
+  ok(`${name} names issues: write`, doc.includes('issues: write'));
+  ok(`${name} names dedupe-key`, doc.includes('dedupe-key'));
+}
+const capDoc = fs.readFileSync(path.join(root, 'plugins', 'trailhead', 'skills', 'trailhead-capture', 'references', 'capture.md'), 'utf8');
+ok('capture.md names the Action', capDoc.includes('actions/capture'));
+for (const [name, text] of [['action.yml', yml], ['README.md', readme], ['README.it.md', readmeIt], ['capture.md', capDoc], ['test', fs.readFileSync(__filename, 'utf8').replace(/String\.fromCharCode\(0x2014\)/g, '')]]) {
+  ok(`no em-dash in ${name}`, !text.includes(EMDASH));
+}
+ok('real helper path used by the run block exists',
+  fs.existsSync(path.join(root, 'actions/capture', '../../plugins/trailhead/templates/trailhead-capture.js')));
+for (const [name, doc] of [['README.md', readme], ['README.it.md', readmeIt]]) {
+  const keys = [...doc.matchAll(/^\s*dedupe-key: (.+)$/gm)].map((m) => m[1]);
+  ok(`${name} has a dedupe-key example`, keys.length > 0);
+  for (const k of keys) {
+    ok(`${name} dedupe-key example avoids unsafe contexts`, !/github\.(ref_name|workflow|head_ref|ref)\b/.test(k));
+    // job ids are [A-Za-z0-9_-]; run_id and run_number are digits
+    const resolved = k.replace(/\$\{\{\s*github\.(job|run_id|run_number)\s*\}\}/g, 'x1');
+    ok(`${name} dedupe-key example matches the helper regex`, /^[A-Za-z0-9._:-]{1,100}$/.test(resolved));
+  }
+}
+console.log(`capture-action.test.js: ${passed} checks passed`);

package/bin/capture-docs.test.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Docs test for #332: capture.md documents the scripted capture helper (CLI, statuses,
+// exit codes, trust, idea as fog, dedupe, dashboard). Plain asserts, no framework.
+// Run: node bin/capture-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const root = path.resolve(__dirname, '..');
+const doc = fs.readFileSync(path.join(root, 'plugins', 'trailhead', 'skills', 'trailhead-capture', 'references', 'capture.md'), 'utf8');
+const start = doc.indexOf('## Scripted capture for automations');
+const section = start < 0 ? '' : doc.slice(start);
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+ok('capture.md has the scripted capture section', section !== '');
+ok('names the helper', section.includes('trailhead-capture.js'));
+for (const flag of ['--type', '--title', '--body-file', '--repo', '--map', '--of', '--trigger', '--unverified', '--dedupe-key', '--no-dashboard']) {
+  ok(`names ${flag}`, section.includes(flag));
+}
+for (const status of ['created', 'existing', 'partial', 'error', 'usage']) {
+  ok(`documents status ${status}`, section.includes(`"status":"${status}"`));
+}
+ok('documents exit codes 0, 1, 2 and 3', ['exit 0', 'exit 1', 'exit 2', 'exit 3'].every((c) => section.includes(c)));
+ok('partial names prune', /partial[^]*\/trailhead:prune/.test(section));
+ok('trust: allowlist is the repo variable, not the local env', section.includes('TRAILHEAD_LABEL_ALLOWLIST') && /never consults its local environment/.test(section));
+ok('trust: installation tokens are verified post-create', section.includes('github-actions[bot]'));
+ok('idea is parked fog', /`idea` is parked fog/.test(section) && section.includes('`trailhead:fog`'));
+ok('dedupe: marker, cap fallback and the lag residual', section.includes('trailhead-dedupe') && section.includes('1000-result cap') && /search-index lag/.test(section));
+ok('dashboard rule: whiteboard only, update-only', /whiteboard ticket refreshes the dashboard/.test(section) && section.includes('--update-only'));
+ok('no em-dash', !doc.includes(String.fromCharCode(0x2014)));
+console.log(`capture-docs.test.js: ${passed} checks passed`);

package/bin/config-dir-templates-docs.test.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Docs test: il lookup di <templates> negli skill rispetta CLAUDE_CONFIG_DIR (npm install),
+// quindi nessun percorso nudo ~/.claude/trailhead/templates; il candidato Codex resta.
+// Plain asserts, no framework. Run: node bin/config-dir-templates-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');
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const walk = (dir) => fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+  e.isDirectory() ? walk(path.join(dir, e.name)) : [path.join(dir, e.name)]);
+// Radici doc che il motore legge: skill, agent e comandi
+const DOC_ROOTS = ['skills', 'agents', 'commands'].map((d) => path.join(root, 'plugins/trailhead', d));
+const files = DOC_ROOTS.flatMap(walk).filter((f) => f.endsWith('.md'));
+
+// Ogni grafia nuda della home: ~ o $HOME (la forma buona ha `}` dopo .claude, quindi non combacia)
+const BARE = /(?:~|\$HOME)\/\.claude\/trailhead\/templates/g;
+const GOOD = '${CLAUDE_CONFIG_DIR:-~/.claude}/trailhead/templates/';
+const CODEX = '~/.codex/skills/trailhead/templates/';
+
+for (const f of files) {
+  const rel = path.relative(root, f);
+  ok(`${rel}: no bare ~/.claude/trailhead/templates`, !(fs.readFileSync(f, 'utf8').match(BARE)));
+}
+
+// Siti noti: candidato Claude con CLAUDE_CONFIG_DIR, candidato Codex intatto
+for (const rel of [
+  'trailhead-work/SKILL.md',
+  '_shared/techniques.md',
+  '_shared/teamwork.md',
+  'trailhead-manage/references/auditing.md',
+]) {
+  const t = fs.readFileSync(path.join(SKILLS, rel), 'utf8');
+  ok(`${rel}: config-dir candidate present`, t.includes(GOOD));
+  ok(`${rel}: codex candidate untouched`, t.includes(CODEX));
+}
+const cfg = fs.readFileSync(path.join(SKILLS, '_shared/configuration-reference.md'), 'utf8');
+ok('configuration-reference: statusline lookup uses config dir', cfg.includes(GOOD + 'statusline-trailhead.sh'));
+
+// #319: l'install della statusline va nella config dir, non in ~/.claude nudo
+const stl = cfg.split('\n').find((l) => l.includes('On **Enable**, install it')) || '';
+ok('configuration-reference: statusline install line found', stl.length > 0);
+ok('configuration-reference: statusline target and settings use config dir',
+  stl.includes('${CLAUDE_CONFIG_DIR:-~/.claude}/statusline-trailhead.sh') && stl.includes('${CLAUDE_CONFIG_DIR:-~/.claude}/settings.json'));
+ok('configuration-reference: statusline install has no bare ~/.claude target or $HOME command',
+  !/(?<!:-)~\/\.claude\/(settings\.json|statusline-trailhead\.sh)/.test(stl) && !stl.includes('$HOME/.claude'));
+
+console.log(`config-dir-templates-docs.test.js: ${passed} checks passed`);

package/bin/decision-builds-docs.test.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// Docs test: una decision chiusa porta il suo lavoro nei build (riga `Builds:`), il grill
+// che risolve un ticket fa lo stesso, e l'audit segnala le decisioni chiuse senza build.
+// Plain asserts, no framework. Run: node bin/decision-builds-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);
+
+// Sezione dal suo heading fino al prossimo heading dello stesso livello (o superiore).
+const section = (text, headingRe) => {
+  const m = headingRe.exec(text);
+  if (!m) return '';
+  const level = m[0].match(/^#+/)[0].length;
+  const rest = text.slice(m.index + m[0].length);
+  const next = new RegExp(`^#{1,${level}} `, 'm').exec(rest);
+  return next ? rest.slice(0, next.index) : rest;
+};
+
+const SK = 'plugins/trailhead/skills';
+
+// Motore decision
+const engines = read(`${SK}/trailhead-work/references/ticket-engines.md`);
+const dec = section(engines, /^## `decision`.*$/m);
+ok('decision engine: section found', dec.length > 0);
+ok('decision engine: a build follow-through step', /Carry it into build/.test(dec));
+ok('decision engine: records a `Builds:` line', dec.includes('`Builds:'));
+ok('decision engine: allows `Builds: none` only with a reason', /`Builds: none \(<why>\)`/.test(dec));
+ok('decision engine: links existing tickets or creates build tickets', /existing/i.test(dec) && /create-then-wire/.test(dec));
+ok('decision engine: the human confirms the build split in the final confirmation', /final confirmation/i.test(dec));
+ok('decision engine: no close without the line', /never `gh issue close`/i.test(dec));
+ok('decision engine: explains the fog that vanishes', /Not yet specified/.test(dec));
+ok('decision engine: no em-dash', !dec.includes(EM));
+
+// Work the map
+const work = read(`${SK}/trailhead-work/SKILL.md`);
+const step5 = (work.match(/^5\. Record the resolution:.*$/m) || [''])[0];
+ok('work step 5: decision close waits on the `Builds:` line', step5.includes('`Builds:') && /Carry it into build/.test(step5));
+
+// Grill su un ticket
+const chart = read(`${SK}/trailhead-chart/SKILL.md`);
+const grill = (chart.match(/^Run a standalone \*\*Grilling\*\*.*$/m) || [''])[0];
+ok('grill: resolving a decision ticket carries it into build', /Carry it into build/.test(grill) && grill.includes('`Builds:'));
+
+// Audit
+const audit = read(`${SK}/trailhead-manage/references/auditing.md`);
+const light = (audit.match(/^\*\*Light check\*\*.*$/m) || [''])[0];
+ok('audit light check: flags a closed decision with no build', /no build/i.test(light) && light.includes('`Builds:'));
+ok('audit light check: an older decision counts a build that links it', /links? (it|back)/i.test(light));
+const report = section(audit, /^## 8\. Report$/m);
+ok('audit report: lists decisions with no build', /no build/i.test(report));
+const props = section(audit, /^## 9\. Proposals.*$/m);
+ok('audit proposals: open the missing build tickets on a yes', /No build/.test(props) && /build/.test(props) && /`Builds:`/.test(props));
+
+// Docs utente
+const readme = read('README.md');
+ok('README: decision engine leaves build tickets', /`decision` diverges options then grills to choose, then opens the build tickets/.test(readme));
+ok('README: audit names decisions with no build', /decisions closed with no build/i.test(readme));
+const readmeIt = read('README.it.md');
+ok('README.it: decision engine leaves build tickets', /`decision` dirama le opzioni poi fa grilling per scegliere, poi apre i ticket build/.test(readmeIt));
+ok('README.it: audit names decisions with no build', /decisioni chiuse senza build/i.test(readmeIt));
+const wf = read('site/src/content/docs/docs/workflow.md');
+ok('workflow.md: decision engine leaves build tickets', /`decision` diverges options then grills to choose, then opens the build tickets/.test(wf));
+const manage = read('site/src/content/docs/docs/commands/manage.md');
+ok('manage.md: audit names decisions with no build', /closed with no build/i.test(manage));
+for (const [n, t] of [['README.md', readme], ['README.it.md', readmeIt], ['workflow.md', wf], ['manage.md', manage]]) {
+  ok(`${n}: no em-dash`, !t.includes(EM));
+}
+
+console.log(`decision-builds-docs.test.js: ${passed} checks passed`);

package/bin/engine-route-docs.test.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+// Docs test per #325: ogni step del motore decide inline vs dispatch con
+// model-route.js, non con la regola in prosa. Il testo canonico vive una volta
+// in techniques.md; ogni punto di dispatch ha un gate imperativo che lo richiama.
+// Run: node engine-route-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 = (rel) => fs.readFileSync(path.join(skills, rel), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const SECTION = '**Route every step through model-route.js.**';
+const SECTION_NAME = 'Route every step through model-route.js';
+
+// --- Parte A: la sezione canonica in techniques.md -----------------------------------
+{
+  const techniques = read('_shared/techniques.md');
+  const at = techniques.indexOf(SECTION);
+  ok('A: techniques.md has the canonical routing paragraph', at !== -1);
+  const sec = at === -1 ? '' : techniques.slice(at, techniques.indexOf('\n\n', at));
+  const has = (...needles) => needles.every((n) => sec.includes(n));
+  ok('A: the command with every flag',
+    has('model-route.js <key> --session <your full model id>', '--session-effort', '--host codex', '--no-subagents', '<project root>'));
+  ok('A: the two-path <hooks> lookup', has('../../hooks/lib/', '../trailhead/hooks/lib/', 'model-defaults-review.js'));
+  ok('A: where the model id comes from', has('The exact model ID is', 'pass `unknown` only if it is truly absent'));
+  ok('A: the key per step', has(
+    'Plan -> `plan`', 'Execute -> `execute`', 'Fix -> `execute`', 'Code review -> `review`',
+    'Goal-backward verification -> `verify`', 'Research -> `research`', 'Debug -> `debug`',
+    'Codebase map -> `codebase-map`', 'Grilling -> `grill`'));
+  ok('A: Fix spawns trailhead-fix in place of the returned agent', has('spawn `trailhead-fix` in place of the returned `agent`'));
+  ok('A: Grilling keeps its own section', has('**Who runs a round**'));
+  ok('A: route inline, suggest and warning', has('`route: inline`', '`suggest`', '`warning`'));
+  ok('A: route dispatch uses agent and alias verbatim', has('`route: dispatch`', 'use its `agent` and `alias` verbatim'));
+  ok('A: no hand decision', has('Never decide inline versus dispatch by hand', 'never read the config yourself'));
+  ok('A: an unregistered agent runs inline', has('not registered', 'inline'));
+  ok('A: the lean exception', has('accepted `lean` skip'));
+  ok('A: the autonomous-run exception dispatches with no model override on an inline route',
+    has('more than one slot', 'no model override'));
+  ok('A: Codex spawns by agent_type, with a null alias', has('`agent_type=<agent>` on Codex', '`alias` is null'));
+  ok('A: Claude Code passes alias as the Agent model override', has('`alias` as the `Agent` model override on Claude Code'));
+  const rule = sec.indexOf('Never decide inline versus dispatch by hand');
+  const lean = sec.indexOf('accepted `lean` skip');
+  const auto = sec.indexOf('more than one slot');
+  ok('A: both exclusions are stated after the rule, inside the paragraph',
+    rule !== -1 && lean > rule && auto > rule && sec.indexOf('Two cases sit outside the route') > rule);
+  ok('A: the helper still runs in the autonomous case', sec.slice(auto).includes('the helper is still run'));
+  const dispatch = techniques.split('\n')[4] || '';
+  ok('A: the dispatch paragraph points at the routing paragraph', dispatch.includes(SECTION_NAME));
+  ok('A: the dispatch paragraph no longer restates the hand rule',
+    !dispatch.includes('running inline instead only when') && !dispatch.includes('Keep the inline-vs-subagent decision on the full id'));
+}
+
+// --- Parte B: il gate a ogni punto di dispatch ---------------------------------------
+const gateOk = (text, key) =>
+  text.includes(`model-route.js ${key} --session <your full model id> <project root>`) &&
+  text.includes('obey its `route`') &&
+  text.includes('never decide inline versus dispatch by hand') &&
+  text.includes(SECTION_NAME);
+
+{
+  const engines = read('trailhead-work/references/ticket-engines.md');
+  const lines = engines.split('\n');
+  const line = (prefix) => lines.find((l) => l.startsWith(prefix)) || '';
+  ok('B: build Plan gates on plan', gateOk(line('2. **Plan**:'), 'plan'));
+  ok('B: build Execute Dispatch gates on execute', gateOk(line('   - **Dispatch.** Spawn the **`trailhead-executor`**'), 'execute'));
+  ok('B: bug Diagnose gates on debug', gateOk(line('2. **Diagnose**:'), 'debug'));
+  const fix = line('   - **Dispatch.** Spawn the **`trailhead-fix`**');
+  ok('B: bug Fix Dispatch gates on execute and spawns trailhead-fix', gateOk(fix, 'execute') && fix.includes('`trailhead-fix`'));
+  ok('B: ticket-engines.md no longer restates the hand rule', !engines.includes('Inline only when the resolved model'));
+  const GATE = '**First, route it.**';
+  for (const [name, l] of [['Plan', line('2. **Plan**:')], ['Execute', line('   - **Dispatch.** Spawn the **`trailhead-executor`**')],
+    ['Diagnose', line('2. **Diagnose**:')], ['Fix', fix]]) {
+    ok(`B: ${name} spawns by agent_type on Codex`, l.includes('agent_type='));
+    const g = l.indexOf(GATE);
+    ok(`B: ${name} gate comes before any lean-skip or exception wording`, g !== -1 && (l.indexOf('`lean`') === -1 || g < l.indexOf('`lean`')));
+  }
+}
+
+for (const [file, key, agent] of [
+  ['code-review.md', 'review', 'trailhead-code-review'],
+  ['verify.md', 'verify', 'trailhead-verify'],
+  ['research.md', 'research', 'trailhead-research'],
+  ['debug.md', 'debug', 'trailhead-debug'],
+  ['codebase-map.md', 'codebase-map', 'trailhead-codebase-map'],
+]) {
+  const text = read(`_shared/techniques/${file}`);
+  const gateAt = text.indexOf('**First, route it.**');
+  const dispatchAt = text.indexOf(`**\`${agent}\`** agent`);
+  const gate = gateAt === -1 ? '' : text.slice(gateAt, text.indexOf('\n', gateAt));
+  ok(`B: ${file} has a routing gate before its dispatch sentence`, gateAt !== -1 && dispatchAt !== -1 && gateAt < dispatchAt);
+  ok(`B: ${file} gate runs model-route.js ${key}`, gateOk(gate, key));
+  ok(`B: ${file} gate exempts the dispatched ${agent}`, gate.includes(`If you are the \`${agent}\` agent, skip this gate`));
+  ok(`B: ${file} no longer restates the hand rule`, !text.includes('inline only when the resolved model'));
+  ok(`B: ${file} gate spawns by agent_type on Codex`, gate.includes('agent_type=<agent>'));
+  ok(`B: ${file} gate points at the canonical paragraph`, gate.includes('Route every step through model-route.js'));
+  ok(`B: ${file} gate comes before any lean-skip wording`, text.indexOf('`lean`') === -1 || gateAt < text.indexOf('`lean`'));
+}
+
+// --- Parte B2: auto.md ---------------------------------------------------------------
+{
+  const auto = read('trailhead-work/references/auto.md');
+  const line = auto.split('\n').find((l) => l.startsWith('- **Background dispatch, never inline.**')) || '';
+  ok('B: auto.md still dispatches every step in the background', line.includes('background subagent'));
+  ok('B: auto.md runs the helper per step', line.includes('model-route.js <key> --session <your full model id> <project root>') && line.includes('Route every step through model-route.js'));
+  ok('B: auto.md spawns with no model override on an inline route', line.includes('`route: inline`') && line.includes('no model override'));
+}
+
+// --- Parte B3: rifiniture della review di #325 --------------------------------------
+{
+  const cr = read('_shared/techniques/code-review.md');
+  ok('B: code-review.md no longer says a lean skip is the only inline review', !cr.includes('only inline review'));
+  ok('B: code-review.md says the review runs inline on route: inline', cr.includes('in the session on `route: inline`'));
+  const audit = read('trailhead-manage/references/auditing.md');
+  ok('B: auditing.md routes verify once per run through model-route.js',
+    audit.includes('routes `verify` once per run through `model-route.js`') && audit.includes('Route every step through model-route.js'));
+  const agent = fs.readFileSync(path.join(root, 'plugins', 'trailhead', 'agents', 'trailhead-codebase-map.md'), 'utf8');
+  ok('B: the codebase-map agent no longer claims it has no model key', !agent.includes('no dedicated model key') && agent.includes('config.models.codebase-map'));
+  const cfg = read('_shared/configuration.md');
+  const ref = read('_shared/configuration-reference.md');
+  ok('B: configuration docs say every key routes through model-route.js',
+    !cfg.includes('every model key runs as a subagent') && !ref.includes('Every model key runs as a subagent') &&
+    cfg.includes('every model key routes through `model-route.js`') && ref.includes('Every model key routes through `model-route.js`'));
+}
+
+// --- Parte C: la config descrive l'helper, non una decisione a mano -------------------
+{
+  const cfg = read('_shared/configuration.md');
+  const ref = read('_shared/configuration-reference.md');
+  ok('C: configuration.md lets the helper decide', cfg.includes('model-route.js') && !cfg.includes('Run Execute inline only when'));
+  const bullet = (k) => ref.split('\n').find((l) => l.startsWith(`- \`${k}\` →`)) || '';
+  ok('C: configuration-reference.md plan bullet points at the helper', bullet('plan').includes('model-route.js') && !bullet('plan').includes('inline only when'));
+  ok('C: configuration-reference.md execute bullet points at the helper', bullet('execute').includes('model-route.js') && !bullet('execute').includes('inline in the session instead when'));
+}
+
+// --- Parte D: l'helper copre ogni chiave nominata ------------------------------------
+{
+  const { AGENT_OF } = require(path.join(root, 'plugins', 'trailhead', 'hooks', 'lib', 'model-route.js'));
+  for (const key of ['plan', 'execute', 'review', 'verify', 'research', 'debug', 'codebase-map', 'grill']) {
+    ok(`D: model-route.js knows ${key} on both hosts`, !!AGENT_OF.claude[key] && !!AGENT_OF.codex[key]);
+  }
+}
+
+console.log(`engine-route-docs.test.js: ${passed} checks passed`);

package/bin/fog-vs-ticket-docs.test.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// Docs test: il charting apre come ticket (bloccati se serve) le aree con una Question
+// già scrivibile, lascia in fog solo il resto; dopo ogni risoluzione la fog viene
+// riesaminata tutta; a frontier vuota si propone un gruppo di voci da graduare.
+// Plain asserts, no framework. Run: node bin/fog-vs-ticket-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 line = (text, re) => (text.match(re) || [''])[0];
+
+const SK = 'plugins/trailhead/skills';
+
+// Charting: il criterio ticket vs fog
+const charting = read(`${SK}/trailhead-chart/references/charting.md`);
+const step4 = line(charting, /^4\. \*\*Create the tickets you can specify now\*\*.*$/m);
+ok('charting step 4: names the ticket-or-fog test', /Ticket or fog/.test(step4));
+ok('charting step 4: a writable Question makes a ticket even when blocked', /Question/.test(step4) && /blocked/.test(step4) && /not a reason to leave it in the fog/i.test(step4));
+ok('charting step 4: fog only when the question cannot be phrased yet', /cannot phrase/i.test(step4));
+ok('charting step 4: fog when an open decision could reshape the question, and the entry says which', /reshape/i.test(step4) && /names? (that|the) (decision|ticket)/i.test(step4));
+ok('charting step 4: the 100 sub-issue cap is the only volume brake', /100/.test(step4));
+ok('charting: no em-dash', !charting.includes(EM));
+
+// Work the map: riesame di tutta la fog dopo ogni risoluzione
+const work = read(`${SK}/trailhead-work/SKILL.md`);
+const step6 = line(work, /^6\. Add newly-surfaced tickets.*$/m);
+ok('work step 6: re-scans every fog entry', /every entry/i.test(step6) && /Not yet specified/.test(step6));
+ok('work step 6: applies the charting test', /Ticket or fog/.test(step6));
+ok('work step 6: proposes the graduations as one batch', /one batch/i.test(step6));
+
+// Handoff a frontier vuota: un gruppo, non una voce
+const handoff = read(`${SK}/_shared/session-handoff.md`);
+const empty = line(handoff, /^\s*\*\*If the frontier is empty\*\*.*$/m);
+ok('handoff: empty frontier proposes a batch of ripe fog entries', /batch/i.test(empty) && /Ticket or fog/.test(empty));
+ok('handoff: no em-dash', !handoff.includes(EM));
+
+// Docs utente
+const docs = [
+  ['README.md', read('README.md'), false],
+  ['README.it.md', read('README.it.md'), true],
+  ['concepts.md', read('site/src/content/docs/docs/concepts.md'), false],
+];
+for (const [n, t, it] of docs) {
+  ok(`${n}: fog no longer clears "one at a time"`, it ? !/una alla volta, finché non resta/.test(t) : !/ticket, one at a time, until nothing/.test(t));
+  ok(`${n}: a phrasable question is a ticket, blocked if needed`, it
+    ? /domanda già formulabile[^.]*ticket[^.]*bloccat/i.test(t)
+    : /question you can already phrase[^.]*ticket[^.]*blocked/i.test(t));
+  ok(`${n}: no em-dash`, !t.includes(EM));
+}
+
+console.log(`fog-vs-ticket-docs.test.js: ${passed} checks passed`);