@ericrisco/rsc 3.0.7 → 3.0.8

package/targets/claude.js

@@ -115,6 +115,9 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // Shared by session-start + userprompt-gate. Hooks are materialized file by file, so a module
   // they import must be copied as their SIBLING — a subdirectory import would break once copied.
   copyFileSync(join(HERE, 'hook-once.mjs'), join(paths.projectRoot, '.rsc', 'hook-once.mjs'));
+  // Shared by every PreToolUse guard (and the sello): what a Bash command really runs, `bash -c` and
+  // `eval` unwrapped. A sibling for the same reason, and here because the danger guard needs it too.
+  copyFileSync(join(HERE, 'shell-unwrap.mjs'), join(paths.projectRoot, '.rsc', 'shell-unwrap.mjs'));
   // Same reason: session-start imports the reaper for the landed-worktree sweep, so it travels as a
   // sibling too. Missing it does not break startup — the sweep is wrapped — it just goes silent.
   copyFileSync(join(HERE, 'worktree-reaper.mjs'), join(paths.projectRoot, '.rsc', 'worktree-reaper.mjs'));
@@ -132,7 +135,12 @@ export function wireHook(paths, sourceMd, policy = {}) {
 
   let suggestRel = at(relative(paths.projectRoot, paths.skillDir('suggest')).split(sep).join('/'), 'SKILL.md');
   const operationsSuggest = join(paths.projectRoot, '.rsc', 'suggest-always-on.md');
-  if (policy.codeHooks === false) {
+  // The lane decision (FTD or SDD) belongs to every SOFTWARE project, small ones included. Tying it to
+  // the code gates was the cause behind the E2E of 2026-10-07: a small project got a three-line stub
+  // with no lanes in it, no per-turn gate, and so never wrote a feature document. Plans from before
+  // the field keep their old meaning (`laneGate` follows `codeHooks`) until onboard runs again.
+  const laneGate = policy.laneGate ?? policy.codeHooks !== false;
+  if (policy.codeHooks === false && !laneGate) {
     writeFileSync(operationsSuggest, '# rsc-suggest — always-on operations layer\n\nRead `02-DOCS/wiki/harness/user-profile.md` before acting. Use `orient` to keep the user situated and `suggest` to offer a missing skill only when the current task needs it. Close with the configured orientation block.\n');
     suggestRel = at('.rsc', 'suggest-always-on.md');
   } else if (existsSync(operationsSuggest)) rmSync(operationsSuggest, { force: true });
@@ -237,16 +245,38 @@ export function wireHook(paths, sourceMd, policy = {}) {
       settings.hooks[event] = settings.hooks[event].filter((entry) => {
         const body = hookWiringOf(entry);
         return !body.includes('.rsc/ship-guard.') && !body.includes('.rsc/branch-guard.') &&
-          !body.includes('.rsc/gitmoji-guard.') && !body.includes('.rsc/userprompt-gate.');
+          !body.includes('.rsc/gitmoji-guard.') && (laneGate || !body.includes('.rsc/userprompt-gate.'));
       });
       if (!settings.hooks[event].length) delete settings.hooks[event];
     }
-    for (const name of ['ship-guard.mjs', 'branch-guard.mjs', 'trunk-policy.mjs', 'gitmoji-guard.mjs', 'userprompt-gate.mjs', 'sello.mjs']) {
-      rmSync(join(paths.projectRoot, '.rsc', name), { force: true });
-    }
-    written.push(operationsSuggest);
+    const gone = ['ship-guard.mjs', 'branch-guard.mjs', 'gitmoji-guard.mjs', 'sello.mjs', ...(laneGate ? [] : ['trunk-policy.mjs', 'userprompt-gate.mjs'])];
+    for (const name of gone) rmSync(join(paths.projectRoot, '.rsc', name), { force: true });
+    if (laneGate) {
+      // Same per-turn gate as a governed project: the lane, and where code changes go here.
+      const fgDest = join(paths.projectRoot, '.rsc', 'userprompt-gate.mjs');
+      copyFileSync(join(HERE, 'userprompt-gate.mjs'), fgDest);
+      copyFileSync(join(HERE, 'trunk-policy.mjs'), join(paths.projectRoot, '.rsc', 'trunk-policy.mjs'));
+      const fgCmd = viaBootstrap('quiet', at('.rsc', 'userprompt-gate.mjs'), `"${P}"`);
+      settings.hooks.UserPromptSubmit ||= [];
+      settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter((e) => !hookWiringOf(e).includes('.rsc/userprompt-gate.'));
+      settings.hooks.UserPromptSubmit.push({ hooks: [{ type: 'command', command: fgCmd }] });
+      written.push(fgDest, join(paths.projectRoot, '.rsc', 'trunk-policy.mjs'));
+    } else written.push(operationsSuggest);
   }
 
+  // FTD nudge: once per session, right after the first code edit with no feature document touched.
+  // Wherever the lane decision is installed; context only, never blocks; .rsc/.no-ftd-nudge.
+  settings.hooks.PostToolUse ||= [];
+  settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter((e) => !hookWiringOf(e).includes('.rsc/ftd-nudge.'));
+  if (laneGate) {
+    const fnDest = join(paths.projectRoot, '.rsc', 'ftd-nudge.mjs');
+    copyFileSync(join(HERE, 'ftd-nudge.mjs'), fnDest);
+    const fnCmd = viaBootstrap('quiet', at('.rsc', 'ftd-nudge.mjs'), `"${P}"`);
+    settings.hooks.PostToolUse.push({ matcher: 'Edit|Write|MultiEdit|NotebookEdit', hooks: [{ type: 'command', command: fnCmd }] });
+    written.push(fnDest);
+  } else rmSync(join(paths.projectRoot, '.rsc', 'ftd-nudge.mjs'), { force: true });
+  if (!settings.hooks.PostToolUse.length) delete settings.hooks.PostToolUse;
+
   // Danger guard: its own decision, not part of the code-hook block above (#273). `init` promises it
   // to non-technical and mixed users whatever the project is, and a plan that predates the field is
   // read as "yes": a non-technical operations install gets the guard it was missing on its next sync,

package/targets/clone-bootstrap.mjs

@@ -43,7 +43,7 @@ const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9a-z.-]+)?$/i;
  * nothing checks is just drift with a head start.
  */
 export const PROJECT_OPT_OUTS = [
-  'audit', 'auto-update', 'claudemd-check', 'danger-guard', 'feature-gate', 'gitmoji', 'knowledge-sync', 'ship-guard', 'trunk-guard', 'trunk-open', 'worktree-cleanup', 'worktree-isolation',
+  'audit', 'auto-update', 'claudemd-check', 'danger-guard', 'feature-gate', 'ftd-nudge', 'gitmoji', 'knowledge-sync', 'ship-guard', 'trunk-guard', 'trunk-open', 'worktree-cleanup', 'worktree-isolation',
 ];
 
 /**

package/targets/danger-guard.mjs

@@ -5,8 +5,14 @@
 //
 // For a NON-TECHNICAL user (per 02-DOCS/wiki/harness/user-profile.md → technical_level),
 // it DENIES irreversible, foot-gun Bash commands and tells the agent to find a safer,
-// scoped alternative. A fully `technical` user is never guarded. Default-safe: if there
-// is no profile yet, the harness convention is "assume non-technical", so the guard is ON.
+// scoped alternative. Default-safe: if there is no profile yet, the harness convention is
+// "assume non-technical", so the guard is ON.
+//
+// A `technical` user used to get nothing at all, and the E2E of 2026-10-07 showed what that means:
+// a small project with `main` open had no guard whatsoever, and `git reset --hard` would have wiped
+// uncommitted work with only the model's judgment in the way. So a technical user now gets the
+// short list of commands that destroy WORK OR SHARED HISTORY with no undo, as an `ask`: Claude Code
+// stops and the person confirms. Never a deny — a technical person who wants it gets it in one click.
 //
 // Disable per project with .rsc/.no-danger-guard — but only when the USER explicitly asks
 // for it (the deny message says so). Fail-open on any internal error (never brick a shell).
@@ -16,6 +22,16 @@ import { join } from 'node:path';
 const root = process.argv[2] || process.cwd();
 
 function allow() { process.exit(0); }
+function ask(why) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'ask',
+      permissionDecisionReason: `rsc: this command ${why}. It cannot be undone, so the person confirms it.`,
+    },
+  }));
+  process.exit(0);
+}
 function deny(why) {
   process.stdout.write(JSON.stringify({
     hookSpecificOutput: {
@@ -23,8 +39,9 @@ function deny(why) {
       permissionDecision: 'deny',
       permissionDecisionReason:
         `BLOCKED for a non-technical user — this command ${why}. ` +
-        `Do NOT run it: explain the risk in plain language and propose a safer, scoped alternative ` +
-        `(name exact paths, add a WHERE clause, back up first, etc.). ` +
+        `Do NOT run it, and do NOT reach the same result another way (a softer reset plus a delete is the ` +
+        `same loss). Explain the risk in plain language, let the person decide, and propose a safer, scoped ` +
+        `alternative that keeps their work (name exact paths, add a WHERE clause, back up first, etc.). ` +
         `Only if the USER explicitly insists on allowing dangerous commands here, create .rsc/.no-danger-guard to disable this guard.`,
     },
   }));
@@ -34,14 +51,22 @@ function deny(why) {
 if (existsSync(join(root, '.rsc', '.no-danger-guard'))) allow();
 
 // technical_level === 'technical' → not guarded. non-technical / mixed / missing → guarded.
+// The person's own profile first. It is personal and kept out of commits, so a teammate's clone has
+// none — and falling straight to "non-technical" turned every clone into a wall of denials (field
+// test 3.0.8). Next comes the level the harness was installed with, recorded in `.rsc.json`, which
+// the team commits. Only with neither is the safe default applied.
 function technicalLevel() {
   try {
     const txt = readFileSync(join(root, '02-DOCS', 'wiki', 'harness', 'user-profile.md'), 'utf8');
     const m = txt.match(/technical_level:\s*([a-z-]+)/i);
-    return m ? m[1].toLowerCase() : null;
+    if (m) return m[1].toLowerCase();
+  } catch { /* no profile here */ }
+  try {
+    const level = JSON.parse(readFileSync(join(root, '.rsc.json'), 'utf8'))?.onboarding?.plan?.record?.technicalLevel;
+    return typeof level === 'string' ? level.toLowerCase() : null;
   } catch { return null; }
 }
