@marcomigozzi/trailhead 0.13.0 → 0.14.0

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

@@ -44,6 +44,32 @@
 // are shared with trailhead-search-guard.js via lib/shell-scan.js, so the two
 // guards can never drift into two divergent tokenizers again.
 //
+// #214 fix: a secret read inside a command substitution was missed when the
+// substitution sat in double quotes (`echo "$(cat .env)"`, `x="$(cat .env)"`,
+// `echo "$(true; cat .env)"`): the quoted token hid it, and the splitter cut
+// inside the `$(..)`. Each outermost `$(..)` / `<(..)` / `>(..)` body (from
+// substitutionBodies in lib/shell-scan.js) is now also scanned as a command,
+// off a depth- and size-capped work-list.
+//
+// #216 fix: the same miss for backtick substitutions (`echo "`cat .env`"`,
+// `x="`cat .env`"`, `echo "${x:-`cat .env`}"`). scanLine now tracks a backtick
+// span and substitutionBodies returns its body (unescaped as the shell would
+// run it) alongside the `$(..)` ones, so the work-list scans it too.
+//
+// #218 fix: the same miss for a substitution in the body of an UNQUOTED heredoc
+// (`cat <<EOF` with `$(cat .env)` or a backtick inside): the shell runs it, but
+// heredoc bodies are data to the splitter and were never lexed. Each unquoted
+// body is now lexed as the shell reads one (heredocSubstitutionBodies: quotes
+// are literal there) and its outermost substitution bodies join the work-list.
+// A quoted delimiter (`<<'EOF'`) and an escaped `\$(..)` stay literal.
+//
+// #223 fix: a heredoc body fed to a shell interpreter on stdin (`bash <<'EOF'`,
+// `sh <<EOF`, `cat <<EOF | bash`) is a script the shell runs, whatever the
+// delimiter quoting, but bodies were only ever data. Each statement is now paired
+// with its own bodies by position (as trailhead-secret-guard.js does); when a
+// statement of its pipeline invokes a shell from a closed set, those bodies join
+// the work-list as commands. No wrappers (sudo, exec, nohup): out of scope.
+//
 // #180 fix: `docker`/`podman` `--env-file .env` (or `--env-file=.env`) was a
 // false positive: the container RUNTIME reads that file, not the agent. Only
 // that flag's value is exempted, and only for docker/podman verbs; see
@@ -60,6 +86,14 @@
 // a link prepared under a non-secret name onto `.env`
 // (`ln -s .env.example l && mv l .env`).
 //
+// #227: a construct the guard cannot interpret with certainty (eval, source / `.`, a
+// bash 5.3 `${ cmd; }`, printf -v, a function definition, an alias, a quoted gh api body
+// key, a backslash-newline inside a word) is not emulated. As a FINAL gate, after the
+// precise scan, one that sits next to a secret-looking piece (`.env`, `.e""nv`, ...)
+// denies with SECRET_READ_UNMODELLED_CONSTRUCT and asks for the simple form; with no
+// such piece (`. venv/bin/activate && make`) it passes. The closed list is
+// lib/unmodelled.js.
+//
 // 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
@@ -76,7 +110,12 @@
 const {
   basename,
   stripQuotes,
-  splitStatements,
+  splitStatementsWithSeparators,
+  countHeredocs,
+  skipEnvPrefix,
+  substitutionBodies,
+  heredocBodies,
+  heredocSubstitutionBodies,
   tokenize,
   SEARCH_VERB_CONFIG,
   scanArgsSkippingPattern,
@@ -391,6 +430,47 @@ function scanStatementForSecretPath(stmt) {
   return scanTokensForSecretPath(tokens, exempt, nameOnlyTokenIndices(bin, tokens));
 }
 
+// #214: substitution bodies are scanned off an explicit work-list (no
+// recursion, so no stack overflow) under a cap on nesting depth and on the
+// total bytes of bodies scanned. Past the cap the remaining text is checked
+// crudely instead (see crudeSecretToken): the guard fails toward blocking.
+const MAX_SUB_DEPTH = 32;
+const MAX_SUB_BYTES = 64 * 1024;
+const CRUDE_SPLIT_RE = /[\s"'`()$;|&<>{}=]+/;
+
+// Fallback when the cap is hit: split the unscanned text on whitespace, quotes,
+// parens and operators, and return the first piece that is a secret path.
+function crudeSecretToken(text) {
+  for (const piece of text.split(CRUDE_SPLIT_RE)) {
+    if (piece && isSecretPathArg(piece)) return piece;
+  }
+  return null;
+}
+
+// #223: shells that read a script from stdin (closed set, no wrappers).
+const STDIN_SCRIPT_INTERPRETERS = new Set(['bash', 'sh', 'zsh', 'dash', 'ksh']);
+// Reserved words that may precede the command word (no grouping, no wrappers).
+const LEADING_KEYWORDS = new Set(['then', 'do', 'else', 'time', '!']);
+// `env` options whose value is the next token (separate form, no `=`).
+const ENV_VALUE_OPTIONS = new Set(['-u', '-C', '--unset', '--chdir']);
+
+// True when the statement runs one of those shells: after leading NAME=value
+// assignments, an optional `env` (with its NAME=value and -option words), the
+// command word's basename is in the set. Flags after it do not matter.
+function invokesInterpreter(stmt) {
+  const tokens = tokenize(stmt);
+  let i = 0;
+  while (i < tokens.length && LEADING_KEYWORDS.has(tokens[i])) i++;
+  i += skipEnvPrefix(tokens.slice(i));
+  if (i < tokens.length && basename(stripQuotes(tokens[i])) === 'env') {
+    i++;
+    while (i < tokens.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i]) || tokens[i].startsWith('-'))) {
+      i += ENV_VALUE_OPTIONS.has(tokens[i]) ? 2 : 1;
+    }
+  }
+  return i < tokens.length && STDIN_SCRIPT_INTERPRETERS.has(basename(stripQuotes(tokens[i])));
+}
+
 // 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,
