@marcomigozzi/trailhead 0.15.0 → 0.16.1

package/bin/auto-merge-ticket-docs.test.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Docs test for #287: an autonomous run opens, or updates, one merge ticket per map (or
+// the whiteboard) for the slot branches it leaves unmerged, right when each arises.
+// Plain asserts, no framework. Run: node bin/auto-merge-ticket-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 commands = fs.readFileSync(path.join(plugin, 'skills/_shared/substrate-commands.md'), 'utf8');
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+ok('auto.md: names the add call with scope, ticket, file, workspace and repo', auto.includes('trailhead-merge-ticket.js add --scope <map-<n>|whiteboard> --ticket <n> --file <path> [--file <path> ...] --workspace <path> --repo <owner/name>'));
+ok('auto.md: one --file per conflicting path of the merge result', /one `--file` per path in the merge result's `conflicts`/.test(auto));
+ok('auto.md: the add runs right after the abort, before parking', /right after the abort, before parking/i.test(auto));
+ok('auto.md: the park reason names the branch, workspace, files and the merge ticket', /park reason names the branch, the workspace, the conflicting files and the merge ticket/.test(auto));
+ok('auto.md: one merge ticket per map or the whiteboard, opened at the first unmerged branch, updated after each later one', /one merge ticket per map \(or the whiteboard\)[^\n]*opened at the first unmerged branch[^\n]*updated after each later one/.test(auto));
+ok('auto.md: never only at run end', /never only at run end/.test(auto));
+ok('auto.md: a needs-you task so no run takes it, closed by the human', /needs-you `task`[^\n]*no run takes it[^\n]*closed by the human/.test(auto));
+ok('auto.md: a map or the whiteboard with no unmerged branch gets no merge ticket', /no unmerged branch gets no merge ticket/.test(auto));
+ok('auto.md: records as it goes names the merge ticket', /Records as it goes\n[^\n]*merge ticket/.test(auto));
+ok('auto.md: run-end summary names the merge tickets', /\*\*what merged\*\*[^\n]*merge tickets/.test(auto));
+ok('auto.md: a helper error is reported, named in the park reason, retried once at run end', /helper error[^\n]*reported in chat[^\n]*named in the park reason[^\n]*retried once at run end/.test(auto));
+ok('auto.md: a still-failing retry is listed as no merge ticket written', /no merge ticket written/.test(auto));
+ok('substrate-commands.md: names the helper and its call', commands.includes('trailhead-merge-ticket.js add --scope') && commands.includes('--workspace <path> --repo <owner/name>'));
+ok('substrate-commands.md: finds through GraphQL OPEN with the marker', /trailhead:merge-ticket/.test(commands) && /states OPEN|OPEN issues/.test(commands));
+ok('substrate-commands.md: an error is unknown, never none found', /merge ticket[^\n]*unknown, never as none found/.test(commands));
+ok('no em-dash in auto.md', !auto.includes(String.fromCharCode(0x2014)));
+ok('no em-dash in substrate-commands.md', !commands.includes(String.fromCharCode(0x2014)));
+console.log(`auto-merge-ticket-docs.test.js: ${passed} checks passed`);

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

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

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

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

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

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

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

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

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

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

package/bin/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/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`);

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

@@ -69,7 +69,14 @@ function convertToCodex(md) {
   // 2. Claude's /clear -> Codex's /new.
   out = out.replace(/\/clear\b/g, '/new');
 
-  // 3. Paths: anchored forms first, then the bare form.
+  // 3a. Espansione della config dir: CLAUDE_CONFIG_DIR -> CODEX_HOME per intero,
+  // prima dei path nudi (altrimenti resta CLAUDE_CONFIG_DIR con fallback ~/.codex).
+  out = out.replace(/\$\{CLAUDE_CONFIG_DIR:-(~|\$HOME)\/\.claude\}/g, '${CODEX_HOME:-$1/.codex}');
+  // Forme nude rimaste in prosa: $CLAUDE_CONFIG_DIR e ${CLAUDE_CONFIG_DIR} -> CODEX_HOME.
+  out = out.replace(/\$\{CLAUDE_CONFIG_DIR\}/g, '${CODEX_HOME}');
+  out = out.replace(/\$CLAUDE_CONFIG_DIR\b/g, '$CODEX_HOME');
+
+  // 3b. Paths: anchored forms first, then the bare form.
   out = out.replace(/\$HOME\/\.claude\b/g, '$HOME/.codex');
   out = out.replace(/~\/\.claude\b/g, '~/.codex');
   out = out.replace(/(?<![A-Za-z0-9_\-.\/~$])\.claude\//g, '.codex/');
@@ -113,7 +120,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 +373,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 +388,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') },