@marcomigozzi/trailhead 0.11.0 → 0.12.0

package/plugins/trailhead/hooks/trailhead-mockup-link-guard.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// trailhead-mockup-link-guard.js: PreToolUse(AskUserQuestion) hook.
+// Structural backstop for the Prototype technique's "surface the mockup" rule
+// (_shared/techniques/prototype.md): a message that asks to approve, react to,
+// or pick between mockups must carry each mockup's clickable link in its
+// plain prose, right before the question. The prose rule alone was skipped in
+// practice (an approval asked with only the project's name, no URL), so this
+// hook blocks an AskUserQuestion that is a mockup-approval ask when the
+// assistant prose immediately before it (no tool call in between) holds no
+// URL or file path.
+// Blocks with exit 2 + {"decision":"block",...}; allows everything else.
+// Fail-OPEN on any error (exit 0): a missing/unreadable transcript or an
+// unexpected shape must never wedge the workflow.
+// Claude-Code-specific (Codex has no AskUserQuestion tool; its twin there is
+// trailhead-mockup-link-stop.js). Detection lives in lib/mockup-link.js.
+// Pure functions are exported for tests; runs as a hook when executed directly.
+
+const fs = require('fs');
+const { hasLink, isMockupApprovalAsk, BLOCK_REASON } = require('./lib/mockup-link.js');
+
+// Only the transcript tail matters: the prose sits right before the ask.
+const TAIL_BYTES = 512 * 1024;
+
+const blocksOf = (e) => (Array.isArray(e.message && e.message.content) ? e.message.content : []);
+const isPendingAsk = (e) => e.type === 'assistant'
+  && blocksOf(e).some((b) => b.type === 'tool_use' && b.name === 'AskUserQuestion');
+
+// The assistant prose right before the ask: walk the main-chain entries back
+// from the end, skip the pending AskUserQuestion entries, and collect text
+// blocks until anything else (a user turn, a tool result, another tool call).
+function proseBeforeAsk(entries) {
+  const main = entries.filter((e) => e && (e.type === 'assistant' || e.type === 'user') && !e.isSidechain);
+  let i = main.length - 1;
+  while (i >= 0 && isPendingAsk(main[i])) i--;
+  const texts = [];
+  for (; i >= 0; i--) {
+    const e = main[i];
+    if (e.type !== 'assistant') break;
+    const blocks = blocksOf(e);
+    if (blocks.some((b) => b.type === 'tool_use')) break;
+    blocks.filter((b) => b.type === 'text').forEach((b) => texts.unshift(b.text || ''));
+  }
+  return texts.join('\n');
+}
+
+function readTail(file) {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    const len = Math.min(size, TAIL_BYTES);
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, size - len);
+    return buf.toString('utf8');
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// Parse JSONL leniently: the first line of a tail read may be cut mid-record.
+function parseEntries(text) {
+  return text.split('\n').flatMap((l) => {
+    try { return l.trim() ? [JSON.parse(l)] : []; } catch { return []; }
+  });
+}
+
+function block() {
+  process.stdout.write(JSON.stringify({ decision: 'block', code: 'MOCKUP_LINK_MISSING', reason: BLOCK_REASON }));
+  process.exit(2);
+}
+
+function run(data) {
+  try {
+    const payload = JSON.parse(data);
+    if (payload.tool_name && payload.tool_name !== 'AskUserQuestion') process.exit(0);
+    if (!isMockupApprovalAsk(payload.tool_input)) process.exit(0);
+    if (!payload.transcript_path) process.exit(0);
+    const prose = proseBeforeAsk(parseEntries(readTail(payload.transcript_path)));
+    if (!hasLink(prose)) block();
+  } catch {
+    // fall through to allow: a guard must never wedge the workflow
+  }
+  process.exit(0);
+}
+
+if (require.main === module) {
+  let data = '';
+  const timer = setTimeout(() => process.exit(0), 5000); // stdin never ends -> give up
+  process.stdin.on('data', (c) => (data += c));
+  process.stdin.on('end', () => {
+    clearTimeout(timer);
+    run(data);
+  });
+}
+
+module.exports = { isMockupApprovalAsk, hasLink, proseBeforeAsk };