-if (technicalLevel() === 'technical') allow();
+const technical = technicalLevel() === 'technical';
 
 // Only Bash commands can be dangerous here.
 let input = {};
@@ -84,7 +109,9 @@ const SHELLS = /^(bash|sh|zsh|dash|ksh)$/i;
 // this, `echo "never run rm -rf /"` was denied — the guard blocking the conversation about a
 // command instead of the command, exactly the defect the gitmoji guard had to fix with its own
 // RUNS_GIT check. A guard that argues with you about a sentence is a guard you turn off.
-function runsRm(segment) {
+function runsRm(segment) { return runs(segment, 'rm'); }
+
+function runs(segment, bin) {
   const tokens = segment.trim().split(/\s+/).filter(Boolean);
   let i = 0;
   while (i < tokens.length) {
@@ -95,14 +122,28 @@ function runsRm(segment) {
       while (i < tokens.length && /^-/.test(tokens[i])) i += 1; // skip -c and friends
       continue;
     }
-    return bare === 'rm' || bare.endsWith('/rm');
+    return bare === bin || bare.endsWith(`/${bin}`);
   }
   return false;
 }
 
+// The shared unwrapper (E2E defect 15) adds the segments the shell really runs — `eval "rm …"`,
+// `exec rm …`, `FOO=1 rm …`, a `cd x && rm …` inside `bash -c` — on top of the plain split, so it
+// can only ever see MORE, never fewer. Sibling import under `.rsc/`; without it, as before.
+const SH = await import(new URL('./shell-unwrap.mjs', import.meta.url)).catch(() => null);
+const runSegments = () => {
+  const unwrapped = (() => { try { return SH ? SH.expand(cmd) : []; } catch { return []; } })();
+  return [...cmd.split(/\|\||&&|[|;&]/), ...unwrapped];
+};
+
+// A git rule judges the segment that RUNS git, so `echo 'git reset --hard'` is a sentence, not a reset.
+function gitSegment(re) {
+  return runSegments().some((segment) => runs(segment, 'git') && re.test(segment));
+}
+
 function isRmRecursiveForce() {
   if (!/\brm\b/.test(cmd)) return false;
-  for (const segment of cmd.split(/\|\||&&|[|;&]/)) {
+  for (const segment of runSegments()) {
     if (!runsRm(segment)) continue;
     const flags = rmFlagsIn(segment);
     const hasR = flags.some((f) => /^--recursive$/i.test(f) || /^-[A-Za-z]*r/i.test(f));
@@ -112,6 +153,9 @@ function isRmRecursiveForce() {
   return false;
 }
 
+// `git push`, with global options allowed before the subcommand (`git -C . push`, `git -c k=v push`).
+const GIT_PUSH = String.raw`\bgit\s+(?:(?:-[Cc]\s+\S+|--\S+)\s+)*push\b`;
+
 const RULES = [
   { id: 'rm-rf', why: 'deletes whole files/folders irreversibly (rm with -r and -f)', match: isRmRecursiveForce },
   { id: 'find-delete', why: 'mass-deletes matched files (find … -delete / -exec rm)', match: () => /\bfind\b[^|;&]*(-delete\b|-exec\s+rm\b)/i.test(cmd) },
@@ -119,10 +163,17 @@ const RULES = [
   { id: 'mkfs', why: 'formats a filesystem, erasing everything on it (mkfs)', match: () => /\bmkfs(\.\w+)?\b/i.test(cmd) },
   { id: 'curl-pipe-shell', why: 'pipes a downloaded script straight into a shell (curl|bash) — runs untrusted code', match: () => /\b(curl|wget)\b[^|]*\|\s*(sudo\s+)?(sh|bash|zsh)\b/i.test(cmd) },
 
-  { id: 'git-push-force', why: 'force-pushes and can overwrite shared history for everyone (git push --force)', match: () => /\bgit\s+push\b[^|;&]*(--force(?!-with-lease)\b|\s-f\b)/i.test(cmd) },
-  { id: 'git-reset-hard', why: 'throws away all uncommitted work with no undo (git reset --hard)', match: () => /\bgit\s+reset\b[^|;&]*--hard\b/i.test(cmd) },
-  { id: 'git-clean', why: 'permanently deletes untracked files (git clean -f)', match: () => /\bgit\s+clean\b[^|;&]*-[a-z]*f/i.test(cmd) },
-  { id: 'git-branch-D', why: 'force-deletes a branch even if its work was never merged (git branch -D)', match: () => /\bgit\s+branch\b[^|;&]*\s-D\b/.test(cmd) },
+  // A `+` in front of a refspec forces that ref exactly like the flag (team simulation D7).
+  { id: 'git-push-force', why: 'force-pushes and can overwrite shared history for everyone (git push --force, or a +refspec)', match: () => gitSegment(new RegExp(String.raw`${GIT_PUSH}[^|;&]*(--force(?!-with-lease)\b|\s-f\b|\s\+[^\s+])`, 'i')) },
+  // The "safer" force: it refuses only when the remote moved since the last fetch, and a fetch that
+  // already happened (an IDE, an earlier pull) satisfies it. What it rewrites is still history the
+  // team may have pulled, so it is asked / denied like the plain flag (team simulation D7).
+  { id: 'git-push-lease', why: 'force-pushes with a lease and still rewrites history the team may have pulled (git push --force-with-lease)', match: () => gitSegment(new RegExp(String.raw`${GIT_PUSH}[^|;&]*--force-with-lease\b`, 'i')) },
+  { id: 'git-reset-hard', why: 'throws away uncommitted work, and drops commits when it moves back, with no undo (git reset --hard)', match: () => gitSegment(/\bgit\s+reset\b[^|;&]*--hard\b/i) },
+  { id: 'git-clean', why: 'permanently deletes untracked files (git clean -f)', match: () => gitSegment(/\bgit\s+clean\b[^|;&]*-[a-z]*f/i) },
+  { id: 'git-discard', why: 'discards every uncommitted change in the tree with no undo (git checkout -- . / git restore .)', match: () => gitSegment(/\bgit\s+(checkout\s+(--\s+)?\.|restore\s+(--(staged|worktree)\s+)*\.)(\s|$|[|;&])/i) },
+  { id: 'git-no-verify', why: 'skips the project\'s own git hooks (--no-verify)', match: () => gitSegment(/\bgit\s+(commit|push|merge|rebase|am|cherry-pick)\b.*\s--no-verify\b/i) },
+  { id: 'git-branch-D', why: 'force-deletes a branch even if its work was never merged (git branch -D)', match: () => gitSegment(/\bgit\s+branch\b[^|;&]*\s-D\b/) },
 
   { id: 'sql-drop', why: 'drops an entire database/schema/table (DROP …)', match: () => /\bdrop\s+(database|schema|table)\b/i.test(cmd) },
   { id: 'sql-truncate', why: 'empties an entire table (TRUNCATE)', match: () => /\btruncate\s+(table\s+)?\S/i.test(cmd) },
@@ -131,8 +182,23 @@ const RULES = [
   { id: 'mongo-wipe', why: 'drops a collection/database or deletes all documents (drop()/dropDatabase/deleteMany({}))', match: () => /\.drop\(\s*\)|dropdatabase\s*\(|deletemany\(\s*\{\s*\}\s*\)|\.remove\(\s*\{\s*\}\s*\)/i.test(cmd) },
 ];
 
+// What a technical person is asked about: work or shared history gone with no undo. Everything else
+// on the list (a scoped rm -rf, SQL, curl|bash) is ordinary for them and stays silent (P7).
+const FOR_EVERYONE = new Set(['git-push-force', 'git-push-lease','git-reset-hard', 'git-clean', 'git-discard', 'git-no-verify', 'git-branch-D', 'dd-disk', 'mkfs', 'rm-rf-root']);
+
+// rm -rf aimed at the project itself, the home or the filesystem root is a wipe for anybody.
+function isRmRfRoot() {
+  if (!isRmRecursiveForce()) return false;
+  return /\brm\b[^|;&]*\s(\/|~\/?|\$HOME\/?|\.\/?|\.\.\/?|\*|\.git\/?)(\s|$|[|;&])/.test(cmd);
+}
+RULES.push({ id: 'rm-rf-root', why: 'recursively deletes the project, the home folder or the filesystem root', match: isRmRfRoot });
+
 for (const rule of RULES) {
-  try { if (rule.match()) deny(rule.why); } catch { /* a rule erroring must never block */ }
+  try {
+    if (!rule.match()) continue;
+    if (!technical) deny(rule.why);
+    if (FOR_EVERYONE.has(rule.id)) ask(rule.why);
+  } catch { /* a rule erroring must never block */ }
 }
 
 allow();

package/targets/ftd-nudge.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// rsc FTD nudge (claude). PostToolUse on Edit|Write|MultiEdit|NotebookEdit.
+//   argv[2] = absolute project root   stdin = PostToolUse hook JSON
+//
+// The lane rule ("simple → FTD: one feature document before the first change") lived only in prose,
+// and the E2E of 2026-10-07 measured what prose gets: five sessions of code changes, zero feature
+// documents, zero skill calls. Prose asks; this decides the one observable thing — code is being
+// changed and no feature document has been touched in this session — and says so ONCE per session,
+// right after the first code edit, when it is still cheap to write the document.
+//
+// A session is "documented" the moment any edit touches 02-DOCS/wiki/ftd/ or 02-DOCS/wiki/sdd/.
+// Docs, wiki, harness files and markdown are never "code". Never blocks: context only.
+// Paths inside `.worktrees/<branch>/` are classified as that worktree sees them, and a branch whose
+// own commits already touch a feature document counts as documented.
+// Off for a project with .rsc/.no-ftd-nudge. Fail-open on every error.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const STATE = ['.rsc', 'memory', 'ftd-nudge.json'];
+const KEEP = 50;
+
+export const NUDGE = 'rsc · lane: this session is changing code and has no feature document yet. ' +
+  'Before going on, decide the lane and say it in one line: simple → write 02-DOCS/wiki/ftd/<slug>.md now ' +
+  '(Intent, Scope, Checklist with how each item is proven, Evidence, Next) — one document per feature, ' +
+  'a box ticked only with its observed proof under Evidence, Next kept current; big or ' +
+  'interlocking → SDD (spec first). A one-line, zero-risk change needs no document: say so instead.';
+
+const posix = (p) => p.split(sep).join('/');
+
+// `.worktrees/<branch>/rest` → { worktree: '.worktrees/<branch>', rest }. A branch may hold slashes
+// (`feat/busqueda` lives two levels down), so the worktree is the deepest prefix with a `.git` entry
+// on disk; with nothing on disk to ask, the first segment is the branch.
+function splitWorktree(root, rel) {
+  const parts = rel.split('/');
+  if (parts[0] !== '.worktrees' || parts.length < 3) return null;
+  for (let end = parts.length - 1; end >= 2; end -= 1) {
+    if (existsSync(join(root, ...parts.slice(0, end), '.git'))) return { worktree: parts.slice(0, end).join('/'), rest: parts.slice(end).join('/') };
+  }
+  return { worktree: parts.slice(0, 2).join('/'), rest: parts.slice(2).join('/') };
+}
+
+export function classify(root, filePath) {
+  if (!filePath || typeof filePath !== 'string') return 'other';
+  let rel = posix(isAbsolute(filePath) ? relative(root, filePath) : filePath);
+  if (rel.startsWith('..')) return 'other';
+  // A session isolated in `.worktrees/<branch>/` edits the same project; classify what it edits as
+  // that worktree sees it. Every path there used to read as "other", so the isolated sessions — the
+  // whole team workflow — were never nudged (team simulation D11).
+  const nested = splitWorktree(root, rel);
+  if (nested) rel = nested.rest;
+  if (/^02-DOCS\/wiki\/(ftd|sdd)\//.test(rel)) return 'document';
+  if (/^(02-DOCS|01-TOOLS|\.rsc|\.claude|\.git|\.github|\.worktrees)\//.test(rel)) return 'other';
+  if (/\.(md|mdx|txt|rst)$/i.test(rel)) return 'other';
+  return 'code';
+}
+
+function readState(root) {
+  try { return JSON.parse(readFileSync(join(root, ...STATE), 'utf8')); } catch { return {}; }
+}
+
+function writeState(root, state) {
+  const entries = Object.entries(state).sort((a, b) => (b[1].at || 0) - (a[1].at || 0)).slice(0, KEEP);
+  mkdirSync(join(root, '.rsc', 'memory'), { recursive: true });
+  writeFileSync(join(root, ...STATE), `${JSON.stringify(Object.fromEntries(entries))}\n`);
+}
+
+// The checkout the edited file belongs to: its worktree under `.worktrees/`, or the project itself.
+function checkoutOf(root, filePath) {
+  if (typeof filePath !== 'string') return root;
+  const rel = posix(isAbsolute(filePath) ? relative(root, filePath) : filePath);
+  const nested = rel.startsWith('..') ? null : splitWorktree(root, rel);
+  return nested ? join(root, ...nested.worktree.split('/')) : root;
+}
+
+function gitOut(cwd, args) {
+  const r = spawnSync('git', ['-C', cwd, ...args], { encoding: 'utf8', windowsHide: true, timeout: 5000 });
+  return r.status === 0 ? (r.stdout || '').trim() : null;
+}
+
+/**
+ * Is this branch already documented — does a commit of its own, not on the default branch, touch a
+ * feature document? Then the session is continuing documented work (resolving a merge conflict, a
+ * fix-up after review) and the nudge would ask for a document that exists (team simulation D11).
+ * Asked only at the moment of nudging, once per session. Any doubt answers "no": nudging once too
+ * often is the cheap mistake.
+ */
+export function branchHasFeatureDoc(checkout) {
+  try {
+    const head = gitOut(checkout, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+    if (!head) return false;
+    const remoteHead = gitOut(checkout, ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD']);
+    const trunk = [remoteHead, 'origin/main', 'origin/master', 'main', 'master']
+      .filter(Boolean)
+      .find((ref) => ref !== head && gitOut(checkout, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]) !== null);
+    if (!trunk) return false;
+    const touched = gitOut(checkout, ['log', '--format=', '--name-only', `${trunk}..HEAD`, '--', '02-DOCS/wiki/ftd/']);
+    return Boolean(touched && touched.split('\n').some((line) => /^02-DOCS\/wiki\/ftd\/[^/]+\.md$/.test(line.trim())));
+  } catch { return false; }
+}
+
+/** The decision, pure enough to test: returns the context to inject, or ''. */
+export function decide(root, input, now = Date.now()) {
+  if (existsSync(join(root, '.rsc', '.no-ftd-nudge'))) return '';
+  const session = String(input.session_id || input.sessionId || '');
+  if (!session) return '';
+  const tool = input.tool_input || input.toolInput || {};
+  const file = tool.file_path || tool.notebook_path || tool.path;
+  const kind = classify(root, file);
+  if (kind === 'other') return '';
+  const state = readState(root);
+  const entry = state[session] || {};
+  if (kind === 'document') {
+    if (!entry.documented) { state[session] = { ...entry, documented: true, at: now }; writeState(root, state); }
+    return '';
+  }
+  if (entry.documented || entry.nudged) return '';
+  if (branchHasFeatureDoc(checkoutOf(root, file))) {
+    state[session] = { ...entry, documented: true, at: now };
+    writeState(root, state);
+    return '';
+  }
+  state[session] = { ...entry, nudged: true, at: now };
+  writeState(root, state);
+  return NUDGE;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  try {
+    const root = process.argv[2] || process.cwd();
+    const input = JSON.parse(readFileSync(0, 'utf8') || '{}');
+    const text = decide(root, input);
+    if (text) process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text } }));
+  } catch { /* fail open */ }
+  process.exit(0);
+}

package/targets/gitmoji-guard.mjs

@@ -143,7 +143,11 @@ const HAS_INLINE_M = /(?:^|\s)(?:-[a-zA-Z]*m|--message)(?:=|\s|$)/;
 // `git` must be the command being RUN, not text inside someone else's argument —
 // otherwise `echo "git commit -m x"` or `grep "git commit -m"` gets denied, and a guard
 // that blocks the discussion of commits is exactly the kind that gets switched off.
-const RUNS_GIT = /^\s*(?:sudo\s+)?(?:[A-Za-z_][A-Za-z0-9_]*=\S*\s+)*git\b/;
+const RUNS_GIT = /^\s*(?:(?:sudo|env|command|exec|nohup)\s+|[A-Za-z_][A-Za-z0-9_]*=\S*\s+)*git\b/;
+
+// A commit handed to a shell as a string (`bash -c "git commit -m …"`, `eval …`) is read inside
+// that string (E2E defect 15). shell-unwrap.mjs is a sibling under `.rsc/`; without it, as before.
+const SH = await import(new URL('./shell-unwrap.mjs', import.meta.url)).catch(() => null);
 
 const SEPARATORS = /&&|\|\||[;\n]/;
 
@@ -174,6 +178,15 @@ function inlineMessage(segment) {
 export function commitMessages(command) {
   const cmd = String(command ?? '');
   if (!COMMIT.test(cmd)) return [];
+  const inner = SH ? SH.innerScripts(cmd) : [];
+  if (!inner.length) return directMessages(cmd);
+  // The wrapped strings are read on their own; the rest of the chain without them, so a commit is
+  // never read twice (once naively through the quotes, once unwrapped).
+  const rest = SH.segments(SH.withoutHeredocs(cmd)).filter((seg) => SH.unwrap(seg)?.inner === undefined).join('\n');
+  return [...directMessages(rest), ...inner.flatMap(commitMessages)];
+}
+
+function directMessages(cmd) {
 
   // The heredoc form must be handled before any splitting: its body is the message and
   // may legitimately contain && or ;. The command that owns it is whatever runs just