@marcomigozzi/trailhead 0.11.1 → 0.12.0

package/plugins/trailhead/hooks/trailhead-secret-read-guard.js

@@ -49,6 +49,17 @@
 // that flag's value is exempted, and only for docker/podman verbs; see
 // ENV_FILE_EXEMPT_VERBS below.
 //
+// Name-only operand positions: `git check-ignore` / `git ls-files` /
+// `git rm --cached` pathspecs and the destination of a one-source `cp`/`mv`
+// are names, never contents (the checks that keep a secret OUT of git, and
+// `cp .env.example .env`). Only those positions are exempt, behind closed
+// option sets that fail closed; see GIT_PATHSPEC_SUBCOMMANDS and
+// COPY_NAME_ONLY_FLAGS. Templates (`.env.example`, `.env.*.sample`,
+// `.template`, `.dist`) are not secrets: see NON_SECRET_ENV_SUFFIXES.
+// Known gap (write class, not read): the cp/mv destination exemption can move
+// a link prepared under a non-secret name onto `.env`
+// (`ln -s .env.example l && mv l .env`).
+//
 // Deliberately best-effort on the Bash leg, like the sibling guards: not a
 // full shell parser. It does not care about `cd` shape at all (that is
 // trailhead-search-guard.js's job) — it only asks "does any token here