package/plugins/trailhead/hooks/trailhead-mockup-link-guard.test.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// Tests for trailhead-mockup-link-guard.js. Run: node trailhead-mockup-link-guard.test.js
+// No framework: plain asserts + child_process for the end-to-end hook behaviour.
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const {
+  isMockupApprovalAsk,
+  hasLink,
+  proseBeforeAsk,
+} = require('./trailhead-mockup-link-guard.js');
+
+const HOOK = path.join(__dirname, 'trailhead-mockup-link-guard.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// Costruttori di righe transcript (stesso shape JSONL di Claude Code)
+const text = (t) => ({ type: 'assistant', isSidechain: false, message: { content: [{ type: 'text', text: t }] } });
+const thinking = () => ({ type: 'assistant', isSidechain: false, message: { content: [{ type: 'thinking', thinking: '' }] } });
+const toolUse = (name, input = {}) => ({ type: 'assistant', isSidechain: false, message: { content: [{ type: 'tool_use', id: 'x', name, input }] } });
+const toolResult = (c) => ({ type: 'user', isSidechain: false, message: { content: [{ type: 'tool_result', tool_use_id: 'x', content: c }] } });
+const userPrompt = (c) => ({ type: 'user', isSidechain: false, message: { content: c } });
+
+const approvalInput = {
+  questions: [{
+    question: 'Approvi il mockup della pagina FAQ?',
+    header: 'Mockup',
+    multiSelect: false,
+    options: [{ label: 'Approvo', description: 'Procedi col codice UI' }, { label: 'Chiedo modifiche', description: '' }],
+  }],
+};
+
+// --- isMockupApprovalAsk ---
+ok('IT mockup approval ask is detected', isMockupApprovalAsk(approvalInput));
+ok('EN mockup approval ask is detected', isMockupApprovalAsk({
+  questions: [{ question: 'Do you approve the login mockup?', options: [{ label: 'Approve' }, { label: 'Request changes' }] }],
+}));
+ok('pick between prototype variants is detected', isMockupApprovalAsk({
+  questions: [{ question: 'Quale variante del prototipo scegli?', options: [{ label: 'Variante A' }, { label: 'Variante B' }] }],
+}));
+ok('"want mockups first?" offer is NOT an approval ask', !isMockupApprovalAsk({
+  questions: [{ question: 'Vuoi prima un mockup della schermata?', options: [{ label: 'Sì' }, { label: 'No' }] }],
+}));
+// Regressione da una sessione reale: l'offerta di un mockup cita una
+// approvazione futura solo nella descrizione dell'opzione
+ok('mockup offer whose option description mentions approval is NOT an approval ask', !isMockupApprovalAsk({
+  questions: [{
+    question: 'Vuoi cambiare qualcosa nello scope della pagina FAQ?',
+    header: 'Scope',
+    options: [
+      { label: 'Va bene così', description: 'Procedo con lo scope descritto' },
+      { label: 'Prima un mockup', description: 'Disegno la pagina su claude.ai/design e attendo approvazione prima di scriverla' },
+    ],
+  }],
+}));
+ok('mockup and approval words in different questions do not combine', !isMockupApprovalAsk({
+  questions: [
+    { question: 'Vuoi prima un mockup?', options: [{ label: 'Sì' }] },
+    { question: 'Approvi il piano?', options: [{ label: 'Sì' }] },
+  ],
+}));
+ok('unrelated ask is not detected', !isMockupApprovalAsk({
+  questions: [{ question: 'Approvi il piano?', options: [{ label: 'Sì' }, { label: 'No' }] }],
+}));
+ok('malformed input is not detected', !isMockupApprovalAsk({}) && !isMockupApprovalAsk(null));
+
+// --- hasLink ---
+ok('https URL counts as a link', hasLink('Ecco: https://claude.ai/design/p/abc?file=faq.html'));
+ok('absolute html path counts as a link', hasLink('Mockup in /home/u/app/mockups/faq.html'));
+ok('relative html path counts as a link', hasLink('apri `mockups/faq.html`'));
+ok('markdown link to a file counts', hasLink('[faq](mockups/faq.html)'));
+ok('project name alone is NOT a link', !hasLink('Il mockup della pagina FAQ è pronto su MyApp, gruppo Marketing.'));
+ok('empty prose has no link', !hasLink(''));
+
+// --- proseBeforeAsk ---
+const failing = [
+  userPrompt('lavora #12'),
+  toolUse('Bash'),
+  toolResult('ok'),
+  thinking(),
+  text('Il mockup della pagina FAQ è pronto su MyApp, con indice sezioni.'),
+  toolUse('AskUserQuestion', approvalInput),
+];
+ok('prose right before the ask is collected', /pronto su MyApp/.test(proseBeforeAsk(failing)));
+
+const linkBeforeTools = [
+  userPrompt('lavora #12'),
+  text('Mockup: https://claude.ai/design/p/abc'),
+  toolUse('Bash'),
+  toolResult('ok'),
+  text('Pronto.'),
+  toolUse('AskUserQuestion', approvalInput),
+];
+ok('a link before an intervening tool call does not count', !hasLink(proseBeforeAsk(linkBeforeTools)));
+
+const sidechain = [
+  text('Mockup FAQ pronto.'),
+  { ...text('https://example.com/side'), isSidechain: true },
+  toolUse('AskUserQuestion', approvalInput),
+];
+ok('sidechain text is ignored', !hasLink(proseBeforeAsk(sidechain)));
+
+const noAskYet = [userPrompt('x'), text('Ecco https://a.b/c')];
+ok('works when the pending tool_use is not yet in the transcript', hasLink(proseBeforeAsk(noAskYet)));
+
+// --- end-to-end ---
+function writeTranscript(entries) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'th-mlg-'));
+  const f = path.join(dir, 't.jsonl');
+  fs.writeFileSync(f, entries.map((e) => JSON.stringify(e)).join('\n') + '\n');
+  return f;
+}
+function runHook(payload) {
+  try {
+    const out = execFileSync('node', [HOOK], { input: JSON.stringify(payload) });
+    return { code: 0, out: out.toString() };
+  } catch (e) {
+    return { code: e.status, out: (e.stdout || '').toString() };
+  }
+}
+
+const r1 = runHook({ tool_name: 'AskUserQuestion', tool_input: approvalInput, transcript_path: writeTranscript(failing) });
+ok('approval ask without a link in the prose is blocked (exit 2)', r1.code === 2 && /MOCKUP_LINK_MISSING/.test(r1.out));
+
+const withLink = [...failing.slice(0, 4), text('Mockup: https://claude.ai/design/p/abc?file=faq.html'), failing[5]];
+const r2 = runHook({ tool_name: 'AskUserQuestion', tool_input: approvalInput, transcript_path: writeTranscript(withLink) });
+ok('approval ask with a link in the prose is allowed', r2.code === 0 && r2.out.trim() === '');
+
+const r3 = runHook({ tool_name: 'AskUserQuestion', tool_input: approvalInput, transcript_path: '/nonexistent/t.jsonl' });
+ok('missing transcript fails open', r3.code === 0);
+
+const r4 = runHook({ tool_name: 'Bash', tool_input: { command: 'ls' }, transcript_path: writeTranscript(failing) });
+ok('other tools are ignored', r4.code === 0);
+
+const r5 = runHook({ tool_name: 'AskUserQuestion', tool_input: { questions: [{ question: 'Approvi il piano?', options: [] }] }, transcript_path: writeTranscript(failing) });
+ok('non-mockup ask is allowed', r5.code === 0);
+
+let r6;
+try { execFileSync('node', [HOOK], { input: 'not json' }); r6 = 0; } catch (e) { r6 = e.status; }
+ok('unparseable input fails open', r6 === 0);
+
+console.log(`trailhead-mockup-link-guard: ${passed} passed`);

