@marcomigozzi/trailhead 0.7.0 → 0.8.1

package/plugins/trailhead/hooks/trailhead-search-guard.test.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Tests for trailhead-search-guard.js. Run: node trailhead-search-guard.test.js
+// No framework: plain asserts + child_process for the end-to-end hook behaviour.
+const assert = require('assert');
+const { execFileSync } = require('child_process');
+const path = require('path');
+
+const HOOK = path.join(__dirname, 'trailhead-search-guard.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// Run the hook end-to-end: pipe tool_input JSON on stdin, capture {code, out}.
+function runHook(command) {
+  const input = JSON.stringify({ tool_input: { command } });
+  try {
+    const out = execFileSync('node', [HOOK], { input });
+    return { code: 0, out: out.toString() };
+  } catch (e) {
+    return { code: e.status, out: (e.stdout || '').toString(), err: (e.stderr || '').toString() };
+  }
+}
+
+// --- ticket #134: the exact regression command must be BLOCKED ---
+const ticketCmd = String.raw`cd app && grep -n "go_router" pubspec.yaml pubspec.lock | head; echo "=== router file ==="; grep -rln "GoRouter(" lib/ ; echo "=== /who route def ==="; grep -rn "'/who'\|\"/who\"\|/profile/manage\|path: '/home'" lib/ | head -30`;
+const rTicket = runHook(ticketCmd);
+ok('ticket #134 exact command is blocked (exit 2)', rTicket.code === 2 && /SEARCH_HYGIENE_VIOLATION|search-hygiene/.test(rTicket.out));
+
+// --- BLOCK cases ---
+const r1 = runHook('cd app && grep -n "go_router" pubspec.yaml');
+ok('cd <relative> && grep <relative> is blocked (exit 2)', r1.code === 2 && /search-hygiene/.test(r1.out));
+
+const r2 = runHook('cd /abs/app; grep -rln "GoRouter(" lib/');
+ok('cd <abs>; grep <relative> is blocked (exit 2)', r2.code === 2 && /search-hygiene/.test(r2.out));
+
+const r3 = runHook('pushd app && cat file.txt');
+ok('pushd <dir> && cat <relative> is blocked (exit 2)', r3.code === 2 && /search-hygiene/.test(r3.out));
+
+const r4 = runHook('cd app && wc -l foo.txt');
+ok('cd <dir> && wc -l <relative> is blocked (exit 2)', r4.code === 2 && /search-hygiene/.test(r4.out));
+
+const r5 = runHook('cd app &&\ngrep -n "x" foo.txt\n');
+ok('cd <dir> && then relative grep on a later line (newline-joined) is blocked (exit 2)', r5.code === 2 && /search-hygiene/.test(r5.out));
+
+const r6 = runHook('cd app; echo hi; grep -n "x" foo.txt');
+ok('cd <dir>; ...; relative grep several statements later is blocked (exit 2)', r6.code === 2 && /search-hygiene/.test(r6.out));
+
+const r7 = runHook('env -C app grep -n "x" foo.txt');
+ok('env -C <dir> grep <relative> (single statement) is blocked (exit 2)', r7.code === 2 && /search-hygiene/.test(r7.out));
+
+const r8 = runHook('cd app && git log -- foo.txt');
+ok('cd <dir> && git log without -C on a relative path is blocked (exit 2)', r8.code === 2 && /search-hygiene/.test(r8.out));
+
+const r9 = runHook('cd app && rg "TODO" foo.txt');
+ok('cd <dir> && rg <relative> is blocked (exit 2)', r9.code === 2 && /search-hygiene/.test(r9.out));
+
+// --- ALLOW cases (no false positives) ---
+const a1 = runHook('grep -n "x" /abs/app/pubspec.yaml');
+ok('path-explicit grep with no cd is allowed (exit 0)', a1.code === 0 && a1.out.trim() === '');
+
+const a2 = runHook('git -C /abs/app grep "x"');
+ok('git -C <abs> grep is allowed (exit 0)', a2.code === 0 && a2.out.trim() === '');
+
+const a3 = runHook('cd /abs && npm test');
+ok('cd <abs> && npm test (no read/search verb) is allowed (exit 0)', a3.code === 0 && a3.out.trim() === '');
+
+const a4 = runHook('cd /abs && ls -la');
+ok('cd <abs> && ls (not a Read()-denied verb) is allowed (exit 0)', a4.code === 0 && a4.out.trim() === '');
+
+const a5 = runHook('cd /abs/app');
+ok('a bare standalone cd <abs> alone is allowed (exit 0) - known limitation, never block a lone cd', a5.code === 0 && a5.out.trim() === '');
+
+const a6 = runHook('grep "cd foo" /abs/file');
+ok('grep whose pattern happens to contain "cd" but path is absolute is allowed (exit 0)', a6.code === 0 && a6.out.trim() === '');
+
+const a7 = runHook('grep -n "x" file --with-something');
+ok('command with no cd at all is allowed regardless of relative path (exit 0)', a7.code === 0 && a7.out.trim() === '');
+
+const a8 = runHook('cd /abs/app && grep -n "x" /abs/app/foo.txt');
+ok('cd <abs> && grep with an absolute-path argument is allowed (exit 0)', a8.code === 0 && a8.out.trim() === '');
+
+const a9 = runHook('cd /abs/app && grep -n "x" -r --include=*.js');
+ok('cd <abs> && grep with only flags/patterns (no file arg) is allowed (exit 0)', a9.code === 0 && a9.out.trim() === '');
+
+// --- #134 follow-up: Finding 1 - heredoc bodies are DATA, not statements ---
+const h1 = runHook(`cat > setup.sh <<'EOF'\ncd /some/dir\ngrep -n pattern file.txt\nEOF\n`);
+ok('heredoc body (cd + grep as literal data) is allowed, not parsed as statements (exit 0)', h1.code === 0 && h1.out.trim() === '');
+
+const h2 = runHook(`bash -c 'cat' <<EOF\ncd app\ngrep -n x foo.txt\nEOF\n`);
+ok('heredoc fed to a command is allowed, its body is data not executed statements (exit 0)', h2.code === 0 && h2.out.trim() === '');
+
+const h3 = runHook(`cat > setup.sh <<'EOF'\nsome literal data\nEOF\ncd app && grep -n x foo.txt`);
+ok('a REAL cd + grep violation outside a heredoc on the same command still blocks (exit 2)', h3.code === 2 && /search-hygiene/.test(h3.out));
+
+// --- #134 follow-up: Finding 2 - grouping containers must not hide the violation ---
+const g1 = runHook('(cd app && grep -n x foo.txt)');
+ok('subshell-wrapped cd + grep is blocked (exit 2)', g1.code === 2 && /search-hygiene/.test(g1.out));
+
+const g2 = runHook('{ cd app; grep -n x foo.txt; }');
+ok('brace-group-wrapped cd + grep is blocked (exit 2)', g2.code === 2 && /search-hygiene/.test(g2.out));
+
+const g3 = runHook('for d in */; do cd "$d" && grep -n x foo.txt; cd ..; done');
+ok('loop-body cd + grep is blocked (exit 2)', g3.code === 2 && /search-hygiene/.test(g3.out));
+
+const g4 = runHook('(cd /abs && npm test)');
+ok('subshell-wrapped cd <abs> && npm test (no read verb) is still allowed (exit 0)', g4.code === 0 && g4.out.trim() === '');
+
+// --- #134 follow-up: Finding 3 - `--` end-of-options marker must not swallow the file ---
+const d1 = runHook('cd app && grep -- -x foo.txt');
+ok('cd + grep -- -x <relative file> is blocked (exit 2), `--` must not eat the file arg', d1.code === 2 && /search-hygiene/.test(d1.out) && /foo\.txt/.test(d1.out));
+
+// --- #134 follow-up: Finding 4 - rg-specific value flags must not misattribute the file ---
+const f1 = runHook('cd app && rg -g "*.js" TODO src/foo.js');
+ok('cd + rg -g <glob> <pattern> <relative file> reports the real file, not the pattern (exit 2)', f1.code === 2 && /search-hygiene/.test(f1.out) && /src\/foo\.js/.test(f1.out) && !/`TODO`/.test(f1.out));
+
+console.log(`✓ search-guard: ${passed} assertions passed`);

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

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+// trailhead-secret-read-guard.js: PreToolUse(Read|Bash) hook.
+// Restores the `.env`/`.secrets` read protection that three `Read()` deny
+// permission rules used to provide, before they were removed (#135). A
+// `Read()` deny rule is a PERMISSION rule: under bypass permissions it still
+// falls back to a manual approval prompt on Claude Code 2.1.259's new
+// `cd-compound-read` check (the same headless-breaking prompt that
+// trailhead-search-guard.js exists to route around, see #132-#134). This hook
+// gets the same outcome — a secret file can never be read — as a HOOK `deny`
+// decision instead, which does not arm that permission-layer prompt at all.
+//
+// Denies:
+//   (a) a Read tool call whose `file_path` basename is a secret pattern; and
+//   (b) a Bash command that touches a secret path as a plain positional file
+//       operand, an option value (`--file=.env`, `-f .env`, glued `-f.env`),
+//       or a `<` (or glued `<file`) redirect target.
+// A "secret pattern" is a basename that is exactly `.env`, exactly
+// `.secrets`, or matches `.env.<anything>` (e.g. `.env.local`,
+// `.env.production`), matched CASE-INSENSITIVELY (`.ENV`/`.SECRETS` are the
+// same file on macOS/Windows). Matched on basename, so `app/.env` and
+// `./.env.local` are caught the same as a bare `.env`.
+//
+// #135 follow-up (adversarial review found real false negatives/positives in
+// the original naive `.split(/\s+/)` Bash tokenizer):
+//   - Finding 1 (glued shell metacharacters, e.g. `cat .env|grep KEY`,
+//     `cat .env;echo done`, `cat .env&&echo done`) is fixed by scanning
+//     QUOTE-AWARE, STATEMENT-BASED top-level statements (splitStatements),
+//     which split on operator characters regardless of surrounding
+//     whitespace. `bash -c "cat .env"` / `eval "cat .env"` are fixed by
+//     recursing into the quoted sub-command's text as a nested command.
+//   - Finding 2 (glued short-option value, `cat -f.env`) is fixed by also
+//     testing a value-flag's glued suffix (`token.slice(2)`).
+//   - Finding 3 (bare `.env` inside quoted prose, e.g. `git commit -m
+//     "document .env usage"`) is fixed by a quote-aware tokenizer that keeps
+//     a multi-word quoted phrase as ONE opaque token, never splitting it into
+//     separate words.
+//   - Finding 4 (a quoted grep PATTERN that happens to look like a secret
+//     path, e.g. `grep ".env" config.txt`) is fixed by routing search verbs
+//     (grep/rg/ag/sed/awk) through the shared pattern-positional-skipping
+//     walk, so the pattern is never mistaken for the file operand.
+//   - Finding 5 (case sensitivity) is fixed by lowercasing the basename
+//     before the pattern test.
+// The quote-aware tokenizer/statement-splitter and the search-verb handling
+// are shared with trailhead-search-guard.js via lib/shell-scan.js, so the two
+// guards can never drift into two divergent tokenizers again.
+//
+// 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
+// resolve to a secret path", so `cd app && grep x pubspec.yaml` is allowed
+// (no secret token present) regardless of the `cd`.
+//
+// Denies with exit 2 + {"decision":"block","code":...,"reason":...} — same
+// wire shape the sibling guards use for a block, which the PreToolUse hook
+// contract treats as a deny. Allows everything else. Crash-safe: any error ->
+// exit 0 (never wedge the user's workflow). Self-contained (its own
+// dependency is the sibling lib/ module, no external packages). Pure
+// function exported for tests; runs as a hook when executed directly.
+
+const {
+  basename,
+  stripQuotes,
+  splitStatements,
+  tokenize,
+  SEARCH_VERB_CONFIG,
+  scanArgsSkippingPattern,
+} = require('./lib/shell-scan.js');
+
+// --- path helpers ------------------------------------------------------------
+
+// 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.
+function isSecretBasename(name) {
+  if (!name) return false;
+  const lower = String(name).toLowerCase();
+  if (lower === '.env' || lower === '.secrets') return true;
+  return /^\.env\..+$/.test(lower);
+}
+
+function isSecretPathArg(t) {
+  const bare = stripQuotes(t);
+  if (!bare) return false;
+  return isSecretBasename(basename(bare));
+}
+
+// --- Bash leg: quote-aware, statement-based scan -----------------------------
+
+// Flags that take a separate-token value which could itself be the secret
+// path (`-f .env`, `--file .env`), or (finding #2) a GLUED value on a short
+// flag (`-f.env`). Kept small and generic: this hook doesn't need to model
+// every tool's flag surface, just the common file-value shapes.
+const VALUE_FLAGS = new Set(['-f', '--file']);
+
+// 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
+// operand, so it must be skipped before scanning for a secret FILE argument
+// (finding #4: `grep ".env" config.txt` reads config.txt, not `.env`).
+const SEARCH_VERBS = new Set(Object.keys(SEARCH_VERB_CONFIG));
+
+// `bash -c "<cmd>"` / `sh -c "<cmd>"` / `zsh -c "<cmd>"` / `eval "<cmd>"`: the
+// secret read hides inside that quoted string, invisible to a plain
+// positional/flag scan (finding #1), so these are recursed into as a nested
+// command.
+const SHELL_DASH_C_VERBS = new Set(['bash', 'sh', 'zsh', 'ksh']);
+
+// A token can still end with a glued shell metacharacter that splitStatements
+// doesn't split on (grouping punctuation left over from a subshell/brace
+// group, or a stray backtick closing a command substitution). Strip a run of
+// these from the token's tail before basename-testing it, so e.g. the last
+// token of `(cat .env)` (`.env)`) still resolves to `.env`.
+const TRAILING_PUNCT_RE = /[|;&`)}]+$/;
+function stripTrailingPunct(t) {
+  return String(t).replace(TRAILING_PUNCT_RE, '');
+}
+
+// Scan one already-tokenized statement's argument tokens (verb NOT stripped)
+// for a secret path used as a plain positional, an option value
+// (`--file=.env`, `-f .env`, glued `-f.env`), or a `<` (or glued `<file`)
+// redirect target. Returns the offending token or null.
+function scanTokensForSecretPath(tokens) {
+  for (let i = 0; i < tokens.length; i++) {
+    const t = stripTrailingPunct(tokens[i]);
+    if (!t) continue;
+
+    // `<` redirect: glued (`<.secrets`) or separate-token (`< .secrets`).
+    // Never confuse with a heredoc `<<TAG` (already stripped out by
+    // splitStatements upstream, but be defensive).
+    if (t.startsWith('<') && !t.startsWith('<<')) {
+      const glued = t.slice(1);
+      if (glued) {
+        if (isSecretPathArg(glued)) return glued;
+        continue;
+      }
+      const next = i + 1 < tokens.length ? stripTrailingPunct(tokens[i + 1]) : null;
+      if (next && isSecretPathArg(next)) return next;
+      continue;
+    }
+
+    if (t.startsWith('-') && t !== '-') {
+      // `--flag=value` form.
+      const eq = t.indexOf('=');
+      if (eq > 0) {
+        const val = t.slice(eq + 1);
+        if (isSecretPathArg(val)) return val;
+        continue;
+      }
+      // `-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;
+        continue;
+      }
+      // Glued short-option value (`-f.env`, finding #2): a single-dash flag
+      // whose flag letter is a known value flag, with the value glued
+      // directly onto it.
+      if (!t.startsWith('--') && t.length > 2) {
+        const shortFlag = t.slice(0, 2);
+        if (VALUE_FLAGS.has(shortFlag)) {
+          const glued = t.slice(2);
+          if (isSecretPathArg(glued)) return glued;
+        }
+      }
+      continue; // some other flag: not itself a file operand
+    }
+
+    // Plain positional (file operand or search pattern token).
+    if (isSecretPathArg(t)) return t;
+  }
+  return null;
+}
+
+// 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.
+// Best-effort: only the common single-quoted-argument idiom, not every way a
+// shell can be told to execute a string.
+function extractNestedCommand(stmtTokens) {
+  if (!stmtTokens.length) return null;
+  const bin = basename(stmtTokens[0]);
+  if (bin === 'eval') {
+    const rest = stmtTokens.slice(1);
+    if (!rest.length) return null;
+    return stripQuotes(rest.join(' '));
+  }
+  if (SHELL_DASH_C_VERBS.has(bin)) {
+    const cIdx = stmtTokens.indexOf('-c');
+    if (cIdx === -1 || cIdx + 1 >= stmtTokens.length) return null;
+    return stripQuotes(stmtTokens.slice(cIdx + 1).join(' '));
+  }
+  return null;
+}
+
+// Scan a single top-level statement for a secret path. Recurses into a
+// bash -c/eval quoted sub-command first (finding #1), routes grep/rg/ag/sed/
+// awk through the shared pattern-skipping walk (finding #4), and falls back
+// to the plain per-token walk for everything else (cat, head, redirects,
+// etc.).
+function scanStatementForSecretPath(stmt) {
+  const tokens = tokenize(stmt);
+  if (!tokens.length) return null;
+
+  const nested = extractNestedCommand(tokens);
+  if (nested) {
+    const hit = scanBashForSecretPath(nested);
+    if (hit) return hit;
+    // fall through: also scan the wrapper statement's own tokens (e.g. a
+    // stray `-f .env` on the wrapper itself) for defence in depth.
+  }
+
+  const bin = basename(tokens[0]);
+  if (SEARCH_VERBS.has(bin)) {
+    return scanArgsSkippingPattern(tokens.slice(1), SEARCH_VERB_CONFIG[bin], isSecretPathArg);
+  }
+  return scanTokensForSecretPath(tokens);
+}
+
+// Walk the command's top-level statements (quote-aware; `|`, `;`, `&&`,
+// `||`, and newlines all split, even with no surrounding whitespace, e.g.
+// `cat .env|grep KEY`) looking for a secret path used as a plain positional,
+// an option value, or a `<` redirect target. Returns the offending token
+// (quotes/punctuation not necessarily stripped) or null. Best-effort: not a
+// full shell parser.
+function scanBashForSecretPath(cmd) {
+  const statements = splitStatements(cmd);
+  for (const stmt of statements) {
+    const hit = scanStatementForSecretPath(stmt);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+// --- top-level detection -----------------------------------------------------
+
+// Detect a secret-file read across a Read or Bash tool call. Returns
+// { path } on a hit, or null. Pure, exported for tests.
+function detectSecretRead(toolName, toolInput) {
+  const input = toolInput || {};
+  if (toolName === 'Read') {
+    const p = input.file_path;
+    if (p && isSecretPathArg(String(p))) return { path: String(p) };
+    return null;
+  }
+  if (toolName === 'Bash') {
+    const cmd = input.command || '';
+    const hit = scanBashForSecretPath(cmd);
+    return hit ? { path: hit } : null;
+  }
+  return null;
+}
+
+function block(hit) {
+  const reason =
+    `trailhead secret-read guard: blocked a read of secret file \`${hit.path}\` ` +
+    '(.env / .env.* / .secrets). This replaces the Read() deny permission rules ' +
+    "removed in #135 with a hook-level deny, so secrets stay unreadable without " +
+    "arming Claude Code 2.1.259's cd-compound-read approval prompt. If this file " +
+    'genuinely needs inspecting, do so outside the agent session.';
+  process.stdout.write(JSON.stringify({ decision: 'block', code: 'SECRET_READ_BLOCKED', reason }));
+  process.exit(2);
+}
+
+function run(data) {
+  let parsed;
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    process.exit(0); // unparseable input: nothing to gate
+  }
+  try {
+    const hit = detectSecretRead(parsed.tool_name, parsed.tool_input);
+    if (hit) block(hit);
+  } 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 = { detectSecretRead };

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

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// Tests for trailhead-secret-read-guard.js. Run: node trailhead-secret-read-guard.test.js
+// No framework: plain asserts + child_process for the end-to-end hook behaviour.
+const assert = require('assert');
+const { execFileSync } = require('child_process');
+const path = require('path');
+const { detectSecretRead } = require('./trailhead-secret-read-guard.js');
+
+const HOOK = path.join(__dirname, 'trailhead-secret-read-guard.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// Run the hook end-to-end: pipe {tool_name, tool_input} JSON on stdin, capture {code, out}.
+function runHook(toolName, toolInput) {
+  const input = JSON.stringify({ tool_name: toolName, tool_input: toolInput });
+  try {
+    const out = execFileSync('node', [HOOK], { input });
+    return { code: 0, out: out.toString() };
+  } catch (e) {
+    return { code: e.status, out: (e.stdout || '').toString(), err: (e.stderr || '').toString() };
+  }
+}
+
+// --- pure seam: detectSecretRead ---
+
+// --- DENY cases ---
+ok('Read .env is denied', !!detectSecretRead('Read', { file_path: '.env' }));
+ok('Read config/.env.local is denied', !!detectSecretRead('Read', { file_path: 'config/.env.local' }));
+ok('Read .secrets is denied', !!detectSecretRead('Read', { file_path: '.secrets' }));
+ok('Bash cat .env is denied', !!detectSecretRead('Bash', { command: 'cat .env' }));
+ok('Bash cat < .secrets is denied', !!detectSecretRead('Bash', { command: 'cat < .secrets' }));
+ok('Bash grep -n KEY .env.production is denied', !!detectSecretRead('Bash', { command: 'grep -n KEY .env.production' }));
+ok('Bash cat app/.env.local is denied', !!detectSecretRead('Bash', { command: 'cat app/.env.local' }));
+ok('Bash cat --file=.env is denied', !!detectSecretRead('Bash', { command: 'cat --file=.env' }));
+
+// --- ALLOW cases (no false positives) ---
+ok('Read src/app.ts is allowed', !detectSecretRead('Read', { file_path: 'src/app.ts' }));
+ok('Bash grep -n x pubspec.yaml is allowed', !detectSecretRead('Bash', { command: 'grep -n x pubspec.yaml' }));
+ok('Bash cat README.md is allowed', !detectSecretRead('Bash', { command: 'cat README.md' }));
+ok('Bash cd app && grep x pubspec.yaml is allowed (not a secret; search-guard governs the cd shape)',
+  !detectSecretRead('Bash', { command: 'cd app && grep x pubspec.yaml' }));
+ok('Read env.sample (near-miss) is allowed', !detectSecretRead('Read', { file_path: 'env.sample' }));
+ok('Read .environment (near-miss) is allowed', !detectSecretRead('Read', { file_path: '.environment' }));
+
+// --- #135 follow-up: Finding 1 - glued shell metacharacters must not bypass detection ---
+ok('Bash cat .env|grep KEY is denied (glued pipe)', !!detectSecretRead('Bash', { command: 'cat .env|grep KEY' }));
+ok('Bash cat .env;echo done is denied (glued semicolon)', !!detectSecretRead('Bash', { command: 'cat .env;echo done' }));
+ok('Bash cat .env&&echo done is denied (glued &&)', !!detectSecretRead('Bash', { command: 'cat .env&&echo done' }));
+ok('Bash bash -c "cat .env" is denied (quoted sub-command)', !!detectSecretRead('Bash', { command: 'bash -c "cat .env"' }));
+ok('Bash eval "cat .env" is denied (quoted sub-command)', !!detectSecretRead('Bash', { command: 'eval "cat .env"' }));
+
+// --- #135 follow-up: Finding 2 - glued short-option value must not bypass detection ---
+ok('Bash cat -f.env is denied (glued short-flag value)', !!detectSecretRead('Bash', { command: 'cat -f.env' }));
+
+// --- #135 follow-up: Finding 3 - bare .env inside quoted prose must not false-positive ---
+ok('Bash git commit -m "document .env usage" is allowed (quoted prose, not a file operand)',
+  !detectSecretRead('Bash', { command: 'git commit -m "document .env usage"' }));
+ok('Bash echo "See .env for config" >> README.md is allowed (quoted prose)',
+  !detectSecretRead('Bash', { command: 'echo "See .env for config" >> README.md' }));
+ok('Bash cat ".env" is still denied (a quoted LONE path is still a secret path)',
+  !!detectSecretRead('Bash', { command: 'cat ".env"' }));
+
+// --- #135 follow-up: Finding 4 - quoted grep pattern must not false-positive ---
+ok('Bash grep ".env" config.txt is allowed (the read target is config.txt, not the pattern)',
+  !detectSecretRead('Bash', { command: 'grep ".env" config.txt' }));
+ok("Bash grep '.env' config.txt is allowed (single-quoted pattern)",
+  !detectSecretRead('Bash', { command: "grep '.env' config.txt" }));
+ok('Bash grep -n KEY .env.production is still denied (secret is the FILE operand, not the pattern)',
+  !!detectSecretRead('Bash', { command: 'grep -n KEY .env.production' }));
+
+// --- #135 follow-up: Finding 5 - case-insensitivity (same file on macOS/Windows) ---
+ok('Read .ENV is denied (case-insensitive)', !!detectSecretRead('Read', { file_path: '.ENV' }));
+ok('Bash cat .SECRETS is denied (case-insensitive)', !!detectSecretRead('Bash', { command: 'cat .SECRETS' }));
+ok('Read ENV.SAMPLE (near-miss) is still allowed regardless of case', !detectSecretRead('Read', { file_path: 'ENV.SAMPLE' }));
+ok('Read .ENVIRONMENT (near-miss) is still allowed regardless of case', !detectSecretRead('Read', { file_path: '.ENVIRONMENT' }));
+
+// --- end-to-end hook wire format ---
+const d1 = runHook('Read', { file_path: '.env' });
+ok('hook denies Read(.env) end-to-end (exit 2, block decision)', d1.code === 2 && /"decision":"block"/.test(d1.out));
+
+const d2 = runHook('Bash', { command: 'cat .env' });
+ok('hook denies Bash(cat .env) end-to-end (exit 2, block decision)', d2.code === 2 && /"decision":"block"/.test(d2.out));
+
+const a1 = runHook('Read', { file_path: 'src/app.ts' });
+ok('hook allows Read(src/app.ts) end-to-end (exit 0, no output)', a1.code === 0 && a1.out.trim() === '');
+
+const a2 = runHook('Bash', { command: 'cd app && grep x pubspec.yaml' });
+ok('hook allows Bash(cd app && grep x pubspec.yaml) end-to-end (exit 0, no output)', a2.code === 0 && a2.out.trim() === '');
+
+// --- crash safety ---
+const crash1 = runHook('Read', undefined);
+ok('missing tool_input never crashes (exit 0)', crash1.code === 0);
+
+console.log(`✓ secret-read-guard: ${passed} assertions passed`);

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

@@ -74,6 +74,8 @@ On **trivial/small** the engine surfaces **one consolidated skip offer** and act
 
 **Never in the offer** (always kept, whatever the size or the answer): atomic `Refs:` commits, running the tests / the plan's verification criterion, the post-commit self-check, `bug`'s Diagnose (a confirmed root cause is mandatory before Fix), and Resolve. `effort` scales *redundant heavy* work to the change; it never drops a correctness check.
 
+**`auto` has no config surface.** The autonomous run (`/trailhead:auto`, `../trailhead-work/references/auto.md`) takes no key here, by decision: it changes neither `effort` nor `models.*` (orthogonal to both). Its safety rail is hardcoded always-on, never a toggle, and its stop/go boundary is the same `choices.md` one-line test every other engine step uses (delegate options run without the confirm gate; a human-necessary choice is always set aside), so there is nothing to configure separately.
+
 Example `config.json` (same shape for the project `.trailhead/config.json` and the global `~/.claude/trailhead/config.json`):
 ```json
 { "models": { "plan": "claude-opus-4-8", "execute": "claude-sonnet-5" }, "tdd": "seams", "acceptance": { "browser": "auto" } }

package/plugins/trailhead/skills/_shared/load-first.md

@@ -0,0 +1,16 @@
+# Load first, in order
+
+The **shared-core load contract**, single-sourced here and referenced by every cluster `SKILL.md`: the dispatcher `trailhead/` and the five clusters `trailhead-chart` / `trailhead-work` / `trailhead-view` / `trailhead-capture` / `trailhead-manage`. Each cluster's own `## Load first, in order` points here in a line, then states its cluster-specific isolation posture; this file holds the part that is identical for all of them.
+
+The paths below are written **relative to the cluster `SKILL.md` that pointed you here** (exactly as that `SKILL.md`'s own shared-core references are), so `../_shared/` resolves to this directory from any cluster.
+
+Before doing anything, read the shared core, in order:
+
+1. `../_shared/principles.md`: refer by name, result-oriented output, no em-dashes, git per conventions, one ticket per session.
+2. `../_shared/ticket-language.md`: write all Issue prose and commit bodies in `config.ticket.language` (default `en`), independent of the chat language.
+3. `../_shared/substrate.md`: the GitHub-Issues model: labels, the frontier query, the map / ticket / dashboard / whiteboard anatomy, and the base-command cookbook pointer.
+4. `../_shared/session-handoff.md`: how every resolution closes (`/clear` first, then the next command).
+5. `../_shared/configuration.md`: the three config layers and the load contract.
+6. `../_shared/techniques.md`: the technique index and the subagent-type rule.
+
+Load the **effective config** (per `../_shared/configuration.md`) at session start, from the map's project root (`.trailhead/config.json` plus the global file), before any isolation workspace is set up.

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

@@ -153,7 +153,7 @@ gh issue list --label "trailhead:map-<n>" --state open --json number --jq 'lengt
 gh issue view <map> --json body --jq .body
 ```
 
-**When to refresh the body.** On structural events: a map is charted or exhausted (a map appears or disappears), a whiteboard ticket is born or resolved. And on demand via `/trailhead:dashboard`. NOT on every map-ticket resolve: that churns a pinned issue's notifications, and the native progress bar already tracks map-ticket progress on its own. The whiteboard has no native progress bar, so its ticket birth/close does refresh the dashboard.
+**When to refresh the body.** On structural events: a map is charted or exhausted (a map appears or disappears), a whiteboard ticket is born or resolved. And on demand via `/trailhead:dashboard`. NOT on every map-ticket resolve: that churns a pinned issue's notifications, and the native progress bar already tracks map-ticket progress on its own. The whiteboard has no native progress bar, so its ticket birth or close refreshes the dashboard, except a `quick`-born ticket (born and resolved in one session) refreshes at the handoff (Resolve, or pause), not at creation.
 
 ## 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`).

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

@@ -7,7 +7,7 @@ The tracker is GitHub via the `gh` CLI (already authenticated). **Never post a s
 | Map | an issue with label `trailhead:map`. **Not pinned** (the 3 pinned slots are the repo-scoped [dashboard](../trailhead-view/SKILL.md#render-the-dashboard-dashboard) + codebase + conventions): open maps are found via the `trailhead:map` label and listed in the pinned dashboard, so a repo's maps stay one click away without contending for a slot. **When a map is exhausted** (destination reached: no open tickets and no fog left), **ask the user whether to close the map issue**: on a yes, `gh issue close` it (a closed issue is still the durable record) and refresh the dashboard so it drops off; on a no, leave it open. Never close a map unprompted; there is no pin to free either way. Each map's **tickets** share a **`trailhead:map-<n>` label** (n = the map's issue number) that scopes its frontier; the map issue itself is found by its number and does not carry it. |
 | Codebase | a **single per-repo** issue with label `trailhead:codebase`: the distilled codebase map (architecture, stack, conventions, decisions embodied, risks, test/build). It's repo-scoped: **shared by every map of this repo, owned by none**, so it survives when a map is finished. Each map's Notes *links* it (never re-inlines it). Not a `trailhead:ticket`, so it's off the frontier. Written at adopt; a **greenfield map** (`/trailhead:new`) has no code to map at chart, so it's created **later, once the repo has substantial code** (e.g. after the first build tickets land), via the Codebase map technique. **Kept fresh at Resolve**: when a resolved `build`/`bug` ticket **materially changes** the map (a new module or layer, a new dependency/integration, a new seam, a changed build/test command, a new convention), **patch the affected facet of this issue in place** as part of Resolve, one or two lines, not a re-run of the fan-out. Cosmetic or in-facet changes leave it alone; a full re-map is only for major drift. |
 | Conventions | a **single per-repo** issue with label `trailhead:conventions`: the project's **way of working**, readable by everyone. Repo-scoped and linked from every map's Notes, like Codebase. It opens with a small machine-read header the engine obeys, then human prose. Header keys (defaults **bold**): `git:` **`main`** \| `pr` (commit straight to `main`, or feature branch + PR) · `release:` **`command`** \| `auto` (never release without an explicit command, or release automatically per the project's flow) · `isolation:` **`none`** \| `worktree` \| `clone` (work in the current checkout; or give each executing ticket its own `git worktree` + `trailhead/t<n>` branch; or a dedicated per-ticket **clone** at `../<repo>-t<n>` for **path-bound apps a worktree can't build**, e.g. React Native/Expo with a local `node_modules`; see [Working as a team](teamwork.md#working-as-a-team)). **`worktree`/`clone` imply a branch per ticket even under `git: main`** (git won't check the trunk out twice); the branch integrates to the trunk per `git:` at Resolve. Under **`none`** two in-progress tickets with overlapping `Scope:` **serialise** (the second holds at claim). Below the header: the standing "how we work here" notes. **Filled at chart/adopt by a brief conventions brainstorming** (see the Invocation modes), not a `trailhead:ticket`, off the frontier. |
-| Dashboard | a **single per-repo** issue with label `trailhead:dashboard`: the pinned index of the whole trailhead surface. Repo-scoped and permanent, like Codebase and Conventions, and it occupies the **fixed 3rd pinned slot** alongside them (`gh api graphql` `pinIssue` mutation on its node id). It holds: a link to **every open `trailhead:map`** (GitHub renders each map's sub-issue **progress bar natively**, so the dashboard only links, it does not recompute per-ticket progress), the **whiteboard** as a section (or a link to the `/trailhead:whiteboard` view), and dynamic **counts** (untriaged inbox, whiteboard frontier size). **Created and pinned at the first chart/adopt**, then **rewritten on structural events** (a map is charted or exhausted, i.e. a map appears or disappears; a whiteboard ticket is born or resolved) **and on demand** via `/trailhead:dashboard`. **Not rewritten on every *map* ticket resolve** (that would churn a pinned issue and its notifications; each map's native progress bar already tracks its per-ticket progress, but the whiteboard has no progress bar, so its ticket birth/close does refresh the dashboard). **An exhausted-but-open map** (destination reached, but its issue never closed) is flagged `exhausted · closeable` here via a cheap per-map `0 open scoped issues?` pre-filter confirmed against remaining fog, and the render offers to close it (recurring across the dashboard render and the read-only self-heal entry points, never auto-closing), so a missed exhaustion moment gets a second chance. See [The dashboard](../trailhead-view/SKILL.md#render-the-dashboard-dashboard). |
+| Dashboard | a **single per-repo** issue with label `trailhead:dashboard`: the pinned index of the whole trailhead surface. Repo-scoped and permanent, like Codebase and Conventions, and it occupies the **fixed 3rd pinned slot** alongside them (`gh api graphql` `pinIssue` mutation on its node id). It holds: a link to **every open `trailhead:map`** (GitHub renders each map's sub-issue **progress bar natively**, so the dashboard only links, it does not recompute per-ticket progress), the **whiteboard** as a section (or a link to the `/trailhead:whiteboard` view), and dynamic **counts** (untriaged inbox, whiteboard frontier size). **Created and pinned at the first chart/adopt**, then **rewritten on structural events** (a map is charted or exhausted, i.e. a map appears or disappears; a whiteboard ticket is born or resolved) **and on demand** via `/trailhead:dashboard`. **Not rewritten on every *map* ticket resolve** (that would churn a pinned issue and its notifications; each map's native progress bar already tracks its per-ticket progress, but the whiteboard has no progress bar, so a whiteboard ticket's birth or close refreshes the dashboard, with one timing exception: a `quick`-born ticket, born and resolved in one session, refreshes at its handoff (Resolve, or pause), not at creation). **An exhausted-but-open map** (destination reached, but its issue never closed) is flagged `exhausted · closeable` here via a cheap per-map `0 open scoped issues?` pre-filter confirmed against remaining fog, and the render offers to close it (recurring across the dashboard render and the read-only self-heal entry points, never auto-closing), so a missed exhaustion moment gets a second chance. See [The dashboard](../trailhead-view/SKILL.md#render-the-dashboard-dashboard). |
 | Ticket | a child issue with label `trailhead:ticket` + exactly one **type** label: `trailhead:decision` / `trailhead:research` / `trailhead:prototype` / `trailhead:build` / `trailhead:bug` / `trailhead:task`, plus its map's `trailhead:map-<n>` label and native sub-issue edge (see Child→map link). **A `trailhead:whiteboard` ticket carries none of the map wiring** (no `trailhead:map-<n>`, no sub-issue edge, no `Parent:`); see [The whiteboard](../trailhead-view/SKILL.md#render-the-whiteboard-whiteboard). |
 | Child→map link | three views of one fact, wired in the same pass (like a blocker): a `Parent: <map name>(link)` line in the ticket body (human-readable); a **native sub-issue** edge to the map (`gh api --method POST repos/{owner}/{repo}/issues/<map>/sub_issues -F sub_issue_id=<ticket .id>`, the structure GitHub renders); and the map's **`trailhead:map-<n>` label** on the ticket (the queryable key that scopes its map's frontier). See [Multiple maps on one repo](multi-map.md#multiple-maps-on-one-repo-parking--concurrency). **A whiteboard ticket has none of the three** (it belongs to no map). |
 | Path scope (monorepo) | an optional `Scope: <path>[, <path>…]` line in the ticket body naming the package/dir(s), or **submodule path(s)**, the ticket works in. It sharpens the [undeclared-coupling check](teamwork.md#working-as-a-team) (disjoint scopes parallelize safely), scopes build/test to the affected package, and scopes an `isolation: worktree` worktree's commits. **List every one it touches** (a ticket spanning two submodules names both). **Omit it in a single-package repo** (the whole tree is the scope); add it only where a repo has independent packages/subtrees or submodules. |

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

@@ -44,7 +44,7 @@ Prefer `worktree` whenever more than one session may run on a single clone. On a
 
 ## Pausing & resuming
 Switching away from a ticket mid-work (to clear a blocker, chase an urgent bug, or just stop) must not lose the thread.
-- **Pause** (`/trailhead:pause [note]`): first commit any work-in-progress (atomic) so nothing is stranded, then post a **`PAUSED`** checkpoint comment: what's done, the exact next step, and any local state (branch, **worktree path under `isolation: worktree`**, how to run it). Keep the claim if you'll return soon; **release it** (unassign) if it's open-ended, so someone else can resume; the checkpoint is what makes that safe. If you release, also remove the `.trailhead/session-ticket` marker (SKILL.md Mode 2); if you keep the claim, leave it.
+- **Pause** (`/trailhead:pause [note]`): first commit any work-in-progress (atomic) so nothing is stranded, then post a **`PAUSED`** checkpoint comment: what's done, the exact next step, and any local state (branch, **worktree path under `isolation: worktree`**, how to run it). Keep the claim if you'll return soon; **release it** (unassign) if it's open-ended, so someone else can resume; the checkpoint is what makes that safe. If you release, also remove the `.trailhead/session-ticket` marker (SKILL.md Mode 2); if you keep the claim, leave it. **If the paused ticket is a `trailhead:whiteboard` quick that has deferred its dashboard refresh to a handoff it is not reaching this session** (born by `quick`, resolution refresh not yet done), refresh the dashboard now (full regeneration from the live tracker) so the unfinished quick shows on the pinned index: the read-only renders never rewrite the dashboard body, so pause is what surfaces it.
 - **Resume** (`/trailhead:resume [ticket]`): read the ticket's latest `PAUSED` checkpoint (and the `DISCUSS`/`PLAN` comments above it), then pick up at the recorded next step. Anyone may resume a *released* ticket; a still-claimed one, only its owner. **Re-write the `.trailhead/session-ticket` marker** at the working root (SKILL.md Mode 2 step 2) so the resumed session shows in tooling like the statusline (a released pause removed it); under `isolation: worktree`/`clone`, also re-enter the ticket's recorded workspace.
 - One ticket per session still holds: pausing A to work B ideally means B in a fresh session. If you must switch within one session, checkpoint A first; never leave it half-done and unrecorded.
 

package/plugins/trailhead/skills/_shared/techniques/acceptance-testing.md

@@ -8,7 +8,7 @@ Automated tests prove the code does what the *code* intended; acceptance testing
   - **On a failing step: stop, take note, open the closing ticket then and there.** A failed step is an acceptance finding, not a footnote: record expected-vs-seen, and immediately open the follow-up that will carry it to resolution: a `bug` ticket (with `Regression of:`/`Surfaced from:` as fits), or a fix on this ticket before it resolves if it's small and in-scope. Then ask the human whether to keep going through the remaining steps or stop here. Never silently log a fail and carry on to Resolve.
   - **When only some steps are runnable now** (e.g. a few need a backend deployed first), walk the runnable ones conversationally **now**, and mark the rest **explicitly pending** with what unblocks them, tracked as below. Don't defer the whole UAT just because part of it is blocked.
   - **When the human can only run it later** (on-device, hardware you don't have right now), record the full numbered checklist in the `VERIFY` comment as the durable artifact and mark UAT **explicitly pending**, but the walkthrough stays conversational **when they come to run it**: never shrink it to a vague one-liner ("just check it on the device"), and never let "automated passed" quietly stand in for it. Deferring *where/when* the human runs it is fine; replacing the live step-by-step with a self-serve checklist is not.
-  - **Pending UAT must stay tracked: a closed ticket is not tracking.** Don't resolve/close a user-facing ticket on unconfirmed acceptance and leave the checklist as a comment on the closed issue, where nobody will look. Either **keep the ticket open** until the human confirms the UAT passes (the default: closing on green you didn't see is a premature close), **or**, if the project deliberately batches on-device UAT, spin a follow-up **`task`** that carries the checklist and sits on the frontier until it's run. The pending check must be visible on the tracker, not buried.
+  - **Pending UAT must stay tracked: a closed ticket is not tracking.** Don't resolve/close a user-facing ticket on unconfirmed acceptance and leave the checklist as a comment on the closed issue, where nobody will look. The default is to **keep the ticket open** until the human confirms the UAT passes (closing on green you didn't see is a premature close). **If the human instead accepts closing now and running the UAT later**, you **must open a follow-up ticket before that close** that carries the pending UAT and links back to the parent with a `UAT of: <parent name>(link)` pointer in the body. Route it the way `../choices.md` routes a deferred choice: a **`trailhead:seed`** (kept blocked) when the run is gated on a future external trigger not yet true (hardware you don't have, a device out of reach), or a follow-up **`task`** on the frontier when it's just scheduled or batched work you could pick up any time. Either way the follow-up **carries the full numbered checklist and, when it comes to resolution, runs the guided conversational walkthrough above**, never a self-serve check-off. **Never close a user-facing ticket on deferred UAT with nothing opened**: the parent may close as agreed, but the owed UAT stays visible on the tracker as its own ticket, linked to the parent, until it is actually performed. The pending check must be visible on the tracker, not buried.
 
 Acceptance failures are findings like any other: a `bug` follow-up or a fix on this ticket before it resolves.
 

package/plugins/trailhead/skills/_shared/techniques/codebase-map.md

@@ -1,5 +1,8 @@
 # Codebase map (fan-out)
 One-time at project adoption. Fan out 5 read-only reader subagents in parallel (single message), each owning ONE non-overlapping facet; no facet reads another's territory. Dispatch each reader as the **`trailhead-codebase-map`** agent (read-only by construction); **never** an external-plugin mapper agent that another installed tool registered.
+
+**The repo to map may be handed in by absolute path** (the scan root), so **never assume the current working directory is that repo**: search and read it by absolute path and run git as `git -C <scan root> ...`, and **never `cd` (or `pushd`/`env -C`) into it in any shape** (no `cd <root> && grep <relative>`, no bare `cd <root>` line then a relative read, no heredoc/multi-statement block, and not as a standalone `cd <root>` in an earlier Bash call: the cwd persists across calls). This keeps every read target statically determinable, so a bypass-permissions scan of an out-of-tree repo runs without a manual approval prompt. See **Search-command hygiene** in `../techniques.md`.
+
 - **Architecture**: pattern, layers, data flow, entry points, module seams; where the deep modules live.
 - **Stack & dependencies**: languages, runtime, frameworks, manifests, build/config, external integrations (DBs, APIs, auth, webhooks).
 - **Decisions already embodied / conventions**: style, naming, error handling, the repo's documented standards; patterns a new change must match.

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

@@ -2,6 +2,7 @@
 Interrogate the human live, one question at a time, until the decision is unambiguous and its rationale is captured. This is human-in-the-loop: the decision is theirs, so never answer on their behalf, never assume an answer you haven't heard, never proceed on silence.
 
 - **Map the decision as a tree.** Every choice branches into the choices that hang off it. The *frontier* is every question whose prerequisites are already settled: the ones you can ask now without guessing. A question whose answer depends on another still-open one isn't on the frontier yet; it arrives there the moment that answer lands. You don't ask the frontier in a batch: you pick one from it, and recompute after the answer.
+- **Breadth before depth: enumerate the whole surface first.** When the subject is a space with many parts (mapping an app or a project's scope, not a single isolated choice), open by enumerating every functional area it implies (for a video player: media library, search, thumbnails, filters, genres, the player itself, ...) and get them all onto the record before deep-diving any one. Depth on the current thread is seductive, but the tree only ever grows the questions you actually raise, so an area you never name never enters it and stays silently missing. Fan out first (name every area), then converge each. The deliverable is coverage of the whole surface, not a deep answer on one corner of it.
 - **One question at a time, with your pick.** Number the question, state it, and offer your recommended answer. Then stop and wait. Each answer reshapes the tree: settled decisions push the frontier outward. Recompute and ask the next. Grilling stays human-decides: the **grilled questions themselves never offer the delegate option** (a recommended answer is not the delegate option), because converging a decision is the human's. A separate meta-ask a call-site may put *before* grilling (e.g. the `build`/`quick` Discuss "do you want a grilling round?") is its own advisory choice and can offer delegate/defer per that call-site. **When a grilled decision is genuinely blocked on a prerequisite, offer defer in prose** (state it in words as part of the question), per the recipe in `../choices.md`.
 - **Facts are your job, decisions are theirs.** When a question needs a fact from the environment (filesystem, code, tools), go find it yourself; never ask the human what you could look up. Only questions downstream of that lookup wait; ask the rest now.
 - **Refuse vague and hedged answers.** "Good," "fast," "simple," "users," "later" are not answers: probe. *Fast how: sub-second, or handles large datasets? Users: the Customer or the operator?* Make the abstract concrete: "walk me through it," "give me an example," "what does that actually look like?"
@@ -10,5 +11,5 @@ Interrogate the human live, one question at a time, until the decision is unambi
 - **Steelman and play devil's advocate.** State the strongest case for the option they're leaning away from. Attack the option they favor from its weakest seam. If it survives, the decision is stronger; if it cracks, you found the real question.
 - **Detect and open up tradeoffs.** When "or / versus / torn between / which is better" appears, pause: name what each side optimizes for, what each sacrifices, which aligns with the goal, then recommend with reasoning. Skip for trivial or already-decided choices.
 - **Play back your understanding** before closing each branch: restate the decision and its rationale in your words and have them confirm or correct.
-- **Stop only when the frontier is empty**: every branch visited, nothing silently assumed, the choice unambiguous *and* the why recorded.
+- **Stop only when the frontier is empty**: every branch visited, nothing silently assumed, the choice unambiguous *and* the why recorded. **For a multi-part space** (per the breadth bullet above) also require every functional area to have been enumerated and visited: an empty frontier reached while whole areas were never raised is a false finish, because the tree only ever grew the questions you raised. A single isolated choice has no areas to enumerate, so its empty frontier is a real finish.