@@ -73,22 +84,33 @@ const {
 
 // --- path helpers ------------------------------------------------------------
 
+// Suffissi finali di `.env.<...>` che indicano un template committato e
+// privo di segreti (`.env.example`, `.env.local.sample`, ...), non un segreto.
+// Conta solo l'ULTIMO segmento: `.env.example.bak` resta un segreto.
+const NON_SECRET_ENV_SUFFIXES = new Set(['example', 'sample', 'template', 'dist']);
+
 // A basename is a "secret pattern" when it is exactly `.env`, exactly
 // `.secrets`, or `.env.<something>` (e.g. `.env.local`, `.env.production`),
 // matched case-insensitively (`.ENV`/`.Secrets` are the same file on a
 // case-insensitive filesystem). Near-misses like `env.sample` (no leading
-// dot) or `.environment` (no dot after `.env`) must NOT match.
+// dot) or `.environment` (no dot after `.env`) must NOT match, and neither
+// must a template whose last segment is in NON_SECRET_ENV_SUFFIXES.
 function isSecretBasename(name) {
   if (!name) return false;
   const lower = String(name).toLowerCase();
   if (lower === '.env' || lower === '.secrets') return true;
-  return /^\.env\..+$/.test(lower);
+  if (!/^\.env\..+$/.test(lower)) return false;
+  return !NON_SECRET_ENV_SUFFIXES.has(lower.slice(lower.lastIndexOf('.') + 1));
 }
 
+// Anche la forma `<rev>:<path>` (`git show HEAD:.env`, `scp host:.env .`):
+// il path dopo il primo `:` è letto quanto un operando nudo.
 function isSecretPathArg(t) {
   const bare = stripQuotes(t);
   if (!bare) return false;
-  return isSecretBasename(basename(bare));
+  if (isSecretBasename(basename(bare))) return true;
+  const colon = bare.indexOf(':');
+  return colon !== -1 && isSecretBasename(basename(bare.slice(colon + 1)));
 }
 
 // --- Bash leg: quote-aware, statement-based scan -----------------------------
@@ -110,6 +132,56 @@ const VALUE_FLAGS = new Set(['-f', '--file']);
 const ENV_FILE_EXEMPT_VERBS = new Set(['docker', 'podman', 'docker-compose', 'podman-compose']);
 const ENV_FILE_EXEMPT_FLAGS = new Set(['--env-file']);
 const NO_EXEMPT_FLAGS = new Set();
+const NO_SKIP = new Set();
+
+// Sottocomandi git che riportano o rimuovono lo stato ignore/tracking di un
+// path senza mai stamparne il contenuto: i loro pathspec sono NOMI. Ognuno ha
+// il set CHIUSO delle sue opzioni senza valore (`git <sub> -h`, git 2.49):
+// qualsiasi altra opzione ritira l'esenzione dall'intero statement (fail
+// closed), così il valore di un'opzione non è mai scambiato per un pathspec
+// (`-X <file>` legge il file; `--pathspec-from-file=<file>` ne stampa le
+// righe nell'errore "did not match"). `requires` = opzione senza la quale il
+// sottocomando resta controllato (`git rm` solo con `--cached`).
+const GIT_PATHSPEC_SUBCOMMANDS = new Map([
+  ['check-ignore', {
+    flags: new Set(['-q', '--quiet', '-v', '--verbose', '--stdin', '-z', '-n', '--non-matching', '--no-index', '--index']),
+  }],
+  ['ls-files', {
+    flags: new Set([
+      '-z', '-t', '-v', '-f', '-c', '--cached', '-d', '--deleted', '-m', '--modified', '-o', '--others',
+      '-i', '--ignored', '-s', '--stage', '-k', '--killed', '-u', '--unmerged', '--directory', '--eol',
+      '--no-empty-directory', '--resolve-undo', '--exclude-standard', '--full-name',
+      '--recurse-submodules', '--error-unmatch', '--abbrev', '--debug', '--deduplicate', '--sparse',
+    ]),
+  }],
+  ['rm', {
+    flags: new Set(['--cached', '-f', '--force', '-n', '--dry-run', '-q', '--quiet', '-r', '--ignore-unmatch', '--sparse']),
+    requires: '--cached',
+  }],
+]);
+
+// Opzioni globali di git (usage line, git 2.49), per trovare il sottocomando.
+// Un'opzione con valore consuma la parola successiva salvo forma
+// `--opt=value`; un'opzione in nessuno dei due set fa fail closed, così un
+// valore non è mai letto come sottocomando (`git -C ls-files show HEAD:.env`
+// esegue `show`).
+const GIT_GLOBAL_VALUE_OPTIONS = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--config-env']);
+const GIT_GLOBAL_FLAGS = new Set([
+  '-p', '--paginate', '-P', '--no-pager', '--no-replace-objects', '--no-lazy-fetch',
+  '--no-optional-locks', '--no-advice', '--bare',
+]);
+
+// `cp`/`mv` scrivono la destinazione e non la stampano: un nome segreto che è
+// SOLO la destinazione di una copia/spostamento a sorgente singola è un nome
+// (`cp .env.example .env`). Vale per esattamente due operandi preceduti da
+// opzioni di questo set chiuso; tutto il resto lascia lo statement
+// controllato: `-t` (ogni operando diventa sorgente), backup (`-b`,
+// `--backup`, `-S`: il vecchio segreto sopravvive come `.env~`), link (`-l`,
+// `-s`) o `--exchange` (la destinazione condivide o scambia il segreto). Le
+// opzioni devono precedere gli operandi: una in coda è opzione con la
+// permutazione GNU ma operando con POSIXLY_CORRECT, quindi quale parola sia
+// la destinazione dipenderebbe da un ambiente che l'hook non vede.
+const COPY_NAME_ONLY_FLAGS = new Set(['-f', '--force', '-i', '--interactive', '-n', '--no-clobber', '-v', '--verbose']);
 
 // The pattern-first search verbs (grep/rg/ag/sed/awk), shared with
 // trailhead-search-guard.js. Their first positional is a PATTERN, not a file
@@ -139,9 +211,11 @@ function stripTrailingPunct(t) {
 // redirect target. Returns the offending token or null. `exemptFlags` (#180)
 // names flags whose value must be skipped entirely rather than scanned, in
 // both the `--flag=value` and spaced `--flag value` forms.
-function scanTokensForSecretPath(tokens, exemptFlags) {
+function scanTokensForSecretPath(tokens, exemptFlags, skipIndices) {
   const exempt = exemptFlags || NO_EXEMPT_FLAGS;
+  const skip = skipIndices || NO_SKIP;
   for (let i = 0; i < tokens.length; i++) {
+    if (skip.has(i)) continue; // posizione nome-soltanto: mai letta
     const t = stripTrailingPunct(tokens[i]);
     if (!t) continue;
 
@@ -175,7 +249,7 @@ function scanTokensForSecretPath(tokens, exemptFlags) {
       // `-f value` / `--file value` (separate-token value).
       if (VALUE_FLAGS.has(t)) {
         const next = i + 1 < tokens.length ? stripTrailingPunct(tokens[i + 1]) : null;
-        if (next && isSecretPathArg(next)) return next;
+        if (next && !skip.has(i + 1) && isSecretPathArg(next)) return next;
         continue;
       }
       // Glued short-option value (`-f.env`, finding #2): a single-dash flag
@@ -197,6 +271,77 @@ function scanTokensForSecretPath(tokens, exemptFlags) {
   return null;
 }
 
+// Vero se `text` è un'opzione lunga elencata, o un cluster corto (`-ci`) di
+// cui OGNI lettera è elencata. `--opt=value`, un'abbreviazione o un cluster
+// che contiene un'opzione con valore (`-ciX`) non lo sono.
+function isListedFlag(text, flags) {
+  if (text.startsWith('--')) return flags.has(text);
+  return /^-[A-Za-z]+$/.test(text) && [...text.slice(1)].every((ch) => flags.has(`-${ch}`));
+}
+
+// Indice del sottocomando git oltre le opzioni globali, o -1 se lo precede
+// un'opzione fuori da GIT_GLOBAL_VALUE_OPTIONS / GIT_GLOBAL_FLAGS.
+function gitSubcommandIndex(operands) {
+  for (let k = 0; k < operands.length; k++) {
+    const t = operands[k];
+    if (!t.startsWith('-')) return k;
+    if (GIT_GLOBAL_VALUE_OPTIONS.has(t)) { k++; continue; }
+    if (GIT_GLOBAL_FLAGS.has(t)) continue;
+    const eq = t.indexOf('=');
+    const isLongValueForm = t.startsWith('--') && eq !== -1 && GIT_GLOBAL_VALUE_OPTIONS.has(t.slice(0, eq));
+    if (!isLongValueForm) return -1;
+  }
+  return -1;
+}
+
+// Indici dei pathspec di un sottocomando in GIT_PATHSPEC_SUBCOMMANDS. git
+// permuta le opzioni (una può seguire un pathspec); dopo `--` ogni parola è
+// un pathspec. Sottocomando confrontato case-sensitive, come fa git.
+function gitPathspecIndices(operands) {
+  const sub = gitSubcommandIndex(operands);
+  const spec = sub === -1 ? undefined : GIT_PATHSPEC_SUBCOMMANDS.get(operands[sub]);
+  if (!spec) return NO_SKIP;
+  const pathspecs = new Set();
+  let required = spec.requires === undefined;
+  let endOfOptions = false;
+  for (let k = sub + 1; k < operands.length; k++) {
+    const t = operands[k];
+    if (endOfOptions || !t.startsWith('-') || t === '-') pathspecs.add(k);
+    else if (t === '--') endOfOptions = true;
+    else if (!isListedFlag(t, spec.flags)) return NO_SKIP;
+    else if (t === spec.requires) required = true;
+  }
+  return required ? pathspecs : NO_SKIP;
+}
+
+// Indice della destinazione di un `cp`/`mv` a sorgente singola (vedi
+// COPY_NAME_ONLY_FLAGS).
+function copyDestinationIndices(operands) {
+  const positional = [];
+  let endOfOptions = false;
+  for (let k = 0; k < operands.length; k++) {
+    const t = operands[k];
+    if (endOfOptions || !t.startsWith('-') || t === '-') positional.push(k);
+    else if (positional.length) return NO_SKIP; // opzione o `--` dopo un operando
+    else if (t === '--') endOfOptions = true;
+    else if (!isListedFlag(t, COPY_NAME_ONLY_FLAGS)) return NO_SKIP;
+  }
+  return positional.length === 2 ? new Set([positional[1]]) : NO_SKIP;
+}
+
+// Indici dei token (verbo incluso, indice 0) che lo statement consuma come
+// NOME e mai come CONTENUTO: pathspec di git check-ignore/ls-files/rm
+// --cached e destinazione di cp/mv. Solo queste posizioni saltano il
+// controllo; ogni altro token resta controllato, quindi l'esenzione non può
+// riciclare una lettura altrove nello statement.
+function nameOnlyTokenIndices(bin, tokens) {
+  const operands = tokens.slice(1).map((t) => stripQuotes(stripTrailingPunct(t)));
+  let indices = NO_SKIP;
+  if (bin === 'git') indices = gitPathspecIndices(operands);
+  else if (bin === 'cp' || bin === 'mv') indices = copyDestinationIndices(operands);
+  return new Set([...indices].map((k) => k + 1));
+}
+
 // Does `stmtTokens` invoke `bash -c "<cmd>"` / `sh -c "<cmd>"` / `eval
 // "<cmd>"` (etc.)? If so, return the inner command TEXT (quotes stripped, not
 // yet re-tokenized) so the caller can recurse into it as a nested command.
@@ -243,7 +388,7 @@ function scanStatementForSecretPath(stmt) {
   // standalone docker-compose/podman-compose binaries) get --env-file's value
   // exempted; every other verb keeps today's behaviour unchanged.
   const exempt = ENV_FILE_EXEMPT_VERBS.has(bin) ? ENV_FILE_EXEMPT_FLAGS : NO_EXEMPT_FLAGS;
-  return scanTokensForSecretPath(tokens, exempt);
+  return scanTokensForSecretPath(tokens, exempt, nameOnlyTokenIndices(bin, tokens));
 }
 
 // Walk the command's top-level statements (quote-aware; `|`, `;`, `&&`,

package/plugins/trailhead/hooks/trailhead-secret-read-guard.test.js

@@ -129,6 +129,62 @@ ok('hook allows Bash(podman run --env-file=.env img) end-to-end (exit 0, no outp
 const d3 = runHook('Bash', { command: 'cat .env' });
 ok('hook still denies Bash(cat .env) end-to-end (exit 2, block decision)', d3.code === 2 && /"decision":"block"/.test(d3.out));
 
+// --- template env files (.env.example/.sample/.template/.dist) are not secrets ---
+const allowCmd = (c) => ok(`Bash \`${c}\` is allowed`, !detectSecretRead('Bash', { command: c }));
+const denyCmd = (c) => ok(`Bash \`${c}\` is denied`, !!detectSecretRead('Bash', { command: c }));
+ok('Read .env.example is allowed', !detectSecretRead('Read', { file_path: '.env.example' }));
+ok('Read .env.local.example is allowed', !detectSecretRead('Read', { file_path: 'app/.env.local.example' }));
+ok('Read .ENV.SAMPLE is allowed', !detectSecretRead('Read', { file_path: '.ENV.SAMPLE' }));
+allowCmd('cat .env.template');
+allowCmd('cat .env.dist');
+ok('Read .env.example.bak is still denied', !!detectSecretRead('Read', { file_path: '.env.example.bak' }));
+ok('Read .env.examples is still denied', !!detectSecretRead('Read', { file_path: '.env.examples' }));
+
+// --- name-only operand positions: git pathspecs, cp/mv destination ---
+// Questi comandi non stampano mai il contenuto del file: sono i controlli che
+// tengono un segreto fuori da git, e il guard non deve bloccarli.
+allowCmd('git check-ignore -v .env');
+allowCmd('git check-ignore -q .env .secrets');
+allowCmd('git ls-files --error-unmatch .env');
+allowCmd('git ls-files -ci --exclude-standard -- .env');
+allowCmd('git rm --cached .env');
+allowCmd('git rm -r --cached -f .env');
+allowCmd('git -C app check-ignore .env');
+allowCmd('git --no-pager ls-files .env');
+allowCmd('cp .env.example .env');
+allowCmd('cp -f .env.example .env');
+allowCmd('mv .env.sample .env');
+allowCmd('cp -- .env.example .env');
+allowCmd('git check-ignore .env && cp .env.example .env');
+// Fail-closed: forme che leggono, o fuori dal set di opzioni chiuso.
+denyCmd('git show HEAD:.env');
+denyCmd('git rm .env');
+denyCmd('git rm -- --cached .env');
+denyCmd('git rm --cached --pathspec-from-file=.env');
+denyCmd('git ls-files -X .env');
+denyCmd('git ls-files -ciX .env');
+denyCmd('git -C ls-files show HEAD:.env');
+denyCmd('git --unknown check-ignore .env');
+denyCmd('git diff .env');
+denyCmd('cp .env /tmp/x');
+denyCmd('cp .env .env.bak');
+denyCmd('mv .env /tmp/x');
+denyCmd('cp -t /tmp .env.example .env');
+denyCmd('cp .env.example .env /tmp');
+denyCmd('cp -b .env.example .env');
+denyCmd('cp --backup .env.example .env');
+denyCmd('cp -l .env.example .env');
+denyCmd('cp -s .env.example .env');
+denyCmd('mv --exchange .env.example .env');
+denyCmd('cp .env.example .env -f');
+denyCmd('cp .env.example .env && cat .env');
+denyCmd('git check-ignore .env; cat .env');
+
+const a6 = runHook('Bash', { command: 'git check-ignore -v .env' });
+ok('hook allows Bash(git check-ignore -v .env) end-to-end (exit 0, no output)', a6.code === 0 && a6.out.trim() === '');
+const a7 = runHook('Bash', { command: 'cp .env.example .env' });
+ok('hook allows Bash(cp .env.example .env) end-to-end (exit 0, no output)', a7.code === 0 && a7.out.trim() === '');
+
 // --- crash safety ---
 const crash1 = runHook('Read', undefined);
 ok('missing tool_input never crashes (exit 0)', crash1.code === 0);

package/plugins/trailhead/skills/_shared/choices.md

@@ -54,6 +54,8 @@ This is the operational recipe every applicable call-site follows. It is **manda
 
 Worked examples: 2 real options + delegate + defer = 4 -> all in the menu; 3 real options + delegate + defer = 5 -> the menu carries the 3 real options and delegate/defer are offered in the prose line right after it; 2 real options + delegate (defer not applicable) = 3 -> in the menu.
 
+**Menu call-sites (an `AskUserQuestion` trailhead authors): links live in the prose.** A picker renders its question and options as plain text, so nothing in it is clickable. When a question is about something the user has to open first (a mockup to approve or pick from, a published page, a PR, a ticket comment), write its clickable link(s) in the reply text **immediately before** the menu, in that same message, never only earlier in the conversation, never as a name in place of the URL, and never inside the picker. If there is no link to show yet, do not ask. For mockups the full rule is "Surface the mockup" in `techniques/prototype.md`, enforced by the mockup-link hooks (Claude Code and Codex).
+
 **Prose / conversational call-sites (grilling, or any choice put in words rather than a menu).** There is no cap: **state the applicable affordance(s) in words** in the same message that puts the choice (for example append "Oppure: scegli tu, propongo io / scelgo dopo se dipende da un prerequisito."). Grilling stays human-decides, so delegate is not offered there; **defer is offered in prose when the decision is genuinely blocked on a prerequisite.**
 
 `(Recommended)` on a real option is a separate, static hint that may coexist with the affordances; it is not the delegate option.

package/plugins/trailhead/skills/_shared/configuration-reference.md

@@ -39,7 +39,7 @@ Effective config = built-in defaults ← global `~/.claude/trailhead/config.json
 
 **Pinned model review.** After an update that changed the tier defaults, the engine offers to review pinned `models.*` / `models.codex.*` ids that are older than their tier's new default (listed `key: old -> new`), with three choices: update (write the new ids, codex effort unchanged), keep (nothing to do, not asked again for these defaults), or open `/trailhead:config` to pick per key. The review evaluates the **effective** pins: the global `~/.claude/trailhead/config.json` merged under the project's `.trailhead/config.json`, project winning key by key (a project's own key, even `null`, `''`, or `inherit session`, always wins over the global value; `models.codex` follows the same per-key rule, so a stale pin inherited from the global config is flagged too, even for a project that pins nothing itself). Each stale line names the config file it actually came from, so the update choice edits the right one. The check (`model-defaults-review.js`'s `check(cwd)`, CLI subcommand `check`) is **read-only**: it never writes an ack by itself, so it keeps reoffering until the user actually answers. The ack (CLI subcommand `ack`, writing the acknowledged defaults version) is written only after the user picks one of the three choices, never just for the notice having been shown; it lives in the gitignored `.trailhead/model-defaults-ack` file when a project is found above `cwd`, whether the stale pin itself is project or global. With no project found above `cwd`, the review runs on the global config alone (if one exists) and its ack lives next to it, at `<config dir>/trailhead/model-defaults-ack` (config dir = `$CLAUDE_CONFIG_DIR` or `~/.claude`). The check runs both in the `trailhead-check-update.js` SessionStart hook and at skill config load (`../_shared/load-first.md`), once per session either way. Unset keys already follow the new defaults, so they are never flagged; unknown ids (custom or unrecognised) are never flagged either. The tier history lives in `hooks/lib/model-defaults.json`. Hookless hosts run the same `node <hooks>/lib/model-defaults-review.js check <dir>` / `... ack <dir>` pair inline at session start.
 
-If a value is unset, it resolves to its **Balanced**-profile default for that activity (the default profile: a project with no config still gets the Balanced tier per key, resolved to a concrete id at load time, strong → `claude-opus-5-5`, standard → `claude-sonnet-5-5`, fast → Haiku-class). To use the session model instead of the Balanced default, set the key explicitly to `inherit session`. Never hard-fail on an unknown id: warn and inherit the session model.
+If a value is unset, it resolves to its **Balanced**-profile default for that activity (the default profile: a project with no config still gets the Balanced tier per key, resolved to a concrete id at load time, strong → `claude-opus-5-5`, standard → `claude-sonnet-5-5`, fast → `claude-haiku-5-5`). To use the session model instead of the Balanced default, set the key explicitly to `inherit session`. Never hard-fail on an unknown id: warn and inherit the session model.
 
 **Everything else runs in the main session on its own model, there is no key for it:** charting, grilling, naming the destination, framing and **writing the tickets**, graduating fog, and map/decision operations. That's deliberate: it's HITL/orchestration work (you reason *with* the user), so the model that writes a ticket is the one grilling you; it can't fan out to a subagent. Practical upshot: **run a charting session (`/trailhead:new`/`:adopt`/`:ticket`) on your strong model**. The `models.*` keys above govern only the fan-out activities, not the quality of the tickets themselves. **Store a full model id** (e.g. `claude-opus-5-5`, `claude-fable-5`), never a bare family alias like `opus`; a family now spans several live versions, so an alias can't say which one. (On Claude Code the `Agent` tool takes only a family alias, so at subagent spawn the stored id is mapped to its alias, see the dispatch rule in `techniques.md`; the full id is still what gets stored, so the exact version stays on record and drives the inline-vs-subagent decision, even though the alias-only spawn cannot convey that version to the subagent.) **`models.plan` and `models.execute` are always distinct choices**: never collapse them into one shared model pick, even when the user would pick the same id for both.
 
@@ -52,7 +52,7 @@ If a value is unset, it resolves to its **Balanced**-profile default for that ac
 | **Low** | standard | standard | fast | fast | standard | fast | fast |
 
 **Tier-class -> id**, resolved from the lineup actually reachable at setup time (verify, don't trust these verbatim):
-- **Claude** (`models.*`, ids only, no effort): strong = Opus-class, resolved to **`claude-opus-5-5`** by default (`claude-opus-5` stays offered in the per-key menus) · standard = Sonnet-class, resolved to **`claude-sonnet-5-5`** by default (so Balanced's `execute` runs on Sonnet 5.5; `claude-sonnet-5` stays offered in the per-key menus) · fast = Haiku-class.
+- **Claude** (`models.*`, ids only, no effort): strong = Opus-class, resolved to **`claude-opus-5-5`** by default (`claude-opus-5` stays offered in the per-key menus) · standard = Sonnet-class, resolved to **`claude-sonnet-5-5`** by default (so Balanced's `execute` runs on Sonnet 5.5; `claude-sonnet-5` stays offered in the per-key menus) · fast = Haiku-class, resolved to **`claude-haiku-5-5`** by default (`claude-haiku-4-5` stays offered in the per-key menus).
 - **Codex** (`models.codex.*`, `{model, effort}`): strong = `gpt-5.6-sol` @ `high` (debug on **High** may be `xhigh`) · standard = `gpt-5.6-terra` @ `medium` · fast = `gpt-5.6-luna` @ `low`.
 - Changing a tier default must append a complete new entry to `hooks/lib/model-defaults.json` in the same commit.
 
@@ -101,7 +101,7 @@ Example `config.json` (same shape for the project `.trailhead/config.json` and t
 3. **🌐 Ticket language**: the language trailhead writes its GitHub prose & commit descriptions in (`ticket.language`, ISO 639-1). Offer 🇬🇧 English (`en`, default) · 🇮🇹 Italiano (`it`) · 🇪🇸 Español (`es`) · 🇫🇷 Français (`fr`) · 🇩🇪 Deutsch (`de`) · 🇵🇹 Português (`pt`), plus a free-code option for any other ISO 639-1 code. Note in the prompt that this is *not* the language the agent converses in.
 4. **🧠 Models**: a **profile** (Balanced by default) applied whole, or **Manual** for the per-key questions.
    - **🎚️ Profile, asked first (and often the only Models question).** Present one `AskUserQuestion` menu: 🏔️ **High** · ⚖️ **Balanced (consigliato)** · 🍃 **Low** · ✍️ **Manual (specify each model)**. **On a project with no existing config, pre-select ⚖️ Balanced** (the default profile); when a config already exists, pre-select the profile its keys match (or **Manual** when they match none). **On High / Balanced / Low this is terminal:** seed the seven model keys from the **Model-tier profiles** table above, resolving each tier-class to a concrete id **at setup time** (verify the lineup, don't trust ids verbatim), **write them, and do NOT ask the per-key questions**. Only **Manual** proceeds to the per-key questions below (where any key may be left at `inherit session`). **Host branch:** on **Claude** the profile seeds `models.*` with tier-class ids; on **Codex** it seeds `models.codex.*` as `{model, effort}` (effort is the Codex-only face), and after applying keep the **re-run the installer** instruction from the Codex per-key path below so the pins are re-projected into `~/.codex/agents/trailhead-*.toml`.
-   - **The per-key questions (Manual path only): always two separate questions, one for `plan` and one for `execute`; never merge them into a single model pick.** Ask each as its own `AskUserQuestion` menu (current value pre-selected), and offer the **same versioned lineup** to both. Each option is a **full model id with its version**; never a bare family alias (`opus`/`sonnet`/`haiku`), which can't say *which* live version. Build the list from the models actually reachable **at setup time** (verify, don't trust this file verbatim), offering **at least the two most recent versions per family**, e.g. `claude-fable-5`, `claude-opus-5-5` / `claude-opus-5`, `claude-sonnet-5-5` / `claude-sonnet-5`, `claude-haiku-4-5`, plus **inherit session** (the no-override option, the session model). If that lineup exceeds the menu's option cap, drill **family → version** or include a free-id "Other" so every recent version stays reachable. The rarer `research`/`review`/`debug`/`verify`/`codebase-map` sit behind an "Advanced" option, each its own separate choice, same versioned rule.
+   - **The per-key questions (Manual path only): always two separate questions, one for `plan` and one for `execute`; never merge them into a single model pick.** Ask each as its own `AskUserQuestion` menu (current value pre-selected), and offer the **same versioned lineup** to both. Each option is a **full model id with its version**; never a bare family alias (`opus`/`sonnet`/`haiku`), which can't say *which* live version. Build the list from the models actually reachable **at setup time** (verify, don't trust this file verbatim), offering **at least the two most recent versions per family**, e.g. `claude-fable-5`, `claude-opus-5-5` / `claude-opus-5`, `claude-sonnet-5-5` / `claude-sonnet-5`, `claude-haiku-5-5` / `claude-haiku-4-5`, plus **inherit session** (the no-override option, the session model). If that lineup exceeds the menu's option cap, drill **family → version** or include a free-id "Other" so every recent version stays reachable. The rarer `research`/`review`/`debug`/`verify`/`codebase-map` sit behind an "Advanced" option, each its own separate choice, same versioned rule.
    - **Anti-pattern, never do this (in the Manual path):** a single screen whose options are *combined* plan+execute presets, e.g. `🧠 Plan 4.8 / Exec Sonnet 5`, `🚀 Tutto Opus 5`, `Plan Opus 5 / Exec Sonnet 5`. That bundles the two decisions into one pick. Forbidden. In Manual, Plan is asked, answered, and only then is Execute asked, as a second menu: two questions, two answers, always. (A **named tier profile** applied whole is **not** this anti-pattern: it is a coherent per-key tier assignment chosen deliberately, not an ad-hoc plan+execute combo, which is why picking a profile is terminal.)
    - **On Codex (host-detected), the Manual path asks `models.codex.*` instead of the Claude lineup.** Same discipline: `plan` and `execute` as two separate `AskUserQuestion` menus, never merged; the rarer `research`/`review`/`debug`/`verify`/`codebase-map` behind Advanced, each its own choice. Offer OpenAI model ids verified reachable at setup time (do not trust this list verbatim): `gpt-5.6-sol` (flagship) / `gpt-5.6-terra` (balanced) / `gpt-5.6-luna` (fast), plus **inherit session** (default). Avoid the retiring `gpt-5.4` / `gpt-5.4-mini` and the deprecated `gpt-5.3-codex`. Write the answers to `models.codex.*`; the Claude `models.*` lineup is not asked on Codex (those ids cannot run there). After writing, tell the user to **re-run the installer** (the same `--host=codex` install command) so the pins are re-projected into `~/.codex/agents/trailhead-*.toml`: the menu updates `.trailhead/config.json`, the installer is what regenerates the TOMLs and enables `features.multi_agent_v2`.
 5. **🎨 Design**: 💾 Local disk · 🖼️ claude.ai/design (Anthropic's official Claude Design MCP, Claude only) · 🧵 Stitch (Google Stitch MCP, cross-host: Claude Code + Codex). *Mode only, don't ask for a URL here; the concrete project is created or reused at execution time and its projectId cached in `design.project` (see Prototype).* If claude.ai/design or Stitch is picked, ask the **🖼️ Design surface**: 🖌️ Canvas (a single project of screens to react to; default; **who makes it:** on claude.ai/design you do, the `/design` Artifact or a hand-made web-app project, not MCP-driven; on Stitch the MCP generates the screens) · 🧩 Design system (push components into a shared design-system project, for a shared library; **the MCP creates and syncs it**) → `design.surface`. Then **✅ Mockup approval**: 🖐️ Explicit (wait for a go-ahead before UI code) · ⏩ Auto (proceed without blocking).

package/plugins/trailhead/skills/_shared/principles.md

@@ -1,7 +1,7 @@
 ## Principles
 
 - **Execution inside the map (default).** Unlike a plan-only approach ("plan, don't do"), here the map carries **construction** within it: after the decision tickets, build tickets graduate from the fog and are **executed** as children of the map. The destination is the **working** artifact (a deployed app), not a spec document; the spec is a waypoint. *Override:* a project that must stop at the spec declares it in the map's `## Notes` (that wins over this default).
-- **Refer by name.** Every map and ticket is an issue, so it has a **title**. In everything the human reads, refer by name, never by a bare `#number`. A wall of `#42, #43, #44` is illegible; names read at a glance. The id and URL don't vanish (a name wraps its link) but they ride *inside* the name. **One exception: a command the user must run.** In `/trailhead:work <ticket>` the argument is machine input, not prose; give the **bare number** there (a long title, with its punctuation and jargon, is awkward and error-prone to type). Name the ticket in the surrounding sentence, put the number in the command.
+- **Refer by name.** Every map and ticket is an issue, so it has a **title**. In everything the human reads, refer by name, never by a bare `#number`. A wall of `#42, #43, #44` is illegible; names read at a glance. **But keep the number visible next to the name**, never hidden inside a link: the user works tickets by number, so a name with no number in sight forces them to look it up. Render a ticket as its name followed by its number, e.g. *Add login rate limit* (#45) (the URL may wrap the name), above all when you report a ticket you just opened, captured, or split. **One exception: a command the user must run.** In `/trailhead:work <ticket>` the argument is machine input, not prose; give the **bare number** there (a long title, with its punctuation and jargon, is awkward and error-prone to type). Name the ticket in the surrounding sentence, put the number in the command.
 - **Result-oriented output.** In the chat, report **what was done and the next step**: name tickets, give the concrete next command. Never expose trailhead's internal machinery: Mode labels (`Mode 1`), protocol/step names (`DISCUSS`/`PLAN`/`VERIFY`, "the build engine", "graduate the fog", "the frontier"), wrapper/SKILL.md mechanics, or the conventions and config you are silently obeying: the git mode (`main`/`pr`), the isolation/worktree decision, submodule commit mechanics (commit-inside + gitlink bump), claim/assignment plumbing, and **how work fans out to subagents** (whether a step ran inline or as a subagent, the role name `executor`, the model `claude-sonnet-5`, the config key `models.execute`). To the user it is just **"an agent"**: say "I'll hand this to an agent with the exact spec, then run the code review over the whole diff", never "an executor on `claude-sonnet-5` per `models.execute`". Just act, then report the outcome. Surface a convention only when it **changes what the user must do** (a UAT they run, a release awaiting their command, a genuine claim collision with *another* login) or when they explicitly ask.
 - **No em-dashes.** Write with ordinary punctuation: commas, colons, semicolons, parentheses, periods. Never use an em-dash (U+2014), and never a hyphen standing in for a comma. This holds for **everything trailhead produces**: ticket titles and bodies, engine comments, the map body, commit descriptions, chat output, and the skill's own source docs. En-dashes in numeric ranges (`1–2`) and the arrow `→` in trailhead's notation stay; only the em-dash is banned.
 - **One ticket per session: hard rule.** Resolve **at most one** ticket per session; once one is resolved, do **not** start a second; end the session instead. The only exceptions: `research` tickets (AFK, run in parallel) and `capture` operations (they resolve nothing). On resolving a ticket, close the session with the **[Session handoff](session-handoff.md)** ritual.

package/plugins/trailhead/skills/_shared/session-handoff.md

@@ -3,7 +3,7 @@
 Resolving a ticket **ends the session**: one ticket per session is a hard rule (see [Principles](principles.md)). So every resolution closes the same way. Render every command in this ritual in this host's command forms (the **Host command forms** rule in `load-first.md`). After the resolution comment + `gh issue close` + the `Decisions so far` update, **remove the session-ticket marker** (`.trailhead/session-ticket` at the working root, if you wrote one, see Mode 2), then **always** sign off with, in order:
 
 1. **A short recap of what was done** (2 to 4 lines) for the resolved ticket: the change in plain language, the files or areas touched (when applicable), and the outcome (verified / released / next step). Keep it **result-oriented**: say what changed and what it means, never trailhead's internal machinery (no mode or step names, no engine-role or technique names). It **augments** the ritual (it does not replace anything below): the recap sits above the one-line confirmation and gives the user a quick account of the ticket without reconstructing it from the commits or the issue timeline. It rides with a **resolution** only; a decision-ticket resolution may touch no files, hence "when applicable", and a capture or research batch (which never reach this ritual) carry no recap. It also carries forward any **pending follow-up** the Pending follow-up guard below identified, so a follow-up surfaced while working never has to be reconstructed from scrollback.
-2. **A one-line confirmation** the ticket is resolved, by name (not a bare `#number`).
+2. **A one-line confirmation** the ticket is resolved, by name and number, both visible (e.g. *Add login rate limit* (#45), never the name alone nor a bare `#number`).
 3. **The next step: a scannable block whose FIRST line is `/clear`, always.** Never bury it in prose, and **never point at the next ticket without leading with `/clear`**. `/clear` is its own first bullet, phrased as the first thing to do ("fai `/clear`, poi..."): **never demote it to a trailing parenthetical** on the next command. `/trailhead:work 29 (dopo /clear)` is the bug, not the fix: the reader runs the command and only then reads the note, when the context is already dirty. State the `/clear` **every time** (not only when context is heavy): it must come *before* the next command, on its own line first, so the next ticket starts on clean context. Render it as a short labelled list in the user's conversation language, along these lines:
 
    > **Prossimo passo:**

package/plugins/trailhead/skills/_shared/substrate-commands.md

@@ -173,6 +173,13 @@ These renders create and pin only when missing; they never rewrite the body.
 - **per open map, also flag GitHub's 100 sub-issue cap**: read `sub_issues_summary.total` (below) and flag `near cap · <total>/100` (total >= 90) or `at cap` (total >= 100). For only the (rare) at/near-cap maps, run one bounded native sub-issue list (see `## Sub-issue cap and pruning` above) to check for closed edges, exactly like the bounded fog-confirm above, and append `· prunable` when any are found. The render offers `/trailhead:prune` for such a map, never auto-prunes;
 - the whiteboard as a section, or a link to the `/trailhead:whiteboard` view;
 - dynamic counts: untriaged inbox size and whiteboard frontier size.
+- **the last-audit marker, carried through untouched.** If the existing body holds a hidden line `<!-- trailhead:last-audit <ISO-8601 UTC> -->` (written by `/trailhead:audit`, see `../trailhead-manage/references/auditing.md`), copy that line **verbatim** into every regenerated body, never dropped, reformatted, or re-dated. Only `/trailhead:audit` changes its value, and only on a confirmed marker advance, through the same fail-safe read-modify-write:
+```bash
+# read the marker (empty output = no audit yet); the body was already read non-empty per the fail-safe rule
+gh issue view <dashboard> --json body --jq .body | grep -o '<!-- trailhead:last-audit [^ ]* -->'
+# write: replace the marker line if present, else append it, in the body-file you then pass to `gh issue edit <dashboard> --body-file`
+sed -i -E 's|<!-- trailhead:last-audit [^ ]* -->|<!-- trailhead:last-audit <ISO-8601 UTC> -->|' <body-file>   # or append the line when absent
+```
 
 Count queries, `--json ... --jq 'length'` style:
 ```bash
@@ -194,4 +201,4 @@ gh api repos/{owner}/{repo}/issues/<map> --jq '.sub_issues_summary.total'
 ## First-use repo setup (do ALL THREE, every chart or adopt, never skip any)
 1. Create any missing labels with `gh label create` (all eighteen: `trailhead:map`, `trailhead:codebase`, `trailhead:conventions`, `trailhead:dashboard`, `trailhead:ticket`, the six type labels, `trailhead:blocked`, `trailhead:seed`, `trailhead:out-of-scope`, `trailhead:superseded`, `trailhead:unverified`, `trailhead:fog`, `trailhead:whiteboard`).
 2. **Check the label guard is installed**: `gh api repos/{owner}/{repo}/contents/.github/workflows/trailhead-label-guard.yml`; if it's absent (404), install it: **read `teamwork.md` (Trust & provenance → Repo-side enforcement) for the exact steps**. This is part of standing up trailhead in a repo, not an optional extra: *check every time*, so a repo can never end up with the labels but no guard.
-3. **Sync the commit-msg git hook**: run the commit-msg hook sync script (`trailhead-commit-msg-sync.js`; installs it if absent, upgrades an outdated trailhead hook in place, never touches a foreign one) so trailhead's commit discipline (Conventional Commits subject, no `Co-Authored-By`, and a `Refs: #<n>` trailer while a `.trailhead/session-ticket` marker is active) runs on **every** `git commit` regardless of host (the Claude-Code `PreToolUse` guard stays too, defence in depth): **read `teamwork.md` (Trust & provenance → Repo-side enforcement) for the exact steps**. If the script is missing or node errors, fall back to inspecting the hooks dir (`git rev-parse --git-path hooks`) per `teamwork.md`, never a blind "not enforced". Like the label guard, *check every time*; unlike it, `.git/hooks/` is per-clone local state (untracked), so it is installed, never committed.
+3. **Sync the commit-msg git hook**: run the commit-msg hook sync script (`trailhead-commit-msg-sync.js`; installs it if absent, upgrades an outdated trailhead hook in place, never touches a foreign one) so trailhead's commit discipline (Conventional Commits subject, no `Co-Authored-By`, and a `Refs: #<n>` trailer while a `.trailhead/session-ticket` marker is active) runs on **every** `git commit` regardless of host (the Claude-Code `PreToolUse` guard stays too, defence in depth): **read `teamwork.md` (Trust & provenance → Repo-side enforcement) for the exact steps**. If the script is missing or node errors (missing means none of the three template dirs listed in `teamwork.md` has it: try them all first), fall back to inspecting the hooks dir (`git rev-parse --git-path hooks`) per `teamwork.md`, never a blind "not enforced". Like the label guard, *check every time*; unlike it, `.git/hooks/` is per-clone local state (untracked), so it is installed, never committed.

package/plugins/trailhead/skills/_shared/teamwork.md

@@ -94,4 +94,4 @@ The map issue's **body** is a shared mutable document: two sessions appending to
 
 **Repo-side enforcement (part of first-use setup, not an afterthought).** trailhead **installs the label guard for you**; don't tell the user to copy files. **Every chart or adopt, *check* whether `.github/workflows/trailhead-label-guard.yml` exists** (the first-use repo setup, in SKILL.md's Substrate section); if it's absent, install it, by default on a repo with other collaborators, and as a quick offer on a clearly solo/private one (cheap insurance), but **never silently skip the check**: that's exactly how a repo ends up with trailhead labels and no guard. On go-ahead, write the shipped label-guard template (`${CLAUDE_PLUGIN_ROOT}/templates/trailhead-label-guard.yml` for a plugin install, or `~/.claude/trailhead/templates/trailhead-label-guard.yml` for an npm install, take whichever exists) to the repo's `.github/workflows/trailhead-label-guard.yml` and commit it (conventional message; the commit-guard hook keeps it clean). The Action strips any `trailhead:*` label added by a non-write actor and comments why; set an optional `TRAILHEAD_LABEL_ALLOWLIST` repo variable to whitelist extra logins (e.g. a bot trailhead runs as). **Caveat:** pushing a workflow file needs a token with the `workflow` scope; if the push is rejected, run `gh auth refresh -s workflow` and retry (or, as a last resort, tell the user to add the file by hand).
 
-**The commit-msg git hook (host-independent commit guard).** On every host trailhead ALSO installs a git **`commit-msg`** hook as a host-independent backstop (defence in depth alongside the host's own `PreToolUse` guard on Claude Code and Codex alike), enforcing the two rules (a Conventional Commits subject of at most 72 chars; never a `Co-Authored-By` trailer) plus, while a `.trailhead/session-ticket` marker is present at the worktree root, a `Refs: #<n>` trailer matching its number, on every `git commit`, whatever host drives it (decision #16). **Every chart or adopt, and at every `work`/`quick` ticket start, run the sync script**: `node <templates>/trailhead-commit-msg-sync.js --repo <working-root>`, where `<templates>` is whichever of `${CLAUDE_PLUGIN_ROOT}/templates/`, `~/.claude/trailhead/templates/`, or `~/.codex/skills/trailhead/templates/` exists. It prints one JSON status line and handles every case itself: absent -> installs it; an older trailhead hook (recognised by its own header line, not by trusting the filename) -> upgraded in place; already current -> left alone; a foreign (non-trailhead) hook -> never touched, only reported (offer to chain it); under a repo's `core.hooksPath`, an existing trailhead hook there is still upgraded in place, but nothing is newly added to that directory. Unlike the label guard, `.git/hooks/` is not version-controlled, so this is a per-clone local install with nothing to commit. **If the sync script is missing (outdated install) or node errors, never claim git enforces nothing before looking**: resolve the effective hooks dir with `git -C <working-root> rev-parse --git-path hooks` (resolve a relative output against the working root; it honours `core.hooksPath` and the git common dir shared by linked worktrees), read `<hooks dir>/commit-msg`, and classify it by its header line (a trailhead hook has `// trailhead commit-msg hook (git).` among its first 5 lines, trimmed; never trust the filename alone; a symlinked `commit-msg` counts as foreign, as the script treats it). Report one result-oriented line: (a) trailhead hook present and executable (`test -x`): git does enforce trailhead's rules here, but its freshness could not be checked or upgraded, so suggest updating the trailhead install; a trailhead hook that is NOT executable: git skips it, so it does not enforce trailhead's rules here (suggest updating the install so the sync script can fix the mode); (b) a foreign hook (or a symlink): left untouched, git does not enforce trailhead's rules here; (c) no hook: git does not enforce trailhead's rules here (suggest updating the install so the sync script can install it). Never blocks the work.
+**The commit-msg git hook (host-independent commit guard).** On every host trailhead ALSO installs a git **`commit-msg`** hook as a host-independent backstop (defence in depth alongside the host's own `PreToolUse` guard on Claude Code and Codex alike), enforcing the two rules (a Conventional Commits subject of at most 72 chars; never a `Co-Authored-By` trailer) plus, while a `.trailhead/session-ticket` marker is present at the worktree root, a `Refs: #<n>` trailer matching its number, on every `git commit`, whatever host drives it (decision #16). **Every chart or adopt, and at every `work`/`quick` ticket start, run the sync script**: `node <templates>/trailhead-commit-msg-sync.js --repo <working-root>`, where `<templates>` is the first of `${CLAUDE_PLUGIN_ROOT}/templates/`, `~/.claude/trailhead/templates/`, `~/.codex/skills/trailhead/templates/` that contains `trailhead-commit-msg-sync.js`: try all three in order, skipping the first when `CLAUDE_PLUGIN_ROOT` is unset or empty (it is often absent from the Bash environment), and never stop at the first miss. It prints one JSON status line and handles every case itself: absent -> installs it; an older trailhead hook (recognised by its own header line, not by trusting the filename) -> upgraded in place; already current -> left alone; a foreign (non-trailhead) hook -> never touched, only reported (offer to chain it); under a repo's `core.hooksPath`, an existing trailhead hook there is still upgraded in place, but nothing is newly added to that directory. Unlike the label guard, `.git/hooks/` is not version-controlled, so this is a per-clone local install with nothing to commit. **If the sync script is missing (none of the three dirs has it: an outdated install) or node errors, never claim git enforces nothing before looking**: resolve the effective hooks dir with `git -C <working-root> rev-parse --git-path hooks` (resolve a relative output against the working root; it honours `core.hooksPath` and the git common dir shared by linked worktrees), read `<hooks dir>/commit-msg`, and classify it by its header line (a trailhead hook has `// trailhead commit-msg hook (git).` among its first 5 lines, trimmed; never trust the filename alone; a symlinked `commit-msg` counts as foreign, as the script treats it). Report one result-oriented line: (a) trailhead hook present and executable (`test -x`): git does enforce trailhead's rules here, but its freshness could not be checked or upgraded, so suggest updating the trailhead install; a trailhead hook that is NOT executable: git skips it, so it does not enforce trailhead's rules here (suggest updating the install so the sync script can fix the mode); (b) a foreign hook (or a symlink): left untouched, git does not enforce trailhead's rules here; (c) no hook: git does not enforce trailhead's rules here (suggest updating the install so the sync script can install it). Never blocks the work.

package/plugins/trailhead/skills/_shared/techniques/prototype.md

@@ -31,7 +31,7 @@ If genuinely ambiguous and the user's unreachable, default by context (backend m
 
 Either way the rough screen is **reacted to before real UI code**.
 
-**"Surface the mockup" means: put its link in the same message that asks for the reaction.** The user can't react to what they can't open. Every message that asks to approve, react to, or pick between mockups **must carry, in that same message and right before the question**, the direct clickable location of each screen it refers to: the file path (`disk`), the Artifact / claude.ai/design project URL (`canvas`), the design-system project URL plus the screen's page (`design-system`), or the Stitch project/screen URL (`stitch`), one line per screen or variant. A link given earlier in the conversation, only in a ticket comment, or implied ("the mockup above") does **not** count: scrollback scrolls away and a structured question UI hides the preceding text. When the question goes through a structured prompt (e.g. an options picker), repeat the link(s) inside the question text itself. If you don't have a link to show yet (publish failed, URL not returned), **do not ask for approval**: fix the publish or report the failure first.
+**"Surface the mockup" means: put its link in the same message that asks for the reaction.** The user can't react to what they can't open. Every message that asks to approve, react to, or pick between mockups **must carry, in that same message and right before the question**, the direct clickable location of each screen it refers to: the file path (`disk`), the Artifact / claude.ai/design project URL (`canvas`), the design-system project URL plus the screen's page (`design-system`), or the Stitch project/screen URL (`stitch`), one line per screen or variant. A link given earlier in the conversation, only in a ticket comment, or implied ("the mockup above") does **not** count: scrollback scrolls away. **Write the link(s) in the plain prose of the message, never inside a structured prompt**: an options picker renders its question and options as plain text, so a link put there is not clickable (above all on mobile). When the approval then goes through a structured prompt, keep every link in the prose just before it and let the picker ask only a plain yes/no: approve the mockup (yes) or request changes (no); for a pick between variants, name each variant in the options and keep their links in the prose. If you don't have a link to show yet (publish failed, URL not returned), **do not ask for approval**: fix the publish or report the failure first. The project's or design system's **name is not a link** ("the mockup is ready on MyApp" without the URL fails this rule), and the link must sit in the reply **text**, not only in your reasoning. A hook enforces this: on Claude Code the **mockup-link guard** blocks a mockup-approval `AskUserQuestion` whose preceding reply text carries no URL or file path; on Codex **mockup-link-stop** continues a final reply that asks for the approval without one. When either fires, write the link(s) in the prose and ask again.
 
 How approval gates the build depends on `config.design.approval`:
 - **`explicit` (default)**: surface the mockup and **wait for the user's clear go-ahead**; do not write UI code until they approve. Record the approval on the ticket, then proceed.

package/plugins/trailhead/skills/trailhead/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: trailhead
 description: "Start and drive a large project (more than one agent session can hold) as a map of decision tickets on GitHub Issues, resolving one at a time until the way to the destination is clear. Self-contained (zero external-plugin dependencies: trailhead ships its own `trailhead-*` engine agents and needs only an authenticated gh CLI): map-based onboarding and a discuss→plan→execute→verify engine with atomic commits, with everything (map, discussion, plan, verification) living on the Issues. Invoke only when the user explicitly runs `/trailhead` (or a `/trailhead:<verb>` command) or asks to chart, adopt, or work a trailhead map, and do not auto-invoke for generic planning, project, or task-tracking requests."
-argument-hint: "[new|adopt|work|quick|whiteboard|ticket|inbox|map|dashboard|config|grill|split|pause|resume|auto|update|prune|bug|todo|idea|seed|note] [text | ticket]"
+argument-hint: "[new|adopt|work|quick|whiteboard|ticket|inbox|map|dashboard|config|grill|split|pause|resume|auto|update|prune|audit|bug|todo|idea|seed|note] [text | ticket]"
 ---
 
 `trailhead` charts a large project as a **shared map on GitHub Issues**, then works its **tickets** one at a time until the way to the destination is clear. This skill is the **entry point**: bare `/trailhead` runs **smart entry** (detect the repo state and propose the next move); a verb runs that verb's engine. Everything lives on the Issues; the repo holds code only.
@@ -15,7 +15,7 @@ Before doing anything, read `../_shared/load-first.md` and follow it: the shared
 The **first word** of the arguments is the verb; the rest is the text or a ticket number. `/trailhead <verb>` and `/trailhead:<verb>` are equivalent.
 
 - **No verb** to **smart entry** (below): this skill handles it directly.
-- **A verb** to hand off to the skill that owns it, passing the whole argument string. **The skill-split migration ([map #53](https://github.com/ToRvaLDz/trailhead/issues/53)) lands the cluster skills one at a time.** The **chart cluster is built (#59)**: `new`, `adopt`, `ticket`, `inbox`, and `grill` route to the **`trailhead-chart`** skill (call the Skill tool with skill name `trailhead-chart` and arguments `<verb> <rest>`). The **work cluster is built (#60)**: `work`, `quick`, `pause`, `resume`, `split`, and `auto` route to the **`trailhead-work`** skill (call the Skill tool with skill name `trailhead-work` and arguments `<verb> <rest>`). The **view cluster is built (#61)**: `map`, `dashboard`, and `whiteboard` route to the **`trailhead-view`** skill (call the Skill tool with skill name `trailhead-view` and arguments `<verb> <rest>`). The **capture cluster is built (#62)**: `bug`, `todo`, `idea`, `seed`, and `note` route to the **`trailhead-capture`** skill (call the Skill tool with skill name `trailhead-capture` and arguments `<verb> <rest>`). The **manage cluster is built (#63)**: `config`, `update`, and `prune` route to the **`trailhead-manage`** skill (call the Skill tool with skill name `trailhead-manage` and arguments `<verb> <rest>`). Then carry out the target skill's instructions.
+- **A verb** to hand off to the skill that owns it, passing the whole argument string. **The skill-split migration ([map #53](https://github.com/ToRvaLDz/trailhead/issues/53)) lands the cluster skills one at a time.** The **chart cluster is built (#59)**: `new`, `adopt`, `ticket`, `inbox`, and `grill` route to the **`trailhead-chart`** skill (call the Skill tool with skill name `trailhead-chart` and arguments `<verb> <rest>`). The **work cluster is built (#60)**: `work`, `quick`, `pause`, `resume`, `split`, and `auto` route to the **`trailhead-work`** skill (call the Skill tool with skill name `trailhead-work` and arguments `<verb> <rest>`). The **view cluster is built (#61)**: `map`, `dashboard`, and `whiteboard` route to the **`trailhead-view`** skill (call the Skill tool with skill name `trailhead-view` and arguments `<verb> <rest>`). The **capture cluster is built (#62)**: `bug`, `todo`, `idea`, `seed`, and `note` route to the **`trailhead-capture`** skill (call the Skill tool with skill name `trailhead-capture` and arguments `<verb> <rest>`). The **manage cluster is built (#63)**: `config`, `update`, `prune`, and `audit` route to the **`trailhead-manage`** skill (call the Skill tool with skill name `trailhead-manage` and arguments `<verb> <rest>`). Then carry out the target skill's instructions.
 - **Unrecognised verb** to treat the whole string as `idea` (route to `trailhead-capture` as `idea <text>`).
 
 The namespaced `/trailhead:<verb>` commands reach their target skill directly through their own command wrapper; this routing table only covers the bare `/trailhead <verb>` form.

package/plugins/trailhead/skills/trailhead-capture/references/capture.md

@@ -2,7 +2,7 @@
 
 Capture without breaking flow, but with the **tracker** as destination, not scattered files. The verbs are named in this cluster's `../SKILL.md`; here is the detail of each. One capture = one action + one confirmation line; it resolves nothing.
 
-**Confirmation line.** Confirm the capture by the ticket's name (not a bare `#number`) and where it landed. **If you point at working it later, lead with `/clear`**: the confirmation is a place you point at the next ticket, so the [Session handoff](../../_shared/session-handoff.md)'s `/clear`-first rule applies: a compact, future-conditional one-liner is fine (a capture is not a resolution, so no full labelled block), along the lines of *"to work it later: `/clear`, then `/trailhead:work 45`; or, for the lighter path, `/trailhead:quick 45`"* (in the user's conversation language). Never a bare `/trailhead:work 45` with no `/clear`, and (the same post-`/clear` invariant the [Session handoff](../../_shared/session-handoff.md) states) **never place after `/clear` an action the agent must perform that depends on context `/clear` erases**: a capture confirmation points only at user-runnable commands, which satisfies this by construction, so keep it that way. **Whenever the confirmation does point at working the ticket (a `seed` parked on its trigger, or a fog `note`/`idea` that is not a ticket yet, is the case where it does not), anchor the next step to `/trailhead:work <n>`, always:** it is the recommendation (the full engine, which can split and keeps the map record), and the confirmation names it first. `/trailhead:quick <n>` is the **lighter alternative** (a single alternative, not two): it works that same ticket whole right now, always size-triaged so on a small change it offers to skip the heavy steps (plan pass, TDD, full code review, goal-backward verify) on an explicit yes, grills only if needed, skips the map narrative book-keeping, and never splits; a map ticket stays on its map, so never call it "off the map". **Describe it by that purpose (the lighter, faster path), never as merely "without splitting"**: not splitting is a side effect, not what `quick` is for. It is offered *alongside* `work`, **never in its place** and **never rendered twice on one line**. This holds for a **whiteboard** capture too, where both apply (`quick` is the no-split variant of `work`): the anchor stays `/trailhead:work <n>` for consistency. Same spirit as chart's codified close (#147). Render the command in this host's command forms (the **Host command forms** rule in `../../_shared/load-first.md`).
+**Confirmation line.** Confirm the capture by the ticket's name and its number, both visible (e.g. *Add login rate limit* (#45), never the name alone nor a bare `#number`), and where it landed. **If you point at working it later, lead with `/clear`**: the confirmation is a place you point at the next ticket, so the [Session handoff](../../_shared/session-handoff.md)'s `/clear`-first rule applies: a compact, future-conditional one-liner is fine (a capture is not a resolution, so no full labelled block), along the lines of *"to work it later: `/clear`, then `/trailhead:work 45`; or, for the lighter path, `/trailhead:quick 45`"* (in the user's conversation language). Never a bare `/trailhead:work 45` with no `/clear`, and (the same post-`/clear` invariant the [Session handoff](../../_shared/session-handoff.md) states) **never place after `/clear` an action the agent must perform that depends on context `/clear` erases**: a capture confirmation points only at user-runnable commands, which satisfies this by construction, so keep it that way. **Whenever the confirmation does point at working the ticket (a `seed` parked on its trigger, or a fog `note`/`idea` that is not a ticket yet, is the case where it does not), anchor the next step to `/trailhead:work <n>`, always:** it is the recommendation (the full engine, which can split and keeps the map record), and the confirmation names it first. `/trailhead:quick <n>` is the **lighter alternative** (a single alternative, not two): it works that same ticket whole right now, always size-triaged so on a small change it offers to skip the heavy steps (plan pass, TDD, full code review, goal-backward verify) on an explicit yes, grills only if needed, skips the map narrative book-keeping, and never splits; a map ticket stays on its map, so never call it "off the map". **Describe it by that purpose (the lighter, faster path), never as merely "without splitting"**: not splitting is a side effect, not what `quick` is for. It is offered *alongside* `work`, **never in its place** and **never rendered twice on one line**. This holds for a **whiteboard** capture too, where both apply (`quick` is the no-split variant of `work`): the anchor stays `/trailhead:work <n>` for consistency. Same spirit as chart's codified close (#147). Render the command in this host's command forms (the **Host command forms** rule in `../../_shared/load-first.md`).
 
 **Language (do not skip):** the captured ticket (title + body) is written in `config.ticket.language` (default `en`), **regardless of the language you are chatting in**. A capture fired in Italian still lands as an English ticket. This is the easiest place to slip, because a capture echoes the user's one-line phrasing; translate it, do not mirror it. See the *Ticket language* rule in `../../_shared/ticket-language.md`.
 

package/plugins/trailhead/skills/trailhead-manage/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: trailhead-manage
 user-invocable: false
-description: "trailhead manage cluster: the admin verbs that keep a trailhead install healthy. Show the effective config or change it through a guided menu (config); check for a newer trailhead and install it where that is safe (update), and prune a map's sub-issue edges to reclaim slots under GitHub's 100-cap (prune). A cohesion cluster of the trailhead skill split, loading the shared `_shared/` core; reached through the `/trailhead:<verb>` command wrappers and the bare `/trailhead` dispatcher. Not auto-invoked: it runs only when one of these verbs is dispatched."
-argument-hint: "[config|update|prune] [get|set … | map]"
+description: "trailhead manage cluster: the admin verbs that keep a trailhead install healthy. Show the effective config or change it through a guided menu (config); check for a newer trailhead and install it where that is safe (update), prune a map's sub-issue edges to reclaim slots under GitHub's 100-cap (prune), and audit closed tickets for regressions against the code and the open ones for duplicates (audit). A cohesion cluster of the trailhead skill split, loading the shared `_shared/` core; reached through the `/trailhead:<verb>` command wrappers and the bare `/trailhead` dispatcher. Not auto-invoked: it runs only when one of these verbs is dispatched."
+argument-hint: "[config|update|prune|audit] [get|set … | map | --all]"
 ---
 
-`trailhead-manage` is the **manage cluster** of the trailhead skill: the admin verbs that keep a trailhead install healthy. `config` shows the effective config or changes it (a guided menu, or `get` / `set <key> <value>`); `update` checks for a newer trailhead and installs it where that is safe; `prune` reclaims a map's native sub-issue slots under GitHub's 100-cap. Everything lives on the GitHub Issues; the repo holds code only.
+`trailhead-manage` is the **manage cluster** of the trailhead skill: the admin verbs that keep a trailhead install healthy. `config` shows the effective config or changes it (a guided menu, or `get` / `set <key> <value>`); `update` checks for a newer trailhead and installs it where that is safe; `prune` reclaims a map's native sub-issue slots under GitHub's 100-cap; `audit` checks closed tickets for regressions against today's code and finds duplicate or groupable open ones. Everything lives on the GitHub Issues; the repo holds code only.
 
 ## Load first, in order
 
@@ -15,10 +15,11 @@ These admin verbs resolve no ticket and set up no isolation workspace.
 
 ## Routing: verb to engine
 
-The **first word** of the arguments is the verb (`config`, `update`, or `prune`); the rest is that verb's argument (`get`, `set <key> <value>`, a map, or empty).
+The **first word** of the arguments is the verb (`config`, `update`, `prune`, or `audit`); the rest is that verb's argument (`get`, `set <key> <value>`, a map, `--all`, or empty).
 
 - **`config [get|set …]`** to **`../_shared/configuration-reference.md`**: the config keys, their semantics, and the guided menu setup. With no argument it runs the guided setup; `config get` prints the merged config read-only (project `.trailhead/config.json` over global over defaults, showing which source wins each key); `config set <key> <value>` writes one key directly (to the project `.trailhead/config.json`, or to `~/.claude/trailhead/config.json` with `--global`). Read that file and follow it.
 - **`update`** to **`references/updating.md`**: the update protocol (detect the install channel, compare the installed version with the latest from the matching source, install the newer one where it is safe). Read that file and follow it.
 - **`prune [map]`** to **`references/pruning.md`**: reclaim native sub-issue slots on a map near or at GitHub's 100 sub-issue cap by dropping the edges of closed and orphan tickets and re-adding missing ones, keeping every reference (Parent line, Decisions-so-far pointer, map label). With no argument it prunes the active map. Read that file and follow it.
+- **`audit [map] [--all]`** to **`references/auditing.md`**: audit the closed tickets since the last audit (or all of them with `--all`) for regressions against the current code (a fast no-agent path for unchanged code), classing each as implemented, unchanged, evolved, implemented wrong, or not implemented, and compare the open tickets for duplicates and groupable clusters; every fix is a proposal applied only on an explicit yes. With no argument it covers every open map plus the whiteboard; with a map it covers that map only. Read that file and follow it.
 
 The full config **key reference** is a single source, shared with the rest of the skill: `../_shared/configuration-reference.md` (keys + guided setup).