package/plugins/trailhead/hooks/trailhead-mockup-link-stop.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// trailhead-mockup-link-stop.js: Stop hook (Codex).
+// Codex twin of trailhead-mockup-link-guard.js. On Codex trailhead asks its
+// questions as a plain-text numbered list (request_user_input is Plan-Mode
+// only), so there is no tool call to gate: this hook reads the final reply
+// (`last_assistant_message`) instead. When the reply asks to approve a mockup
+// (or pick between mockup variants) and carries no URL or file path, it
+// answers {"decision":"block","reason":...}: on Stop, Codex does not reject
+// the turn but continues it, with the reason as the next prompt, so the agent
+// rewrites the ask with the link.
+// Never blocks a turn that was already continued (`stop_hook_active`), so it
+// cannot loop. Fail-OPEN on any error (exit 0, no output).
+
+const { hasLink, isMockupApprovalMessage, BLOCK_REASON } = require('./lib/mockup-link.js');
+
+function run(data) {
+  try {
+    const payload = JSON.parse(data);
+    if (payload.stop_hook_active) process.exit(0);
+    const msg = payload.last_assistant_message;
+    if (isMockupApprovalMessage(msg) && !hasLink(msg)) {
+      process.stdout.write(JSON.stringify({ decision: 'block', reason: BLOCK_REASON }));
+    }
+  } catch {
+    // fall through to allow: a guard must never wedge the workflow
+  }
+  process.exit(0);
+}
+
+if (require.main === module) {
+  let data = '';
+  const timer = setTimeout(() => process.exit(0), 5000); // stdin never ends -> give up
+  process.stdin.on('data', (c) => (data += c));
+  process.stdin.on('end', () => {
+    clearTimeout(timer);
+    run(data);
+  });
+}