@@ -398,10 +478,80 @@ function scanStatementForSecretPath(stmt) {
 // (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;
+  const work = [{ text: String(cmd), depth: 0 }];
+  let bytes = 0;
+  for (let w = 0; w < work.length; w++) {
+    const { text, depth } = work[w];
+    if (depth > 0) bytes += text.length;
+    if (depth > MAX_SUB_DEPTH || bytes > MAX_SUB_BYTES) {
+      const hit = crudeSecretToken(text);
+      if (hit) return hit;
+      continue;
+    }
+    const bodies = heredocBodies(text);
+    const entries = splitStatementsWithSeparators(text);
+    let next = 0;
+    const pushed = new Set(); // bodies already scanned whole as commands
+    let pipe = []; // consecutive statements joined by `|`
+    const flush = () => {
+      if (pipe.some((p) => invokesInterpreter(p.text))) {
+        for (const doc of pipe.flatMap((p) => p.docs)) {
+          work.push({ text: doc.body, depth: depth + 1 });
+          pushed.add(doc);
+        }
+      }
+      pipe = [];
+    };
+    for (const entry of entries) {
+      const hit = scanStatementForSecretPath(entry.text);
+      if (hit) return hit;
+      const docs = bodies.slice(next, next + countHeredocs(entry));
+      next += docs.length;
+      pipe.push({ text: entry.text, docs });
+      if (entry.sep !== '|') flush();
+    }
+    flush();
+    // #214: a statement cut inside `"$(..)"` loses the closing context, and a
+    // double-quoted token hides its body from the per-token walk; scan each
+    // outermost substitution body as a command of its own (nested ones next).
+    for (const body of substitutionBodies(text)) work.push({ text: body, depth: depth + 1 });
+    // #218: an unquoted heredoc body is data to the splitter, but the shell runs
+    // the substitutions in it; a quoted delimiter makes the body literal.
+    // (#223: a body already pushed whole as a command needs no second push.)
+    for (const doc of bodies) {
+      if (doc.quoted || pushed.has(doc)) continue;
+      for (const body of heredocSubstitutionBodies(doc.body)) work.push({ text: body, depth: depth + 1 });
+    }
+  }
+  return null;
+}
+
+// --- unmodelled constructs (#227) ----------------------------------------------
+
+// Does a text hold a secret-looking piece once live backslash-newlines are joined and
+// quote characters dropped (`.e""nv` is `.env` to the shell)? Crude by design: the
+// precise scan above is exact and runs first, this only has to catch what it cannot see.
+function crudeSecretPiece(text) {
+  return crudeSecretToken(String(text).replace(/\\\n/g, '').replace(/["'`]/g, ''));
+}
+
+// A construct the guard cannot interpret (eval, source / `.`, a bash 5.3 `${ cmd; }`,
+// printf -v, a function definition, an alias, a quoted gh api body key, a backslash-newline
+// inside a word) next to a secret-looking piece: { hit, piece } or null. The piece only has
+// to sit in the construct's own statement or in the code it hides, which is not proof of a
+// read (`printf -v x %s .env` blocks too): the uncertain shape is blocked and the simple
+// form asked for, not emulated.
+function unmodelledSecretPiece(cmd) {
+  let lib; // loaded lazily: a missing or broken lib only switches this gate off
+  try {
+    lib = require('./lib/unmodelled.js');
+  } catch {
+    return null;
+  }
+  for (const hit of lib.findUnmodelled(cmd)) {
+    if (hit.id === 'api-field') continue; // a body-write concern (body-guard), not a read
+    const piece = crudeSecretPiece(hit.stmt) || crudeSecretPiece(hit.payload);
+    if (piece) return { hit, piece };
   }
   return null;
 }
@@ -420,12 +570,27 @@ function detectSecretRead(toolName, toolInput) {
   if (toolName === 'Bash') {
     const cmd = input.command || '';
     const hit = scanBashForSecretPath(cmd);
-    return hit ? { path: hit } : null;
+    if (hit) return { path: hit };
+    const um = unmodelledSecretPiece(cmd); // a final gate: the precise scan keeps priority
+    return um ? { path: um.piece, unmodelled: um.hit } : null;
   }
   return null;
 }
 
+function blockUnmodelled(hit) {
+  let redact; // the secret-guard's redactor; without it the message omits the sample
+  try {
+    ({ redact } = require('./trailhead-secret-guard.js'));
+  } catch {
+    redact = undefined;
+  }
+  const reason = require('./lib/unmodelled.js').unmodelledReason('secret-read guard', 'that it does not read a secret file (.env / .env.* / .secrets)', hit.unmodelled, redact);
+  process.stdout.write(JSON.stringify({ decision: 'block', code: 'SECRET_READ_UNMODELLED_CONSTRUCT', reason }));
+  process.exit(2);
+}
+
 function block(hit) {
+  if (hit.unmodelled) blockUnmodelled(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 ' +

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

@@ -34,6 +34,18 @@ ok('Bash grep -n KEY .env.production is denied', !!detectSecretRead('Bash', { co
 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' }));
 
+// --- line continuation splits a secret path (#222) ---
+ok('Bash cat \\<nl>.env is denied', !!detectSecretRead('Bash', { command: 'cat \\\n.env' }));
+ok('Bash echo $(cat \\<nl>.env) is denied', !!detectSecretRead('Bash', { command: 'echo $(cat \\\n.env)' }));
+ok('Bash cat .e\\<nl>nv is denied', !!detectSecretRead('Bash', { command: 'cat .e\\\nnv' }));
+ok('Bash cat .e\\\\<nl>nv (escaped backslash) is allowed', !detectSecretRead('Bash', { command: 'cat .e\\\\\nnv' }));
+ok('Bash continuation inside single quotes stays literal', !detectSecretRead('Bash', { command: "echo 'x\\\n.env'" }));
+ok('Bash consecutive continuations cat \\<nl>\\<nl>.env are denied', !!detectSecretRead('Bash', { command: 'cat \\\n\\\n.env' }));
+ok('Bash separator on the continuation line is denied', !!detectSecretRead('Bash', { command: 'echo a \\\n; cat .env' }));
+ok('Bash continuation inside a backtick span is denied', !!detectSecretRead('Bash', { command: 'echo `cat \\\n.env`' }));
+ok('Bash continuation inside "$(..)" is denied', !!detectSecretRead('Bash', { command: 'echo "$(cat .e\\\nnv)"' }));
+ok('Bash trailing backslash on the last line is allowed', !detectSecretRead('Bash', { command: 'echo done \\' }));
+
 // --- 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' }));
@@ -46,6 +58,8 @@ ok('Read .environment (near-miss) is allowed', !detectSecretRead('Read', { file_
 // --- #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 after an arithmetic << on the previous line is denied (#212)',
+  !!detectSecretRead('Bash', { command: 'echo $((1<<3))\ncat .env' }));
 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"' }));
@@ -180,13 +194,169 @@ denyCmd('cp .env.example .env -f');
 denyCmd('cp .env.example .env && cat .env');
 denyCmd('git check-ignore .env; cat .env');
 
+// #214: a secret read inside a command substitution, even double-quoted
+const hit214 = (c) => { const r = detectSecretRead('Bash', { command: c }); return !!r && r.path === '.env'; };
+for (const c of ['echo "$(true; cat .env)"', 'echo "$(cat .env)"', 'x="$(cat .env)"', 'diff <(cat .env) x',
+  'echo "$(echo "$(cat .env)")"', 'echo "$(\ncat .env\n)"']) {
+  ok(`Bash \`${c}\` is denied with path .env (#214)`, hit214(c));
+}
+allowCmd("echo '$(cat .env)'");
+allowCmd('echo "$(echo hi)"');
+allowCmd('echo "$((1+2))"');
+allowCmd('git commit -m "document .env usage"');
+
+// #214 review: heredoc inside a substitution, substitution inside arithmetic
+for (const c of ['echo "$(cat <<E\nfoo\nE\n; cat .env)"', 'echo $(cat <<E\nfoo\nE\n; cat .env)',
+  'echo "$(( $(cat .env) ))"', 'echo $(( $(cat .env) ))', 'echo "$[ $(cat .env) ]"']) {
+  ok(`Bash \`${c}\` is denied with path .env (#214 review)`, hit214(c));
+}
+allowCmd('echo "$((1+2))"');
+allowCmd('echo $((a+(b)))');
+allowCmd('echo "$(( $(echo 1) + 1 ))"');
+
+// #216: a secret read inside a backtick substitution, even double-quoted
+for (const c of ['echo "`cat .env`"', 'x="`cat .env`"', 'echo "${x:-`cat .env`}"', 'echo `cat .env`',
+  'echo "$(echo `cat .env`)"', 'echo `echo $(cat .env)`', 'echo `echo \\`cat .env\\``']) {
+  ok(`Bash \`${c}\` is denied with path .env (#216)`, hit214(c));
+}
+for (const c of ['echo "`echo \'"\'`"; cat .env', 'echo `true\ncat .env\n`',
+  'echo `echo \\`echo \\\\\\`cat .env\\\\\\`\\``']) {
+  ok(`Bash \`${c}\` is denied with path .env (#216 review)`, hit214(c));
+}
+{ // \" inside a double-quoted backtick body: bash reads the quoted .env (the path keeps its quotes)
+  const r = detectSecretRead('Bash', { command: 'echo "`cat \\".env\\"`"' });
+  ok('Bash `echo "`cat \\".env\\"`"` is denied (#216 review)', !!r && /\.env/.test(r.path));
+}
+allowCmd('echo "run `ls` then `pwd`"');
+allowCmd("echo '`cat .env`'");
+allowCmd('echo "\\`cat .env\\`"');
+
+// #218: a secret read inside the body of an UNQUOTED heredoc (the shell runs $(..) and backticks there)
+for (const c of ['cat <<EOF\n$(cat .env)\nEOF', 'cat <<EOF\n`cat .env`\nEOF', 'cat <<-EOF\n\t$(cat .env)\n\tEOF',
+  "cat <<EOF\nit's $(cat .env)\nEOF", 'cat <<EOF\nsay "hi $(cat .env)\nEOF', 'cat <<EOF\n${x:-$(cat .env)}\nEOF',
+  'cat <<EOF\nfirst line\nthen text $(cat .env) more\nEOF', 'x=$(cat <<EOF\n$(cat .env)\nEOF\n)',
+  'cat <<A\n$(cat <<B\n)\nB\ncat .env)\nA', 'cat <<EOF\n$\\\n(cat .env)\nEOF', 'cat <<EOF\n$(cat .e\\\nnv)\nEOF',
+  'cat <<EOF\n$(cat \\\n.env)\nEOF', "cat <<A <<'B'\n$(cat .env)\nA\nx\nB"]) {
+  ok(`Bash \`${c}\` is denied with path .env (#218)`, hit214(c));
+}
+for (const c of ["cat <<'EOF'\n$(cat .env)\nEOF", 'cat <<"EOF"\n$(cat .env)\nEOF', "cat <<'EOF'\n`cat .env`\nEOF",
+  'cat <<EOF\n$$(cat .env)\nEOF', "cat <<A <<'B'\nx\nA\n$(cat .env)\nB",
+  'cat <<EOF\n\\$(cat .env)\nEOF', 'cat <<EOF\n\\`cat .env\\`\nEOF', 'cat <<EOF\ncat .env\nEOF']) {
+  allowCmd(c);
+}
+
+// #223: a heredoc body fed to a shell interpreter on stdin is a script, whatever the delimiter quoting
+for (const c of ["bash <<'EOF'\ncat .env\nEOF", 'sh <<EOF\ncat .env\nEOF', 'bash <<EOF\ncat .env\nEOF',
+  'cat <<EOF | bash\ncat .env\nEOF', 'zsh -s <<EOF\ncat .env\nEOF', 'VAR=1 bash <<EOF\ncat .env\nEOF',
+  'env FOO=1 bash <<EOF\ncat .env\nEOF', '/bin/bash <<EOF\ncat .env\nEOF', 'dash <<EOF\ncat .env\nEOF',
+  'env -i FOO=1 ksh <<EOF\ncat .env\nEOF', "cat <<'EOF' | sh\ncat .env\nEOF", 'bash -x <<EOF\necho $(cat .env)\nEOF',
+  'echo hi; bash <<EOF\ncat .env\nEOF']) {
+  ok(`Bash \`${c}\` is denied with path .env (#223)`, hit214(c));
+}
+// #223 review: env option values, leading shell keywords, heredoc pairing
+for (const c of ['env -u FOO bash <<EOF\ncat .env\nEOF', 'env -C /tmp bash <<EOF\ncat .env\nEOF',
+  'env --unset FOO sh <<EOF\ncat .env\nEOF', 'env --chdir /tmp bash <<EOF\ncat .env\nEOF',
+  'env -S bash <<EOF\ncat .env\nEOF', 'if true; then bash <<EOF\ncat .env\nEOF', 'time bash <<EOF\ncat .env\nEOF',
+  'while x; do bash <<EOF\ncat .env\nEOF', '! bash <<EOF\ncat .env\nEOF', 'true; then time bash <<EOF\ncat .env\nEOF',
+  'cat <<EOF |& bash\ncat .env\nEOF', 'bash <<EOF &\ncat .env\nEOF', 'cat <<A; bash <<B\necho hi\nA\ncat .env\nB']) {
+  ok(`Bash \`${c}\` is denied with path .env (#223 review)`, hit214(c));
+}
+allowCmd('cat <<A; bash <<B\ncat .env\nA\necho hi\nB');
+
+for (const c of ["cat <<'EOF'\ncat .env\nEOF", 'cat <<EOF\ncat .env\nEOF', "tee f <<'EOF'\ncat .env\nEOF",
+  'cat <<EOF; bash x.sh\ncat .env\nEOF', "bash <<'EOF'\necho hi\nEOF", 'cat <<EOF | bash\necho hi\nEOF']) {
+  allowCmd(c);
+}
+
+// #214: deep nesting is bounded (explicit work-list, capped), never a stack overflow
+{
+  const nest = (n, inner) => 'echo ' + '"$('.repeat(n) + inner + ')"'.repeat(n);
+  for (const n of [40, 2000, 6000]) {
+    const t0 = Date.now();
+    const r = detectSecretRead('Bash', { command: nest(n, 'cat .env') });
+    const ms = Date.now() - t0;
+    ok(`nesting n=${n} with a secret is denied with path .env`, !!r && r.path === '.env');
+    ok(`nesting n=${n} with a secret completes under 1s (${ms}ms)`, ms < 1000);
+  }
+  const t1 = Date.now();
+  const clean = detectSecretRead('Bash', { command: nest(6000, 'cat README.md') });
+  const ms1 = Date.now() - t1;
+  ok('deep nesting with no secret is allowed', clean === null);
+  ok(`deep nesting with no secret completes under 1s (${ms1}ms)`, ms1 < 1000);
+}
+
 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() === '');
 
+// --- #227: constructs the guard cannot interpret, near a secret-looking piece ---
+{
+  const CODE = 'SECRET_READ_UNMODELLED_CONSTRUCT';
+  const code = (command) => { const r = runHook('Bash', { command }); return r.code === 2 ? JSON.parse(r.out).code : null; };
+  for (const c of [
+    'eval cat .e""nv',
+    'eval "cat .e\'\'nv"',
+    'echo ${ cat .e""nv; }',
+    'echo ${| cat .e""nv; }',
+    'source .e""nv',
+    '. .e""nv && make',
+    'printf -v x %s .e""nv',
+    "alias c='cat .e\"\"nv'",
+    "alias c='cat .env'; c",
+    'f() { cat .e""nv; }; f',
+    'echo "${ cat .e""nv; }"',
+    'x=$(source .e""nv)',
+  ]) {
+    const hit = detectSecretRead('Bash', { command: c });
+    ok(`denies an unmodelled construct near a secret piece: ${c}`, !!hit && !!hit.unmodelled);
+    ok(`... with the unmodelled code (exit 2): ${c}`, code(c) === CODE);
+  }
+  ok('a quoted api body key mentioning .env in prose is not a read', detectSecretRead('Bash', { command: "gh api -X PATCH repos/a/b/issues/1 -f 'body'='document the .env file'" }) === null);
+  ok('... and the hook allows it', runHook('Bash', { command: "gh api -X PATCH repos/a/b/issues/1 -f 'body'='document the .env file'" }).code === 0);
+  // The precise scan keeps priority and its code.
+  ok('a precise read keeps SECRET_READ_BLOCKED', code('eval cat .env') === 'SECRET_READ_BLOCKED');
+  ok('a precise read inside a function body keeps SECRET_READ_BLOCKED', code('f() { cat .env; }; f') === 'SECRET_READ_BLOCKED');
+  ok('detectSecretRead keeps { path } for a precise read', (() => { const h = detectSecretRead('Bash', { command: 'cat .env' }); return h && h.path === '.env' && !h.unmodelled; })());
+  // Plain controls pass: the construct has no secret-looking piece near it.
+  for (const c of [
+    '. venv/bin/activate && make',
+    'source ~/.venv/bin/activate && pytest',
+    "alias ll='ls -l'",
+    'alias g=gh; g issue list',
+    'eval "$(ssh-agent)"',
+    'printf -v x %s y; echo $x',
+    'f() { ls; }; f',
+    'echo ${ date; }',
+    'echo "alias .environment"',
+    'cat .e\\\n  nv.md',
+  ]) ok(`allows a construct with no secret piece: ${c}`, detectSecretRead('Bash', { command: c }) === null && runHook('Bash', { command: c }).code === 0);
+  const r = runHook('Bash', { command: 'echo ${ cat .e""nv; }' });
+  const reason = JSON.parse(r.out).reason;
+  ok('the message names the guard and asks for the simple form', /^trailhead secret-read guard: /.test(reason) && /Rewrite it in a simple form/.test(reason));
+  const T = 'ghp_' + 'a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8'.slice(0, 36);
+  const leak = JSON.parse(runHook('Bash', { command: `echo \${ cat .e""nv; echo ${T}; }` }).out).reason;
+  ok('the message never echoes a token', !leak.includes(T) && !leak.includes('ghp_'));
+}
+
 // --- crash safety ---
 const crash1 = runHook('Read', undefined);
 ok('missing tool_input never crashes (exit 0)', crash1.code === 0);
 
+// --- #227: a missing unmodelled lib degrades to the previous behaviour ---
+{
+  const fs = require('fs');
+  const os = require('os');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'srg-nolib-'));
+  fs.mkdirSync(path.join(dir, 'lib'));
+  for (const f of fs.readdirSync(path.join(__dirname, 'lib'))) {
+    if (/\.(js|json)$/.test(f) && !f.endsWith('.test.js') && f !== 'unmodelled.js') fs.copyFileSync(path.join(__dirname, 'lib', f), path.join(dir, 'lib', f));
+  }
+  fs.copyFileSync(path.join(__dirname, 'trailhead-secret-read-guard.js'), path.join(dir, 'trailhead-secret-read-guard.js'));
+  const bare = require(path.join(dir, 'trailhead-secret-read-guard.js'));
+  ok('without the unmodelled lib the guard still loads and denies a precise read', !!bare.detectSecretRead('Bash', { command: 'cat .env' }));
+  ok('without the unmodelled lib the unmodelled gate is off', bare.detectSecretRead('Bash', { command: 'source .e""nv' }) === null);
+  fs.rmSync(dir, { recursive: true });
+}
+
 console.log(`✓ secret-read-guard: ${passed} assertions passed`);

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

@@ -4,6 +4,8 @@ When trailhead must put a **forced choice** to the human (any `AskUserQuestion`-
 
 **Host constraint.** These options exist only inside questions **trailhead itself authors**. The host `AskUserQuestion` tool is not ours to change; we add the options as extra choices in the prompts we build.
 
+**Which format.** Count the **real options** (the delegate/defer affordances never count). A forced choice with **up to 4 real options** is always put as an `AskUserQuestion` menu, never as a prose list: the menu rules below apply (dedup, cap, links in the prose). A forced choice with **more than 4 real options** cannot fit the menu, so put it as a **lettered list** in prose, one option per line (**(a)**, **(b)**, ...), with any applicable affordance appended as its own letter, then wait for the user's pick (a letter or the option's text). The lettered `(a)/(b)/(c)` options written in these instructions name the options to offer, not the format: render them per this rule. Conversational call-sites (grilling) stay in prose. On Codex, which has no `AskUserQuestion`, the plain-text numbered list of its adapter replaces the menu.
+
 ## The one-line test: whose choice is it?
 
 Before offering the delegate option, ask: **is the answer itself a project decision (a `decision`-ticket's answer, or a change to the map's destination or scope), as opposed to a process choice that merely gets folded into some ticket's ordinary resolution summary?**
@@ -54,7 +56,7 @@ 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).
+**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); the Claude Code guard also accepts a link carried by the approval question itself, but the prose stays the preferred form.
 
 **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.**
 

package/plugins/trailhead/skills/_shared/multi-map.md

@@ -13,7 +13,7 @@ gh issue list --label "trailhead:ticket" --label "trailhead:map-<n>" --state ope
   --search "no:assignee -label:trailhead:blocked -label:trailhead:unverified"
 ```
 
-**Active map.** Which map a session works is the **active map**: a `.trailhead/active-map` marker at the working root (one line `#<n>`, **gitignored**, per-session local state like `session-ticket`, never committed). `/trailhead:work` and `/trailhead:map` default to it; naming a map/ticket explicitly always overrides. Each checkout/clone (so each teammate) has its own.
+**Active map.** Which map a session works is the **active map**: a `.trailhead/active-map` marker at the working root (one line `#<n>`, **gitignored**, per-session local state like `session-ticket`, never committed). `/trailhead:work` and `/trailhead:map` default to it; naming a map/ticket explicitly always overrides. A named ticket that carries a `trailhead:map-<n>` label makes that map the active map (write `.trailhead/active-map`); a whiteboard ticket leaves the active map alone. Each checkout/clone (so each teammate) has its own.
 
 **Park & switch** = **pause** the in-flight ticket (`/trailhead:pause`, a `PAUSED` checkpoint), then point the active map at the other's number. Nothing else to save: every map lives on the Issues, durable. Resume later with `/trailhead:resume`, or just `/trailhead:work` once that map is active again.
 

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

@@ -1,6 +1,6 @@
 ## Session handoff
 
-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:
+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) and **clear the work state** (`node <templates>/trailhead-work-state.js clear --repo <working-root>`, see **Work state file** in `teamwork.md`), 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 and number, both visible (e.g. *Add login rate limit* (#45), never the name alone nor a bare `#number`).

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

@@ -49,8 +49,8 @@ With the default `auto` this choice is made for you at each ticket's work-start;
 
 ## 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. **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.
+- **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. Either way, set the work state `--step paused` and keep the file. **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), and set the work state to the recorded next step, in the full work-start form (`--map`, `--ticket`, `--title`, `--step <next step>`) so the file is re-created when absent; 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.
 
 ## Parking & switching between maps
@@ -97,3 +97,5 @@ The map issue's **body** is a shared mutable document: two sessions appending to
 **Keeping the guard current (migration).** The guard filters at **job level** (`jobs.guard.if`: a `trailhead:` label, a sender other than the repo owner, not in `TRAILHEAD_LABEL_ALLOWLIST`), because a skipped job is not billed while a job that starts and returns early from its script costs at least one Actions minute; the in-script permission check stays the real defence. Guards installed before 0.12.1 lack that `if:` and start a runner on **every** label event, which with trailhead labelling all the time runs into thousands of billed runs a month. So whenever the guard is present (every chart/adopt, and after `/trailhead:update`), run `node <templates>/trailhead-label-guard-sync.js --repo <working-root>` (same `<templates>` lookup as the commit-msg sync script below). It prints one JSON status line: `current` (nothing to do), `outdated` (offer the upgrade and always explain why in the question, in plain words: today every label added to an issue starts a run billed at least one minute even when it does nothing, trailhead labels constantly so that adds up to thousands of billed runs a month and can exhaust the Actions minutes, and the updated guard skips irrelevant events before a runner starts with the same protection), `custom` (has the job-level filter but differs from the template: leave it, mention it only if asked), `foreign` (not a trailhead workflow: never touched), `absent` (install as above). On go-ahead for `outdated`, re-run it with `--apply` (it rewrites the file from the template in the working tree only, never a foreign or customised guard), then commit it (`fix: skip trailhead label guard job for irrelevant label events`) and push, with the same `workflow`-scope caveat. The SessionStart hook (or, on a host with no hook bus, the load-first check) also runs it with `--notice` at every session start and surfaces the same upgrade offer until the user answers it; `--ack` records the answer in the gitignored `.trailhead/label-guard-ack` (the guard's hash), so a declined offer comes back only if the file changes. If the script is missing (an outdated install), fall back to reading the file and checking `jobs.guard` for an `if:` containing `startsWith(github.event.label.name, 'trailhead:')`.
 
 **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.
+
+**Work state file (the ticket in play, for tooling).** Alongside the session-ticket marker, trailhead keeps a gitignored `.trailhead/work-state.json` at the working root recording the one ticket in play: `{map, ticket, title, step, auto, autoDone, session, updatedAt}` (`autoDone` is the number of tickets resolved so far in an autonomous run, `0` otherwise). It is independent of `session-ticket` and of the commit-msg hook, and written the same way on Claude Code and Codex by the template helper `trailhead-work-state.js`, found with the same three-dir `<templates>` lookup as the commit-msg sync above (the first of `${CLAUDE_PLUGIN_ROOT}/templates/`, `~/.claude/trailhead/templates/`, `~/.codex/skills/trailhead/templates/` that contains it). Forms: `node <templates>/trailhead-work-state.js set --repo <working-root> --map <n|none> --ticket <n> --title "<title>" --step discuss` at work-start (`--map none` for a whiteboard ticket), `node <templates>/trailhead-work-state.js set --repo <working-root> --step <step>` at each step change (`discuss`, `plan`, `execute`, `verify`, `resolve`, `paused`; it merges onto the file, and a different `--ticket` starts it fresh; it needs a ticket on file, so where the file may be absent, as at resume or a pause in a fresh workspace, pass the full work-start form with that step), and `node <templates>/trailhead-work-state.js clear --repo <working-root>` at Resolve. During an autonomous run every `set` adds `--auto true --auto-done <n>`, `n` being the tickets resolved so far in this run. The step-to-state mapping per ticket type lives in `trailhead-work/references/ticket-engines.md`. A missing helper or a non-zero exit is silent and never blocks the work (no user-facing line).

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

@@ -30,7 +30,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 canvas Artifact URL plus the **artboard title** of each screen (`artifacts`: one canvas URL, then one line per screen or variant naming its artboard and page, since artboards have no URL of their own), or the Stitch project/screen URL (`stitch`). 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 canvas'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.
+**"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 canvas Artifact URL plus the **artboard title** of each screen (`artifacts`: one canvas URL, then one line per screen or variant naming its artboard and page, since artboards have no URL of their own), or the Stitch project/screen URL (`stitch`). 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 canvas'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 (it also accepts a link carried by the approval question itself, but the prose stays the preferred form since a picker's text is not clickable); 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|audit|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|panel|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`, `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.
+- **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>`). The **`panel`** verb routes to no skill: it is answered by the trailhead mod on Claude Code 2.1.287+ (`/trailhead:panel` opens or closes the live map panel), and where no mod answers, say in one line that the panel is not available in this session. 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-work/SKILL.md

@@ -37,13 +37,14 @@ This guard is the **explicit-number paths only**. Bare `work` selects from the l
 
 The user invokes with a map (URL or number). A ticket is optional: without one, you pick the next decision.
 
-1. Load the **map** (the low-res view, not every ticket body). **Pick which map** if the repo has several open: use the one the user named, else the active map (`.trailhead/active-map`); if neither and more than one is open, list them and ask. Set/refresh the active-map marker to the one you're working. See **Multiple maps on one repo** in `../_shared/multi-map.md`. **Codebase issue check (greenfield, offer once):** if the repo has **no `trailhead:codebase` issue** (a greenfield map never got one) and now holds **substantial code**, **don't interrupt the work to offer now**: mark the offer **pending** and surface it **at the handoff**, just before the `/clear`-first next-step block (not as a line inside it: see the **pending codebase offer** rule in `../_shared/session-handoff.md`), exactly once. On the user's yes, generate it via the **Codebase map** technique, then pin it (one of the three permanent repo pins: dashboard, codebase, conventions) and link it from the map's Notes; if the user declines, don't nag again this session. A repo that already has the issue, or is still too thin to map, skips this.
+1. Load the **map** (the low-res view, not every ticket body). **Pick which map** if the repo has several open: use the one the user named, else the active map (`.trailhead/active-map`); if neither and more than one is open, list them and ask. Set/refresh the active-map marker to the one you're working. **Named ticket:** its map becomes the active map, a whiteboard ticket leaves it alone (see **Active map** in `../_shared/multi-map.md`, under **Multiple maps on one repo**). **Codebase issue check (greenfield, offer once):** if the repo has **no `trailhead:codebase` issue** (a greenfield map never got one) and now holds **substantial code**, **don't interrupt the work to offer now**: mark the offer **pending** and surface it **at the handoff**, just before the `/clear`-first next-step block (not as a line inside it: see the **pending codebase offer** rule in `../_shared/session-handoff.md`), exactly once. On the user's yes, generate it via the **Codebase map** technique, then pin it (one of the three permanent repo pins: dashboard, codebase, conventions) and link it from the map's Notes; if the user declines, don't nag again this session. A repo that already has the issue, or is still too thin to map, skips this.
 2. Choose the ticket. **If the user named a ticket, the Preflight above already confirmed it is open** (a closed, superseded, out-of-scope, or nonexistent number stopped there, before any setup ran). If the user names one, use it (a **named** ticket may be a `trailhead:whiteboard` one: `work <n>` works it whole, off the map, with the normal cycle and split allowed; use `quick <n>` for the no-split variant). Otherwise take a frontier ticket to act on, **scoped to this map** (add its `trailhead:map-<n>` label to the frontier query when several maps are live) and **never a whiteboard ticket** (bare `work` stays on the map; the whiteboard frontier is reached via `/trailhead:whiteboard` and `quick`). Bare `work` may act on the first ticket the query returns, but that order is `gh`'s newest-first, not a priority: present several independent tickets as a **set to choose from**, not the graph's natural next step (see **Frontier order carries no priority** in `../_shared/substrate.md`). **Claim** it: assign it to yourself before any work, then re-read the assignee before starting; on a collision, stop and ask the user (see `../_shared/teamwork.md`). If the ticket proves too big once you're in it, propose a **split** rather than grind, but never split on your own: present the children you would create and wait for the user's go-ahead before creating anything (same file).
    - **First, resolve the effective isolation mode.** The `isolation:` header defaults to **`auto`** (an absent key means `auto`; the engine never writes the key). Under **`auto`**, at work-start **before any file edit or diagnostic probe**, first run the read-only **assigned-ticket pre-check** (full rule in `../_shared/teamwork.md`): other open tickets already assigned to you **pre-bias** the ask toward `worktree`/`clone` (still asking, easy neutral), and the ask is **skipped** only when the session is already inside this ticket's own linked worktree (`trailhead/t<N>`, `N` the current ticket). Then ask the user once whether they will work more than one ticket at once on this machine this session. **No** (a lone ticket): the mode resolves to the current checkout, exactly like `none` (the scope-free check below applies). **Yes**: resolve by repo shape, a plain repo -> `worktree`, a **superrepo** (a `.gitmodules` at the checkout root declaring at least one submodule) -> `clone`; that "yes" **is** the clone gate's answer, so the resolved `clone` path proceeds without re-asking. Because trailhead resolves one ticket per session, this asks at most once per ticket work-start (so once per session in normal work; a within-session ticket switch re-asks at the new ticket's work-start), and an autonomous run (`/trailhead:auto`) never asks and never runs the pre-check (sequential work, no concurrency) and resolves to the current checkout. If the header carries an **explicit** `none`/`worktree`/`clone`, honour it as-is (never subject it to auto's ask): explicit `clone` keeps its own gate, explicit `worktree` is eager. See `../_shared/teamwork.md`.
    - **When the resolved mode is the current checkout (`isolation: none`, or `auto` answered no), check the scope is free before starting** (this is how a submodule/package gets serialised when worktrees don't fit): scan the other in-progress tickets' `Scope:` lines, and if one **overlaps** this ticket's scope, **stop and tell the user** the scope is busy (name the ticket + holder) and offer a disjoint-scope frontier ticket or to wait. See `../_shared/teamwork.md`.
    - **Write the session-ticket marker**: at the **working root** (the checkout, worktree, or clone you'll edit in), write `.trailhead/session-ticket` as **one line** `#<n> <ticket title>`. **Keep it gitignored** (add `.trailhead/session-ticket` to that repo's `.gitignore` if absent): it's per-session local state, **never committed**. It lets an external tool show "what am I on" offline (the tracker stays the source of truth), but it is not merely that cheap hint: while it is present, the git commit-msg hook also requires every commit to carry a `Refs: #<n>` trailer matching it, so a stale marker left behind would wrongly demand that trailer on unrelated commits. Remove it at Resolve/handoff (see `../_shared/session-handoff.md`); on **Pause** it may stay (you'll return) or be cleared if you release the claim. The **`.trailhead/active-map`** marker (which map this session works) follows the same rules: gitignored, per-session, never committed; see **Multiple maps on one repo** in `../_shared/multi-map.md`.
    - **Sync the commit-msg hook**: at the working root, run `node <templates>/trailhead-commit-msg-sync.js --repo <working-root>` (where `<templates>` lives and what each status means: the commit-msg hook paragraph in `../_shared/teamwork.md`). Stay silent when it reports installed or current. On **upgraded**, give the user one result-oriented line: this clone's commit-msg hook was updated to the current rules. On **foreign**, one line that the user's own hook was left untouched and git does not enforce trailhead's rules here. On **skipped**, one line that nothing was set up here (a `core.hooksPath` without a trailhead hook, or a working root that is not a git repo) and git does not enforce trailhead's rules. On a missing script or a node error (missing means none of the three template dirs has it: try them all before concluding that), inspect the hooks dir (`git rev-parse --git-path hooks`) and report per the fallback in that same paragraph of `../_shared/teamwork.md` (trailhead hook present and executable: enforced but freshness unchecked, update the install; present but not executable: git skips it, not enforced; foreign hook: untouched, not enforced; no hook: not enforced, update the install), never a blind "not enforced"; it never blocks the work.
    - **When the resolved mode is `worktree` or `clone` (explicit, or `auto` answered yes), set up the isolated workspace NOW, before any file edit or diagnostic probe** (not later at Execute/Fix): **if the repo has submodules (a `.gitmodules`), `isolation: worktree` is escalated to `clone`** (a superproject worktree cannot safely carry submodule state; see `../_shared/teamwork.md`). For `worktree` (no submodules), create/enter this ticket's `git worktree` on a `trailhead/t<n>` branch for the package/path the ticket's `Scope:` names (a submodule-bearing repo would have escalated to `clone` above), e.g. `git worktree add ../<repo>-t<n> -b trailhead/t<n>`; for `clone`, make an independent working copy at `../<repo>-t<n>` (branch `trailhead/t<n>`) by whichever is faster: `git clone` (add `--recurse-submodules` when the repo has submodules) + the install step, or a **folder copy that brings `node_modules`** (and the submodule working trees) to skip the reinstall (then verify the copy's git is independent, `git -C <copy> rev-parse --absolute-git-dir` resolves inside it, and the same inside every submodule, else commits leak back to the original); a clone with submodules is provisioned via `git submodule update --init --recursive` (nested included), each scoped submodule pinned at the superproject's recorded commit. **If this `clone` was reached via `auto`'s work-start ask (answered yes), that ask already served as the clone gate: do not re-ask, proceed to set up the clone. Under an explicit `isolation: clone`, run the gate as follows.** **Because `clone` is heavy (a full clone + an install), gate it, every time, before cloning: ask the user whether they expect to work more than one ticket at once on this machine this session.** If **no**, **skip the clone** and work this ticket in the current checkout (isolation only exists to stop concurrent workspaces from colliding; a lone ticket has nothing to collide with, so the shared-checkout caveats apply and that is fine, and `git:` still decides the branch as usual); if **yes**, clone as above. The gate is **`clone`-only**: `worktree` is cheap, so set it up without asking. Do every subsequent step in whatever workspace you ended up in. This is the whole point of isolation: if you diagnose and edit in the shared checkout "just to start" while a concurrent workspace exists, you are already colliding. Set the workspace up silently (the `clone` gate-question is the one exception you voice); it's undone at Resolve when the branch integrates and the worktree/clone is removed. See `../_shared/teamwork.md`.
+   - **Write the work state, last** (the working root is final only now): `node <templates>/trailhead-work-state.js set --repo <working-root> --map <n> --ticket <n> --title "<title>" --step discuss`, and add `.trailhead/work-state.json` to that repo's `.gitignore` if absent. It is updated at every step change and cleared at Resolve; the canonical description, the `<templates>` lookup, and the silent-on-failure rule are the **Work state file** paragraph in `../_shared/teamwork.md`, and the step mapping per type is in `references/ticket-engines.md`.
 3. **Brief the ticket and confirm scope, before the engine runs.** With the ticket claimed, read it and give the user a **brief, result-oriented summary of what resolving it will do** (its goal and the shape of the work, not a plan yet), then **ask whether they want to change anything**. This is a HITL confirm gate: on assent, proceed to the engine. **If the user asks for a change, hold it against the ticket.** A change **consistent** with the ticket is folded in and the engine proceeds. A change that **diverges** from the ticket is surfaced as a mismatch, and the user is **asked, never forced**, whether to (a) work the ticket **as-is**, or (b) open a **separate new ticket** for the divergent request. Offer both and decide neither: open the separate ticket **only if the user chooses it** (via **Scope that surfaces while working a ticket**, served by the capture cluster, the same capture-or-split path used for scope that surfaces mid-work), never automatically. **If the user defers the choice rather than settling it here, mark the divergent follow-up pending for the Pending follow-up guard (`../_shared/session-handoff.md`), so it is re-posed at the handoff rather than lost.** **Under an autonomous run (`auto`) this is a process confirm gate**, so it follows the advisory boundary in `references/auto.md`: `auto` proceeds (takes the delegate option) without stopping to brief.
 4. Resolve it with its type's engine in **`references/ticket-engines.md`**, **zoom as needed**: fetch the full body of related/closed tickets on demand. If in doubt on a `decision` ticket, run **Grilling** + **Domain vocabulary**. If in doubt on a `build`, **stop and ask** (see the Discuss step): never auto-grill.
 5. Record the resolution: a comment with the answer, `gh issue close`, add the pointer to *Decisions so far*. Then **unblock dependents**: for every ticket this one was blocking, if it was the last open blocker, remove its `trailhead:blocked` label so it graduates onto the frontier.
@@ -59,7 +60,7 @@ It runs the **full engine** (the `build`/`bug` cycle in `references/ticket-engin
 - **Grill only if needed** (Discuss): never auto-grill; start from Plan and stop to ask only if a blocking ambiguity surfaces, exactly as the `build` Discuss. The user may ask to grill at any time.
 - **Never splits.** If the ticket turns out large, work it whole anyway: that is the point of `quick`. Do not `split` it and do not spin children. (New scope that surfaces mid-work is still captured out, never folded in, see **Scope that surfaces while working a ticket**, served by the capture cluster.)
 - **No map narrative book-keeping.** A whiteboard ticket has no map, so there is no `Decisions so far` update, no fog to graduate, no frontier re-scan. Everything else holds: atomic commits with `Refs: #<n>`, TDD / Code review / Acceptance testing per the cycle, the resolution comment + `gh issue close`, and the **Session handoff** (`../_shared/session-handoff.md`). **Exception, `quick <n>` on a *map* ticket: dependent-unblocking still runs** (remove `trailhead:blocked` from any dependent whose last blocker just closed, **Work the map** step 5 above); skipping it would strand those dependents off the frontier for good. Only the *narrative* book-keeping above and the split are skipped, so prefer `work <n>` for a map ticket that has dependents or belongs in the map record.
-- **Same isolation setup as `work`.** `quick` **writes the `.trailhead/session-ticket` marker at the working root in every isolation mode** (exactly as **Work the map** step 2, so tooling like the statusline shows what's in play; no active-map marker, though: a whiteboard ticket has no map). Under `auto` it runs the same work-start concurrency ask **before any edit** and resolves to current-checkout / worktree / clone by the same rule; under an explicit `isolation: worktree`/`clone` it sets up the ticket's `trailhead/t<n>` workspace before any edit (including the submodule-forces-`clone` escalation and submodule provisioning) and re-checks the claim; under `isolation: none` (or `auto` answered no), the scope-free check applies too. `quick` also runs the same commit-msg hook sync at the working root, exactly as **Work the map** step 2.
+- **Same isolation setup as `work`.** `quick` **writes the `.trailhead/session-ticket` marker at the working root in every isolation mode** (exactly as **Work the map** step 2, so tooling like the statusline shows what's in play; the active-map marker follows the same rule as `work`: a named ticket's map becomes the active map, a whiteboard ticket leaves it alone, see **Active map** in `../_shared/multi-map.md`). Under `auto` it runs the same work-start concurrency ask **before any edit** and resolves to current-checkout / worktree / clone by the same rule; under an explicit `isolation: worktree`/`clone` it sets up the ticket's `trailhead/t<n>` workspace before any edit (including the submodule-forces-`clone` escalation and submodule provisioning) and re-checks the claim; under `isolation: none` (or `auto` answered no), the scope-free check applies too. `quick` also runs the same commit-msg hook sync at the working root, exactly as **Work the map** step 2. It also writes the work state last, exactly as **Work the map** step 2, with `--map none` for a whiteboard ticket.
 - **Refreshes the dashboard at the handoff, not mid-work.** A `quick "<text>"` whiteboard ticket is born and resolved in the **same** session, so its dashboard refresh rides with the session's end, not with ticket creation: **do not refresh right after the ticket exists** (that lands a structural pinned-issue write ahead of the work `quick` exists to just-get-done, and only duplicates the resolution refresh a moment later). Refresh at **Resolve** (the handoff), as a **full regeneration from the live tracker** (never a partial patch that leaves other sections knowingly stale), so the whiteboard ticket lands on the dashboard as the session closes. **If the session pauses before Resolve** (`/trailhead:pause`), refresh there instead, so a deliberately-unfinished quick still shows (the read-only renders never rewrite the dashboard body, so nothing else would surface it). `quick <n>` on a *map* ticket does **not** refresh (map ticket progress shows via the native bar). See **The dashboard** and its freshness rule in `../_shared/substrate.md`.
 - **Always size-triages, independent of `config.effort`.** `quick` is the home of the cost-aware path: reaching for `quick` is itself the signal the piece is small, so it runs the **same size triage and ask-to-skip offer defined canonically under effort in `../_shared/configuration-reference.md`** (the same one the `build`/`bug` engine runs, `references/ticket-engines.md`) **every time, at the start before planning, whatever `config.effort` is set to**. `quick` does not wait for `effort: lean`, and an explicit `effort: standard` does not suppress it: `effort` governs `work` / the map cycle, not `quick`. On a trivial/small ticket it surfaces the one consolidated offer (the plan pass, TDD, cross-AI review, the full code review, the goal-backward verify) and goes lean **only on an explicit yes**; on a large ticket there is no offer and the full cycle runs. The correctness spine (atomic `Refs:` commits, tests/criterion, post-commit self-check, Resolve) is never in the offer, whatever the size or the answer.
 

package/plugins/trailhead/skills/trailhead-work/references/auto.md

@@ -53,4 +53,6 @@ Whatever ends the run (frontier drained or human interrupt), auto emits **one ru
 - **what resolved** (the tickets auto closed this run);
 - **what remains**: the **set-aside** tickets (fog, `decision` convergences, out-of-scope rulings, HITL `task` checklists, human-only UAT steps, and rail actions including any **ready-to-integrate branch / PR** under `git: pr`) and **why each needs the human**, the **paused / stuck** tickets from the failure budget, and any **blocked dependents** still waiting.
 
+Before handing back, if a work state file remains (an interrupted or paused ticket), run `node <templates>/trailhead-work-state.js set --repo <working-root> --auto false`. During the run every work-state `set` adds `--auto true --auto-done <n>`, `n` being the tickets resolved so far in this run (`autoDone` in the file).
+
 Then hand back to the human with the normal session handoff framing (`../../_shared/session-handoff.md`): the human decides what to take next (dissolve fog, make a held decision, authorise a rail action, then re-invoke `/trailhead:auto` to drain more).