@ericrisco/rsc 3.0.6 → 3.0.8

package/scripts/rsc.js

@@ -4,12 +4,13 @@ import { detectTarget, installedTargets, resolveTargets, TARGETS } from '../targ
 import { detectRepo } from './detect-repo.js';
 import { rank } from './consult.js';
 import { expandRecommends, toOutcomes, hasOutcome } from './lib/recommend.js';
-import { applyInstall, listInstalled, listInstalledAgents, listInstalledCommands, uninstall, syncInstalled, purge, collisions, ownSkillPaths } from './install-apply.js';
+import { applyInstall, listInstalled, listInstalledAgents, listInstalledCommands, uninstall, syncInstalled, purgeReport, collisions, ownSkillPaths } from './install-apply.js';
+import { isAbsolute, relative, sep } from 'node:path';
 import { stackAgentNames } from '../targets/agents.js';
 import { doctor } from './doctor.js';
 import { ask, say, select, pickFrom, banner, confirm, isInteractive } from './lib/ui.js';
 import { refreshRegistry, registryStatus } from './lib/registry.js';
-import { audit, writeAuditReport } from './audit.js';
+import { audit, writeAuditReport, recordAuditBaseline } from './audit.js';
 import { DOMAINS } from './lib/domains.js';
 import { listBackups, restoreBackup, whereKept } from './lib/backups.js';
 import { runUpgrade } from './lib/upgrade.js';
@@ -18,6 +19,7 @@ import { DEFAULT_SKILL_FLOOR, withDefaultSkillFloor } from './lib/default-skill-
 import { RETIRED_SKILLS, replaceRetired } from './lib/retired-skills.js';
 import { readManifest, writeManifest } from './lib/manifest-file.js';
 import { versionReport } from './lib/versions.js';
