@marcomigozzi/trailhead 0.15.0 → 0.16.0

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

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

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

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

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

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

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

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

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

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

package/bin/lib/codex-projection.js

@@ -113,7 +113,7 @@ Codex has a subagent toolkit: the multi_agent tools (\`spawn_agent\`, \`send_inp
 The engine's \`/clear\` is Codex's \`/new\` (start a fresh session). Command references in a handoff use the skill form (\`$trailhead work <n>\`).
 
 ## F. Lifecycle hooks (native Codex hooks)
-Codex has a hook bus, so trailhead's guardrails run as **real Codex hooks**, not degraded prose. The installer registers them in \`~/.codex/hooks.json\`: commit-guard, secret-guard, install-guard and body-guard as \`PreToolUse\` (matcher \`Bash\`) hooks that can veto the command before it runs (the four run in one process, a single \`trailhead-bash-guards.js --guards=commit,secret,install,body\` registration, so a Bash call pays one start-up instead of four), secret-read-guard as a \`PreToolUse\` (matcher \`Read|Bash\`) hook that denies reads of \`.env\`/\`.env.*\`/\`.secrets\`, the injection-scanner as a \`PostToolUse\` (matcher \`Bash\`) advisory, mockup-link-stop as a \`Stop\` hook (when your final reply asks to approve a mockup without carrying its link, it continues the turn so you rewrite the ask with the URL or file path in the prose), and check-update as a \`SessionStart\` hook. On Codex, file reads happen through shell commands rather than a native Read-tool event, so the secret-read guard's enforcement here runs via its **Bash** arm (protection is not lost); the \`Read\` half of its matcher is a Claude-Code-native path, registered on Codex too only so it fires without changes if a future Codex version adds an equivalent event. search-guard is Claude-Code-specific (it only prevents arming Claude's \`Read()\` deny rule under bypass permissions, a mechanism Codex lacks), so it is not projected to Codex at all. They use the same wire format they use on Claude Code (JSON on stdin, a \`decision\`/\`permissionDecision\` verdict on stdout), which Codex accepts. The host-independent git \`commit-msg\` hook is still installed at repo first-use as well (defence in depth), exactly as on Claude. Codex gates hooks behind \`features.hooks = true\` and reviews them for trust on first start: the installer enables the flag, and Codex will ask you to trust trailhead's hooks the next time it starts.
+Codex has a hook bus, so trailhead's guardrails run as **real Codex hooks**, not degraded prose. The installer registers them in \`~/.codex/hooks.json\`: commit-guard, secret-guard, install-guard, body-guard and labels-guard as \`PreToolUse\` (matcher \`Bash\`) hooks that can veto the command before it runs (the five run in one process, a single \`trailhead-bash-guards.js --guards=commit,secret,install,body,labels\` registration, so a Bash call pays one start-up instead of five), secret-read-guard as a \`PreToolUse\` (matcher \`Read|Bash\`) hook that denies reads of \`.env\`/\`.env.*\`/\`.secrets\`, the injection-scanner as a \`PostToolUse\` (matcher \`Bash\`) advisory, mockup-link-stop as a \`Stop\` hook (when your final reply asks to approve a mockup without carrying its link, it continues the turn so you rewrite the ask with the URL or file path in the prose), and check-update as a \`SessionStart\` hook. On Codex, file reads happen through shell commands rather than a native Read-tool event, so the secret-read guard's enforcement here runs via its **Bash** arm (protection is not lost); the \`Read\` half of its matcher is a Claude-Code-native path, registered on Codex too only so it fires without changes if a future Codex version adds an equivalent event. search-guard is Claude-Code-specific (it only prevents arming Claude's \`Read()\` deny rule under bypass permissions, a mechanism Codex lacks), so it is not projected to Codex at all. They use the same wire format they use on Claude Code (JSON on stdin, a \`decision\`/\`permissionDecision\` verdict on stdout), which Codex accepts. The host-independent git \`commit-msg\` hook is still installed at repo first-use as well (defence in depth), exactly as on Claude. Codex gates hooks behind \`features.hooks = true\` and reviews them for trust on first start: the installer enables the flag, and Codex will ask you to trust trailhead's hooks the next time it starts.
 
 ## G. Design / UI mockups: artifacts -> stitch offer, else local disk
 The \`artifacts\` mockup mode (a Design canvas Artifact built with Claude Code's \`Artifact\` tool; the legacy \`claude.ai/design\` value means the same) does not exist on Codex: there is no \`Artifact\` tool here. When \`config.design\` names it, follow the Prototype technique's fallback: **offer once to switch this project to \`design: stitch\`** (the Google Stitch MCP runs on Codex too), and only on decline produce a throwaway static HTML mockup next to the code (\`disk\`), link it from the ticket, and say why. Never try to create or edit an Artifact on Codex. \`config.design.approval\` still applies unchanged: \`explicit\` waits for the user's go-ahead before any UI code, \`auto\` surfaces the mockup and proceeds.
@@ -366,9 +366,9 @@ function codexVerbSkillPlan(codexHome, verbs) {
 // --- codexHookEntries -----------------------------------------------------
 // The guardrail hooks trailhead registers on Codex, as {event, matcher,
 // command} records. Commands run the copied hook scripts under hooksScriptsDir
-// via node, matching Claude's `node "<path>"` form. The four Bash guards
-// (commit, secret, install, body) are ONE registration, the merged
-// trailhead-bash-guards.js with `--guards=commit,secret,install,body` (a single
+// via node, matching Claude's `node "<path>"` form. The five Bash guards
+// (commit, secret, install, body, labels) are ONE registration, the merged
+// trailhead-bash-guards.js with `--guards=commit,secret,install,body,labels` (a single
 // node process per Bash call); secret-read is a separate PreToolUse hook. All
 // PreToolUse guards can veto; the injection-scanner
 // is a PostToolUse advisory; check-update runs at SessionStart. Reused by the
@@ -381,7 +381,7 @@ function codexVerbSkillPlan(codexHome, verbs) {
 function codexHookEntries(hooksScriptsDir) {
   const cmd = (name) => `node "${path.join(hooksScriptsDir, name)}"`;
   return [
-    { event: 'PreToolUse', matcher: 'Bash', command: `${cmd('trailhead-bash-guards.js')} --guards=commit,secret,install,body` },
+    { event: 'PreToolUse', matcher: 'Bash', command: `${cmd('trailhead-bash-guards.js')} --guards=commit,secret,install,body,labels` },
     { event: 'PreToolUse', matcher: 'Read|Bash', command: cmd('trailhead-secret-read-guard.js') },
     { event: 'PostToolUse', matcher: 'Bash', command: cmd('trailhead-issue-injection-scanner.js') },
     { event: 'Stop', matcher: '', command: cmd('trailhead-mockup-link-stop.js') },

package/bin/lib/codex-projection.test.js

@@ -173,8 +173,8 @@ const entries = codexHookEntries('/h');
 ok('codexHookEntries returns 5 entries', Array.isArray(entries) && entries.length === 5);
 const bashEntries = entries.filter((e) => e.event === 'PreToolUse' && e.matcher === 'Bash');
 ok('codexHookEntries: exactly one PreToolUse/Bash registration', bashEntries.length === 1);
-ok('codexHookEntries: the Bash entry is the merged hook with exactly --guards=commit,secret,install,body',
-  bashEntries[0].command === 'node "/h/trailhead-bash-guards.js" --guards=commit,secret,install,body');
+ok('codexHookEntries: the Bash entry is the merged hook with exactly --guards=commit,secret,install,body,labels',
+  bashEntries[0].command === 'node "/h/trailhead-bash-guards.js" --guards=commit,secret,install,body,labels');
 ok('codexHookEntries: no per-guard script is registered on its own', entries.every((e) =>
   !/trailhead-(commit|secret|install|search|body)-guard\.js/.test(e.command)));
 ok('codexHookEntries: secret-read-guard is PreToolUse/Read|Bash', entries.some((e) =>

package/bin/needs-you-docs.test.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Docs test for #282: the needs-you label (an autonomous run parks a ticket for the
+// human) is documented where the run, the claim and the substrate depend on it.
+// Plain asserts, no framework. Run: node bin/needs-you-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const plugin = path.resolve(__dirname, '..', 'plugins', 'trailhead');
+const read = (rel) => fs.readFileSync(path.join(plugin, rel), 'utf8');
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const auto = read('skills/trailhead-work/references/auto.md');
+const work = read('skills/trailhead-work/SKILL.md');
+const substrate = read('skills/_shared/substrate.md');
+const commands = read('skills/_shared/substrate-commands.md');
+
+for (const needle of ['trailhead:needs-you', 'trailhead-needs-you.js park', '`NEEDS YOU`', 'needs-you ticket', 'queue skips it', 'does not reconsider it', 'surviving blocking review concern', 'stale-base stop', 'a failing UAT setup'.replace('a failing', 'failing')]) {
+  ok(`auto.md names: ${needle}`, auto.includes(needle));
+}
+ok('auto.md no longer says "set aside" / "set-aside"', !/set[- ]aside|sets? (?:it|that|such a|the) (?:ticket )?aside|sets? .{0,20} aside/i.test(auto));
+
+const claimStep = (work.match(/^2\. Choose the ticket\..*$/m) || [''])[0];
+const quickBullet = (work.match(/^- \*\*Same isolation setup as `work`\.\*\*.*$/m) || [''])[0];
+const CLEAR = 'node <templates>/trailhead-needs-you.js clear --issue <n> --repo <owner/name>';
+ok('work claim step clears needs-you with the helper', claimStep.includes(CLEAR));
+ok('quick isolation bullet clears needs-you with the helper', quickBullet.includes(CLEAR));
+ok('work claim step has the by-hand fallback', claimStep.includes('gh issue edit <n> --remove-label trailhead:needs-you'));
+ok('a failed clear is reported, never blocking the claim (work)', /failed `clear` is reported to the user in one line but never blocks the claim/.test(claimStep));
+ok('a failed clear is reported, never blocking the claim (quick)', /failed `clear` is reported to the user in one line but never blocks the claim/.test(quickBullet));
+
+ok('substrate.md documents the label, off every run, on the human frontier', /\*\*`trailhead:needs-you`\*\*[\s\S]{0,900}not a frontier exclusion for humans/.test(substrate) && substrate.includes('twenty-one labels'));
+ok('substrate-commands.md ensures the label idempotently', commands.includes('gh label create trailhead:needs-you --color D93F0B --description "Needs you: an autonomous run parked it for the human" --force'));
+ok('substrate-commands.md documents park and clear', commands.includes('trailhead-needs-you.js park --issue <n> --reason <text> --repo <owner/name>') && commands.includes('trailhead-needs-you.js clear --issue <n> --repo <owner/name>'));
+ok('substrate-commands.md first-use list has twenty-one labels', /all twenty-one:[^\n]*`trailhead:needs-you`/.test(commands));
+
+for (const [name, text] of [['auto.md', auto], ['SKILL.md', work], ['substrate.md', substrate], ['substrate-commands.md', commands]]) {
+  ok(`${name}: no em-dash`, !text.includes(String.fromCharCode(0x2014)));
+}
+console.log(`needs-you-docs.test.js: ${passed} checks passed`);

package/bin/pick-stress-test-docs.test.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// Docs test: the agent never offers or acts on its own pick unchecked. The stress-test rule is
+// stated once (choices.md) and pointed at by grilling, the delegate option, auto and the Plan;
+// the Plan carries a Done-when coverage check, decision Diverge re-checks a framed option set,
+// and inbox never closes or answers someone else's issue without the user's yes.
+// Run: node pick-stress-test-docs.test.js
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const skills = path.join(__dirname, '..', 'plugins', 'trailhead', 'skills');
+const read = (rel) => fs.readFileSync(path.join(skills, rel), 'utf8');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const ANCHOR = 'Stress-test the pick before offering it';
+const DEFINITION = `**${ANCHOR}.**`;
+
+const walk = (dir) => fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+  e.isDirectory() ? walk(path.join(dir, e.name)) : [path.join(dir, e.name)]);
+const lineOf = (text, pred) => text.split('\n').find(pred);
+
+// 1. la definizione esiste una sola volta, in choices.md
+const defs = walk(skills).filter((f) => fs.readFileSync(f, 'utf8').includes(DEFINITION));
+ok('definition appears in exactly one file', defs.length === 1);
+ok('definition lives in choices.md', defs[0] === path.join(skills, '_shared', 'choices.md'));
+const choices = read('_shared/choices.md');
+ok('definition appears once', choices.split(DEFINITION).length === 2);
+
+// 2. la definizione porta i frammenti normativi
+const rule = lineOf(choices, (l) => l.includes(DEFINITION));
+for (const frag of [
+  'a recommended answer in grilling',
+  '`(Recommended)`',
+  'the delegate option',
+  'an option `auto` takes on its own',
+  'the edge case or failure mode where it breaks',
+  'checked against the code rather than assumed',
+  'the choices already settled',
+  'real holes, not manufactured doubt',
+  'One pass, no loop',
+  'present only that',
+  'Weak point:',
+  'still recommended because',
+  'conversation language',
+  'where no human sees it live',
+  'trivial or already-decided choice',
+]) ok(`rule carries: ${frag}`, rule.includes(frag));
+
+// 3. i call-site puntano alla regola senza ripeterla
+const pointer = (name, line) => {
+  ok(`${name} found`, !!line);
+  ok(`${name} references the anchor`, line.includes(ANCHOR));
+  ok(`${name} does not restate the rule`, !line.includes('manufactured doubt'));
+};
+const grilling = read('_shared/techniques/grilling.md');
+const gl = grilling.split('\n');
+const pickIdx = gl.findIndex((l) => l.startsWith('- **One question at a time, with your pick.**'));
+ok('grilling pick bullet found', pickIdx >= 0);
+pointer('grilling self-check bullet', gl[pickIdx + 1]);
+ok('grilling bullet keeps the per-question check', gl[pickIdx + 1].includes('by question number'));
+ok('grilling pick bullet points at the self-check', gl[pickIdx].includes('stress-tested per the next bullet'));
+pointer('delegate step 2', lineOf(choices, (l) => l.startsWith('2. The agent states **which option it would choose')));
+const auto = read('trailhead-work/references/auto.md');
+const autoLine = lineOf(auto, (l) => l.startsWith('- **Advisory / process choice**'));
+pointer('auto advisory choice', autoLine);
+ok('auto records the weak point', autoLine.includes('`Weak point:` line'));
+const engines = read('trailhead-work/references/ticket-engines.md');
+const plan = lineOf(engines, (l) => l.startsWith('2. **Plan**'));
+pointer('build Plan', plan);
+
+// 4. Plan: copertura del Done when prima di ready
+for (const frag of [
+  '**Coverage check before `ready`.**',
+  'every `Done when` criterion',
+  'a criterion no step delivers is a gap',
+  'return `needs_input`',
+  'the short inline plan too',
+]) ok(`plan carries: ${frag}`, plan.includes(frag));
+
+// 5. Diverge: un set di opzioni gia' inquadrato viene ricontrollato
+const diverge = lineOf(engines, (l) => l.startsWith('1. **Diverge'));
+ok('diverge found', !!diverge);
+ok('diverge no longer skips blindly', !diverge.includes('skip straight to grilling when it did.'));
+for (const frag of ['still current and complete', 'Decisions so far', 'status quo', '`OPTIONS` comment'])
+  ok(`diverge carries: ${frag}`, diverge.includes(frag));
+
+// 6. Inbox: nessuna chiusura o commento pubblico senza un si'
+const inbox = read('trailhead-chart/references/inbox.md');
+ok('inbox drops "on your own for clear ones"', !inbox.includes('on your own for clear ones'));
+const intro = lineOf(inbox, (l) => l.startsWith('For each issue in the first two sections'));
+for (const frag of ['propose a disposition', 'one list', 'explicit yes', 'never close', 'comment on', 'out-of-scope ruling'])
+  ok(`inbox intro carries: ${frag}`, intro.includes(frag));
+const dup = lineOf(inbox, (l) => l.startsWith('- **Duplicate.**'));
+for (const frag of ['what each one covers', 'partial overlap', 'not a duplicate'])
+  ok(`inbox duplicate carries: ${frag}`, dup.includes(frag));
+
+// 7. niente em-dash
+for (const rel of ['_shared/choices.md', '_shared/techniques/grilling.md', 'trailhead-work/references/auto.md',
+  'trailhead-work/references/ticket-engines.md', 'trailhead-chart/references/inbox.md'])
+  ok(`${rel} has no em-dash`, !read(rel).includes(String.fromCharCode(8212)));
+ok('this test has no em-dash', !fs.readFileSync(__filename, 'utf8').includes(String.fromCharCode(8212)));
+
+console.log(`pick-stress-test-docs.test.js: ${passed} checks passed`);

package/bin/trailhead.js

@@ -243,10 +243,10 @@ function claudePaths(configDir) {
     settings: path.join(configDir, 'settings.json'),
   };
 }
-// The five Bash guard modules. They are shipped, but only require()d by the
+// The six Bash guard modules. They are shipped, but only require()d by the
 // merged trailhead-bash-guards.js (one process per Bash call), never registered
 // on their own. Legacy installs registered each one; the installers strip those.
-const BASH_GUARD_MODULES = ['trailhead-commit-guard.js', 'trailhead-secret-guard.js', 'trailhead-install-guard.js', 'trailhead-search-guard.js', 'trailhead-body-guard.js'];
+const BASH_GUARD_MODULES = ['trailhead-commit-guard.js', 'trailhead-secret-guard.js', 'trailhead-install-guard.js', 'trailhead-search-guard.js', 'trailhead-body-guard.js', 'trailhead-labels-guard.js'];
 // Every hook script copied into the hooks dir (shipped runtime files).
 const HOOK_FILES = [...BASH_GUARD_MODULES, 'trailhead-bash-guards.js', 'trailhead-issue-injection-scanner.js', 'trailhead-secret-read-guard.js', 'trailhead-mockup-link-guard.js', 'trailhead-mockup-link-stop.js', 'trailhead-check-update.js'];
 // The registered entrypoints: the shipped files that must appear in
@@ -436,7 +436,7 @@ function installClaude(configDir, { useSymlink }) {
 
   const s = readJSON(P.settings);
   // Migration: an earlier install registered each Bash guard on its own; the
-  // merged entrypoint below replaces all five.
+  // merged entrypoint below replaces all six.
   stripLegacyBashGuards(s);
   const added = [
     addHook(s, 'PreToolUse', 'Bash', hookCmd('trailhead-bash-guards.js')),