package/plugins/trailhead/hooks/trailhead-mockup-link-stop.test.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// Tests for trailhead-mockup-link-stop.js (+ lib/mockup-link.js message detection).
+// Run: node trailhead-mockup-link-stop.test.js
+const assert = require('assert');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { isMockupApprovalMessage } = require('./lib/mockup-link.js');
+
+const HOOK = path.join(__dirname, 'trailhead-mockup-link-stop.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// Risposta Codex: la domanda è un elenco numerato in testo semplice
+const noLink = [
+  'Il mockup della pagina FAQ è pronto su MyApp, con indice sezioni.',
+  '',
+  'Approvi il mockup della pagina FAQ?',
+  '1. Approvo',
+  '2. Chiedo modifiche',
+].join('\n');
+const withLink = noLink.replace('pronto su MyApp', 'pronto: https://claude.ai/design/p/abc?file=faq.html');
+
+// --- isMockupApprovalMessage ---
+ok('IT approval reply is detected', isMockupApprovalMessage(noLink));
+ok('EN approval reply is detected', isMockupApprovalMessage('Mockup ready.\n\nDo you approve the login mockup?\n1. Yes\n2. No'));
+ok('variant pick is detected', isMockupApprovalMessage('Due prototipi pronti.\nQuale variante scegli?\n1. A\n2. B'));
+ok('past approval mention is NOT an ask', !isMockupApprovalMessage('Ho implementato il mockup approvato. Commit fatto.'));
+ok('approval word without a question line is NOT an ask', !isMockupApprovalMessage('Approvi il mockup quando vuoi.'));
+ok('"want mockups first?" offer is NOT an ask', !isMockupApprovalMessage('Vuoi prima un mockup?\n1. Sì\n2. No'));
+ok('non-string is not detected', !isMockupApprovalMessage(undefined));
+
+// --- end-to-end ---
+function runHook(payload) {
+  try {
+    const out = execFileSync('node', [HOOK], { input: typeof payload === 'string' ? payload : JSON.stringify(payload) });
+    return { code: 0, out: out.toString() };
+  } catch (e) {
+    return { code: e.status, out: (e.stdout || '').toString() };
+  }
+}
+const parse = (s) => { try { return JSON.parse(s); } catch { return null; } };
+
+const r1 = runHook({ hook_event_name: 'Stop', stop_hook_active: false, last_assistant_message: noLink });
+const j1 = parse(r1.out);
+ok('approval reply without a link: continues the turn with a block decision (exit 0, JSON)',
+  r1.code === 0 && j1 && j1.decision === 'block' && /mockup-link/.test(j1.reason));
+
+const r2 = runHook({ hook_event_name: 'Stop', stop_hook_active: false, last_assistant_message: withLink });
+ok('approval reply with a link is allowed', r2.code === 0 && r2.out.trim() === '');
+
+const r3 = runHook({ hook_event_name: 'Stop', stop_hook_active: true, last_assistant_message: noLink });
+ok('already-continued turn is never blocked again (no loop)', r3.code === 0 && r3.out.trim() === '');
+
+const r4 = runHook({ hook_event_name: 'Stop', stop_hook_active: false });
+ok('missing last_assistant_message fails open', r4.code === 0 && r4.out.trim() === '');
+
+const r5 = runHook({ hook_event_name: 'Stop', last_assistant_message: 'Fatto, commit pushato.' });
+ok('ordinary reply is allowed', r5.code === 0 && r5.out.trim() === '');
+
+const r6 = runHook('not json');
+ok('unparseable input fails open', r6.code === 0 && r6.out.trim() === '');
+
+console.log(`trailhead-mockup-link-stop: ${passed} passed`);

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.