+import { templateAssets, targetName } from './lib/tools-skeleton.js';
 import {
   normalizeOnboarding, missingOnboardingFields, scanProject,
   buildOnboardingPlan, decodeGoal, encodeGoal, identifyPlan, recommendDeferredComponents,
@@ -39,6 +41,33 @@ if (['--version', '-v', 'version'].includes(rawArgv[0])) {
   process.stdout.write(`${lines.join('\n')}\n`);
   process.exit(0);
 }
+const GENERAL_HELP = [
+  'Use: npx @ericrisco/rsc onboard | reassess | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | memory <on|off|status|save|resume|learn|metrics> | sello <on|off|status|…> | worktrees [reap [path] [--confirm]] | backups | restore <id|latest> | upgrade | repair | uninstall <id...> | purge | help',
+  'Any command takes --target <claude|codex|cursor|copilot|gemini|…> (comma-separate for several)',
+  '   → without it, rsc uses the assistant already installed here; if two are, it asks instead of guessing.',
+].join('\n');
+const UNINSTALL_HELP = [
+  'Use: npx @ericrisco/rsc uninstall <id...> [--dry-run] [--target <assistant>]',
+  '  Removes the named skills or agents from this project.',
+  '  To remove everything rsc installed here, run: npx @ericrisco/rsc purge  (keeps 02-DOCS/ unless --with-docs)',
+].join('\n');
+const PURGE_HELP = [
+  'Use: npx @ericrisco/rsc purge [--dry-run] [--with-docs]',
+  '  Removes everything rsc installed in this project and reports what was removed, cleaned and kept.',
+  '  --dry-run shows the report without touching anything. 02-DOCS/ is kept unless --with-docs.',
+].join('\n');
+
+// Asking for help must never RUN the command. `uninstall --help` used to be read as an empty id list
+// and report "Removed: (nothing)"; `purge --help` would have purged. Answered before anything else.
+{
+  const helpAsked = rawArgv.some((a) => a === '--help' || a === '-h');
+  if (rawArgv[0] === 'help' || helpAsked) {
+    const about = rawArgv[0] === 'help' ? rawArgv[1] : rawArgv.find((a) => !a.startsWith('-'));
+    const text = about === 'uninstall' ? UNINSTALL_HELP : about === 'purge' ? PURGE_HELP : GENERAL_HELP;
+    process.stdout.write(`${text}\n`);
+    process.exit(0);
+  }
+}
 // `--accompaniment` stays listed although the dial is retired: old scripts and agents still pass it,
 // and its value must keep being skipped rather than read as a command or a skill id.
 const GLOBAL_VALUE_FLAGS = new Set([
@@ -159,6 +188,12 @@ function renderPlan(plan, planId) {
   for (const decision of plan.decisions.filter((d) => d.state === 'excluded')) say(`  × ${decision.kind}/${decision.id} — ${decision.reason}`);
   say('Managed paths:');
   for (const path of plan.governedPaths) say(`  ${path}`);
+  // The scaffolding is written once and then belongs to the person, so it is not a managed (digested)
+  // path — but it IS written by this plan, and a plan that does not show it is not the whole plan.
+  if ((plan.floorPaths || []).includes('01-TOOLS/_TEMPLATE/')) {
+    say('Scaffolded once (yours to edit; never overwritten; purge removes only untouched files):');
+    for (const path of ['01-TOOLS/.gitignore', ...templateAssets().map((a) => `01-TOOLS/_TEMPLATE/${targetName(a)}`)].sort()) say(`  ${path}`);
+  }
   if (plan.replacesUserSkills?.length) {
     say('Your own skills this plan replaces:');
     for (const path of plan.replacesUserSkills) say(`  ! ${path} — already here and not put by rsc; the catalog skill of the same name takes its place, and yours is kept in .rsc/backups/`);
@@ -166,8 +201,11 @@ function renderPlan(plan, planId) {
     say('  AGENT: name each of these to the user before accepting, and ask whether to replace or rename.');
   }
   if (plan.evidence.parentHarness) say(`Parent harness detected at ${plan.evidence.parentHarness}; it is not inherited by this plan.`);
+  // Pinned to the version that computed this plan. The id is a hash of the plan, and the plan
+  // depends on the catalog of the running version: `@latest` would accept it with whatever version
+  // npm resolves next, which answers RSC_PLAN_CHANGED the day a release lands in between.
   const pieces = [
-    'npx @ericrisco/rsc@latest onboard',
+    `npx @ericrisco/rsc@${versionReport(process.cwd()).cli} onboard`,
     `--technical-level ${plan.record.technicalLevel}`,
     `--project-kind ${plan.record.projectKind}`,
     `--goal-base64 ${encodeGoal(plan.record.goal)}`,
@@ -260,6 +298,9 @@ async function runOnboarding(targets) {
   } catch (error) {
     say(`RSC_SKELETON_FAILED ${error.message}`);
   }
+  // The audit cadence starts at install. Without a baseline the very first session after onboarding
+  // announced "a skill audit is due" about a set chosen minutes earlier. Never overwrites a real run.
+  try { recordAuditBaseline(process.cwd()); } catch { /* a missing baseline only means an early nudge */ }
   for (const path of plan.replacesUserSkills || []) {
     const kept = whereKept({ cwd: process.cwd(), relPath: path });
     if (kept) say(`Your previous ${path} is kept in ${kept}`);
@@ -370,10 +411,34 @@ function flag(name) {
 // Remove everything rsc installed in this project (skills, hooks, .rsc/), across
 // every assistant. Keeps 02-DOCS/ unless --with-docs. `purge` / `uninstall --all`.
 async function runPurge(dryRun, withDocs) {
-  const removed = await purge({ cwd: process.cwd(), withDocs, dryRun });
-  say(`${dryRun ? 'Would remove' : 'Removed'} ${removed.length} path(s):`);
-  for (const r of removed) say(`  - ${r}`);
-  if (!withDocs) say('\nKept 02-DOCS/ (your knowledge base). Add --with-docs to remove it too.');
+  const cwd = process.cwd();
+  const report = await purgeReport({ cwd, withDocs, dryRun });
+  // Relative to the project: the report is read by a person, and every path is inside it.
+  const shown = (p) => {
+    const rel = relative(cwd, p);
+    return !rel || rel.startsWith('..') || isAbsolute(rel) ? p : rel.split(sep).join('/');
+  };
+  say(`${dryRun ? 'Would remove' : 'Removed'} ${report.removed.length} path(s):`);
+  for (const r of report.removed.map(shown).sort()) say(`  - ${r}`);
+  if (report.cleaned.length) {
+    say(`\n${dryRun ? 'Would clean' : 'Cleaned'} ${report.cleaned.length} file(s) — rsc's entries ${dryRun ? 'would be' : 'were'} taken out; ${dryRun ? 'each is deleted if nothing of yours remains' : 'the rest of the file is yours and stays'}:`);
+    for (const c of report.cleaned.map(shown).sort()) say(`  - ${c}`);
+  }
+  if (report.kept.length) {
+    say(`\nKept ${report.kept.length}:`);
+    for (const k of report.kept) say(`  - ${k.path} — ${k.reason}`);
+  }
+  // On a clone most of what purge deletes is committed. Deleting it here is local; committing the
+  // deletions uninstalls rsc for the whole team (team simulation D15). Said before anyone commits.
+  if (report.tracked?.length) {
+    const quote = (p) => (/^[\w./@+-]+$/.test(p) ? p : `'${p.replace(/'/g, `'\\''`)}'`);
+    say(`\nWARNING: ${report.tracked.length} of these file(s) are committed in git and ${dryRun ? 'would show' : 'now show'} as deleted or changed:`);
+    for (const f of report.tracked.slice(0, 12)) say(`  - ${f}`);
+    if (report.tracked.length > 12) say(`  … and ${report.tracked.length - 12} more`);
+    say('Committing these changes uninstalls rsc for the whole team, on their next pull. To remove rsc only on this machine, do not commit them.');
+    if (!dryRun) say(`To undo locally: git restore -- ${report.tracked.map(quote).join(' ')}`);
+    else say('To undo after a real purge: git restore -- <those files> (purge prints the exact command).');
+  }
 }
 
 async function recommendIds(query, { labeledOnly = false } = {}) {
@@ -450,6 +515,7 @@ function printNextSteps(targets, ids) {
   say('   Browse the catalog / get picks:   npx @ericrisco/rsc consult "whatever you need"');
   say('────────────────────────────────────────────────────────');
   if (targets.includes('codex')) say('   Codex: review and trust the project lifecycle hook once with `/hooks`; until then memory is reported as requiring trust.');
+  if (targets.includes('deepseek')) say('   DeepSeek Harness: hooks run through rsc\'s bridge in ~/.dsh/cordis.patch.yml (one block, every profile); restart dsh once to load it.');
   if (targets.includes('cursor')) say('   Cursor: startup memory is assisted because its sessionStart hook is fire-and-forget; the installed always-on rule performs the read-before-action fallback.');
   printAgentHandoff();
 }
@@ -514,7 +580,7 @@ function printContextBudget(b) {
   if (b.notApplicable.length) {
     say(`  ${b.note}`);
   } else {
-    say(`  Per session start : ${kb(b.sessionStartBytes)}   (always-on body, per wired scope)`);
+    say(`  Per session start : ${kb(b.sessionStartBytes)}   (always-on body, per wired scope; one-time and conditional banners not counted)`);
     say(`  Per user turn     : ${kb(b.perTurnBytes)}`);
   }
   say(`  Skill descriptions: ${kb(b.descriptionsBytes)}   (${b.installedSkills} installed, always in context)`);
@@ -1005,7 +1071,15 @@ async function main() {
         // defeated by an argument the sweep itself told the agent to type.
         const confirmed = argv.includes('--confirm');
         const targets = one ? [one] : candidates.filter((c) => c.verdict === 'safe').map((c) => c.path);
-        if (!targets.length) { say('nothing to clean up.'); return; }
+        // The bulk reap also deletes plain local branches that have landed (`branch -d`, never -D):
+        // the worktree is not the only thing a merge leaves behind (E2E defect 14).
+        const reapBranches = () => {
+          if (one) return 0;
+          const { deleted } = W.reapMergedBranches(root);
+          for (const b of deleted) say(`✅ deleted merged branch ${b}`);
+          return deleted.length;
+        };
+        if (!targets.length) { if (!reapBranches()) say('nothing to clean up.'); return; }
         for (const t of targets) {
           const out = W.reapWorktree(root, t, { confirmed });
           if (out.removed) {
@@ -1017,6 +1091,7 @@ async function main() {
             process.exitCode = 1;
           }
         }
+        reapBranches();
         return;
       }
 
@@ -1271,7 +1346,14 @@ async function main() {
       const dry = argv.includes('--dry-run');
       // `uninstall --all` is an alias for a full purge.
       if (argv.includes('--all')) return void (await runPurge(dry, argv.includes('--with-docs')));
-      const selected = classifyRequested(requestedIds());
+      const ids = requestedIds();
+      // No id is not "nothing to remove": it is a command that was not given what it needs.
+      if (!ids.length) {
+        console.error(`rsc: uninstall needs at least one skill or agent id.\n${UNINSTALL_HELP}`);
+        process.exitCode = 1;
+        return;
+      }
+      const selected = classifyRequested(ids);
       // A retired skill an old install still holds is not unknown: the state file proves it is ours.
       const held = new Set(listInstalled({ target }));
       selected.skills.push(...selected.unknown.filter((id) => Object.hasOwn(RETIRED_SKILLS, id) && held.has(id)));
@@ -1305,9 +1387,7 @@ async function main() {
       return void (await runPurge(argv.includes('--dry-run'), argv.includes('--with-docs')));
     default:
       say(`rsc: unknown command '${cmd}'.`);
-      say('Use: npx @ericrisco/rsc onboard | reassess | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | memory <on|off|status|save|resume|learn|metrics> | sello <on|off|status|…> | worktrees [reap [path] [--confirm]] | backups | restore <id|latest> | upgrade | repair | uninstall <id> | purge');
-      say('Any command takes --target <claude|codex|cursor|copilot|gemini|…> (comma-separate for several)');
-      say('   → without it, rsc uses the assistant already installed here; if two are, it asks instead of guessing.');
+      say(GENERAL_HELP);
       process.exitCode = 1;
   }
 }

package/skills/suggest/SKILL.md

@@ -106,12 +106,13 @@ Offer once per session. Never mention any of it when the harness is healthy.
 
 Before handling the first request of a session, check the workspace:
 
-- No `02-DOCS/wiki/harness/user-profile.md` **and** no `.rsc/.no-harness` → the harness has never
-  been set up here. Invoke `init` first; it opens with one question: technical terms or analogies.
-  Do not start the user's task before first contact is done.
+- No `02-DOCS/wiki/harness/user-profile.md` **and** no `.rsc/.no-harness` → invoke `init` first
+  (one question: technical terms or analogies) before the task.
+- A clone (`.rsc.json` committed) is not first contact: ask that once, in one line, then continue
+  with their task; with `.rsc/.profile-offered`, never again.
 - The user declines a harness here ("sin harness", "solo código") → create an empty
   `.rsc/.no-harness`, confirm in one line, and never auto-start `init` in this repo again.
-- Once the profile exists, this gate is inert. Never re-onboard.
+- With a profile, this gate is inert. Never re-onboard.
 
 ## Explain without assuming
 

package/targets/branch-guard.mjs

@@ -33,6 +33,29 @@ export const COMMITS_HERE = new RegExp(String.raw`\bgit\s+${GIT_OPTS}(?:commit|m
 // A branch move: switch, or checkout of something that is not a path (`checkout -- f`, `checkout HEAD -- f`).
 export const MOVES_BRANCH = new RegExp(String.raw`\bgit\s+${GIT_OPTS}(?:switch(?![\w-])|checkout(?![\w-])(?![^;&|\n]*\s--(?:\s|$)))`);
 
+// A move of a branch REF without a commit: `git update-ref <ref> …` or a forced `git branch`
+// (-f/--force, -M, -C). Which ref it moves is read by refMoveTarget().
+export const MOVES_REF = new RegExp(String.raw`\bgit\s+${GIT_OPTS}(?:update-ref(?![\w-])|branch\s+(?:\S+\s+)*?(?:-[A-Za-z]*[fMC][A-Za-z]*|--force)(?=\s|$))`);
+
+// A push whose DESTINATION is named: `git push origin HEAD:main`, `feat/x:refs/heads/main`, `--mirror`.
+export const PUSHES = new RegExp(String.raw`\bgit\s+${GIT_OPTS}push(?![\w-])`);
+
+/** True when this push segment writes to branch `trunk` on the remote by an explicit refspec. */
+export function pushesTo(seg, trunk) {
+  const t = tokens(seg.replace(/^.*?\bgit\s+/, '').replace(/^(?:(?:-C|-c)\s+\S+\s+|--\S+\s+)*/, ''));
+  if (t.shift() !== 'push') return false;
+  const args = [];
+  for (let i = 0; i < t.length; i++) {
+    if (t[i] === '--mirror') return true; // rewrites every ref on the remote, the default branch included
+    if (/^(-o|--push-option|--repo|--receive-pack|--exec)$/.test(t[i])) { i++; continue; }
+    if (!t[i].startsWith('-')) args.push(t[i]);
+  }
+  return args.slice(1).some((spec) => {
+    const dst = spec.replace(/^\+/, '').split(':')[1];
+    return dst !== undefined && dst.replace(/^refs\/heads\//, '') === trunk;
+  });
+}
+
 export const unquoted = (command) => command.replace(/"(?:[^"\\]|\\.)*"|'[^']*'/g, '""');
 
 /** Where the git command actually runs: `git -C <dir>`, or a leading `cd <dir> &&`, else the cwd. */
@@ -54,27 +77,10 @@ const ago = (iso) => {
   return min <= 1 ? 'just now' : `${min} min ago`;
 };
 
-/** Heredoc bodies are text being written, not commands: `cat > notes.md <<EOF … git commit … EOF`. */
-export const withoutHeredocs = (command) => command.replace(/<<-?\s*(['"]?)([A-Za-z_]\w*)\1[^\n]*\n[\s\S]*?\n\s*\2\s*(?=\n|$)/g, '');
-
-/** The command split where the shell would run one thing after another, never inside quotes. */
-export function segments(command) {
-  const out = [];
-  let cur = '';
-  let q = null;
-  for (let i = 0; i < command.length; i++) {
-    const c = command[i];
-    if (q) { cur += c; if (c === '\\' && q === '"') cur += command[++i] ?? ''; else if (c === q) q = null; continue; }
-    if (c === '"' || c === "'") { q = c; cur += c; continue; }
-    if (c === ';' || c === '\n' || c === '|' || c === '&') {
-      if ((c === '&' || c === '|') && command[i + 1] === c) i++;
-      out.push(cur); cur = ''; continue;
-    }
-    cur += c;
-  }
-  out.push(cur);
-  return out.filter((s) => s.trim());
-}
+// The quote-aware split, the heredoc strip and the shell unwrapping (`bash -c "…"`, `eval`, `env`…)
+// live in shell-unwrap.mjs, shared with the other guards (E2E defect 15). It is a sibling import
+// like trunk-policy.mjs; without it the guard cannot read a command and fails open.
+const SH = await import(new URL('./shell-unwrap.mjs', import.meta.url)).catch(() => null);
 const tokens = (s) => s.trim().split(/\s+/).filter(Boolean);
 
 /** What a branch-moving segment moves to, or null if it is a path checkout after all (`checkout .`). */
@@ -89,6 +95,31 @@ function moveTarget(seg, dir) {
   return { name, created: false };
 }
 
+/** The branch a ref-moving segment points somewhere else (`update-ref refs/heads/x`, `branch -f x`), or null. */
+export function refMoveTarget(seg) {
+  const t = tokens(seg.replace(/^.*?\bgit\s+/, '').replace(/^(?:(?:-C|-c)\s+\S+\s+|--\S+\s+)*/, ''));
+  const verb = t.shift();
+  if (verb === 'update-ref') {
+    const args = [];
+    for (let i = 0; i < t.length; i++) {
+      if (t[i] === '-m') { i++; continue; }
+      if (t[i] === '--stdin') return null; // refs come from stdin: unreadable here
+      if (!t[i].startsWith('-')) args.push(t[i]);
+    }
+    const m = (args[0] || '').match(/^refs\/heads\/(.+)$/);
+    return m ? m[1] : null;
+  }
+  if (verb !== 'branch') return null;
+  const flags = t.filter((x) => x.startsWith('-'));
+  const names = t.filter((x) => !x.startsWith('-'));
+  const short = flags.filter((f) => /^-[A-Za-z]+$/.test(f)).join('');
+  const renames = /[mMcC]/.test(short) || flags.some((f) => /^--(move|copy)$/.test(f));
+  const forced = /[fMC]/.test(short) || flags.includes('--force');
+  if (!forced || /[dD]/.test(short)) return null;
+  // `branch -M [old] new` / `-C [old] new`: the last name is the one overwritten; `-f name [start]`: the first.
+  return (renames ? names[names.length - 1] : names[0]) || null;
+}
+
 /**
  * Rule A and rule B, judged segment by segment: a chain is followed the way the shell runs it, so
  * `git switch -c feat/x && git commit` is a commit on feat/x (allowed) and `git switch main && git
@@ -96,12 +127,14 @@ function moveTarget(seg, dir) {
  */
 export async function evaluate({ root, command, cwd, sessionId }) {
   if (typeof command !== 'string' || !command) return null;
+  if (!SH) return null;
   // Words inside quotes or heredocs are text, not commands: `grep -rn "git commit" docs/` is a search.
-  const bare = unquoted(withoutHeredocs(command));
-  if (!COMMITS_HERE.test(bare) && !MOVES_BRANCH.test(bare)) return null;
-  const self = (rel) => new URL(rel, import.meta.url);
-  const raw = segments(withoutHeredocs(command));
+  // Except where a wrapper hands the string to a shell: `bash -c "git commit"` runs the commit, so
+  // the segments judged are the ones the shell would really run (shell-unwrap.mjs).
+  const raw = SH.expand(command);
   const segs = raw.map(unquoted);
+  if (!segs.some((s) => COMMITS_HERE.test(s) || MOVES_BRANCH.test(s) || MOVES_REF.test(s) || PUSHES.test(s))) return null;
+  const self = (rel) => new URL(rel, import.meta.url);
   let dir = cwd || root;
   const branchAt = new Map(); // toplevel → branch the chain has moved it to
 
@@ -111,7 +144,9 @@ export async function evaluate({ root, command, cwd, sessionId }) {
     if (cd) { const d = cd[1].replace(/^["']|["']$/g, ''); dir = isAbsolute(d) ? d : resolve(dir, d); continue; }
     const commits = COMMITS_HERE.test(seg);
     const moves = MOVES_BRANCH.test(seg);
-    if (!commits && !moves) continue;
+    const movesRef = MOVES_REF.test(seg);
+    const pushes = PUSHES.test(seg);
+    if (!commits && !moves && !movesRef && !pushes) continue;
     const at = effectiveDir(raw[i] || seg, dir);
     const git = gitAt(at);
     const top = git('rev-parse', '--show-toplevel');
@@ -129,6 +164,32 @@ export async function evaluate({ root, command, cwd, sessionId }) {
       }
     }
 
+    // Rule A, the other way onto the default branch: pointing it somewhere else without a commit.
+    if (movesRef && !existsSync(join(root, '.rsc', '.no-trunk-guard'))) {
+      try {
+        const { trunkPolicy, defaultBranchName } = await import(self('./trunk-policy.mjs'));
+        const trunk = defaultBranchName(here);
+        if (trunk && refMoveTarget(seg) === trunk) {
+          const policy = trunkPolicy(here);
+          if (policy.closed) return refDenial({ trunk, policy });
+        }
+      } catch { /* policy module missing → nothing to enforce */ }
+    }
+
+    // And by pushing straight into it: `git push origin HEAD:main` from a feature branch. Branch
+    // protection on the server would refuse it, but a repo without one would take it (second team
+    // simulation) — so the closed trunk is enforced here, where the agent runs it.
+    if (pushes && !existsSync(join(root, '.rsc', '.no-trunk-guard'))) {
+      try {
+        const { trunkPolicy, defaultBranchName } = await import(self('./trunk-policy.mjs'));
+        const trunk = defaultBranchName(here);
+        if (trunk && pushesTo(seg, trunk)) {
+          const policy = trunkPolicy(here);
+          if (policy.closed) return refDenial({ trunk, policy, how: '`git push <remote> <branch>:' + trunk + '`' });
+        }
+      } catch { /* policy module missing → nothing to enforce */ }
+    }
+
     if (commits && !existsSync(join(root, '.rsc', '.no-trunk-guard'))) {
       try {
         const { trunkPolicy, defaultBranchName } = await import(self('./trunk-policy.mjs'));
@@ -164,6 +225,13 @@ async function trunkDenial({ root, here, sessionId, self, trunk, policy }) {
     'Unlock → only on their explicit answer, `npx @ericrisco/rsc main unlock` (a project decision, saved in .rsc.json), then commit again.';
 }
 
+function refDenial({ trunk, policy, how = '`git update-ref` and a forced `git branch`' }) {
+  return `This project keeps its default branch "${trunk}" closed for the agent (it looks complex or in production: ${policy.signals.join(', ')}), so "${trunk}" was not moved — ` +
+    `${how} land${how.includes(' and ') ? '' : 's'} work on it with no review. ` +
+    `Work reaches "${trunk}" through a pull request: push the branch and open one (the \`ship\` skill). ` +
+    `Do not choose for the person: if they want "${trunk}" moved by hand, ask them in one line; only on their explicit answer, \`npx @ericrisco/rsc main unlock\` (a project decision, saved in .rsc.json).`;
+}
+
 async function isolationDenial({ root, here, sessionId, self }) {
   const others = await othersHere({ root, here, sessionId, self });
   if (!others.length) return null;

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',
 ];
 
 /**