@ericrisco/rsc 3.0.7 → 3.0.9

package/README.md

@@ -94,7 +94,7 @@ rsc 3.0 fixes all four, by default, with no new commands to learn:
 | **You choose how the project works** | The install asks once: straight on `main`, or branches and pull requests? Branches are recommended only for long-lived, complex code. With `main` the agent works on it and never asks about branches. With branches a commit on `main` is refused, and before each code change the agent asks: this branch, a new one, or unlock `main`? It never opens a branch on its own. | Say **«unlock main»** / **«lock main»**, or `rsc main unlock` / `lock` |
 | **One workspace per agent** | If another assistant session is working in the same folder, new work goes to a worktree under `.worktrees/<branch>/`. It stays inside the project, is never committed, and is removed once that branch is merged. | `rsc isolation off` |
 | **The agent picks the method** | A simple change takes Fast-Track (one document, proof for every task). Something big or complex takes the spec-driven chain. The agent decides and says why. You still approve *what* gets built: the spec and the clarifications, then step by step or autopilot. | Ask for the other lane |
-| **Knowledge reaches everyone** | `01-TOOLS/` and `02-DOCS/` travel through one exchange branch, `rsc/knowledge`. They go up when your turn ends and come down into whatever branch each person is on. They reach `main` inside your normal pull requests. | `rsc knowledge-sync off` |
+| **Knowledge reaches everyone** | `01-TOOLS/`, `02-DOCS/wiki/` and `02-DOCS/attachments/` travel through one exchange branch, `rsc/knowledge`. They go up when your turn ends and come down into whatever branch each person is on. They reach `main` inside your normal pull requests. | `rsc knowledge-sync off` |
 
 **Commit, push and pull request without a prompt each time.** A harness installed from scratch lets
 the agent run `git commit`, `git push` and `gh pr create` without asking, because those are the steps
@@ -372,7 +372,11 @@ That verdict is not just about the receipt: it also requires the harness floor t
 `01-TOOLS/_TEMPLATE/`, `02-DOCS/wiki/harness/`, and the constitution when the plan selects SDD.
 If the floor is missing, the install applied but prints `RSC_ONBOARDING_INCOMPLETE` with each
 missing path and the action that creates it, because a plan that promised little used to be able to
-report success with three markdown files.
+report success with three markdown files. When the plan selects SDD, onboarding writes the
+constitution itself as a draft (`status: draft`, only the facts it knows, no principles), so a
+non-interactive install still ends `RSC_ONBOARDING_READY`; the draft is listed as pending — under
+READY and in `rsc doctor` — until the `constitution` phase completes it. An existing constitution is
+never overwritten.
 
 ---
 
@@ -471,8 +475,10 @@ list somebody has to remember to update is a list that goes quietly stale. Decla
 
 ### Your wiki and tools stay in sync — on by default
 
-`01-TOOLS/` and `02-DOCS/` are the team's knowledge, so rsc keeps them the same on every machine
-without anybody thinking about git, **and without ever pushing to `main`**. Your `main` is
+`01-TOOLS/`, `02-DOCS/wiki/` and `02-DOCS/attachments/` are the team's knowledge, so rsc keeps them
+the same on every machine without anybody thinking about git, **and without ever pushing to `main`**.
+Exactly those three folders, minus rsc's own `01-TOOLS/_TEMPLATE/` and your personal
+`02-DOCS/wiki/harness/user-profile.md`. Your `main` is
 protected, or should be; rsc assumes it is.
 
 The knowledge travels through one exchange branch, `rsc/knowledge`, that nobody works on by hand:
@@ -484,13 +490,22 @@ main   · protected      untouched — gets it inside the next merged pull reque
 new    · clones main    has it all after the first message
 ```
 
-- **When a turn ends**, your changes in those folders are committed as `📝 docs(auto): … [skip ci]`
-  and sent to `rsc/knowledge` on `origin`, from whatever branch you are on. If you are on a closed
-  `main`, nothing is committed locally: the snapshot is built aside and only goes to `rsc/knowledge`.
-  Knowledge that you or the agent already **committed** on the branch during the turn goes up too —
-  only its `01-TOOLS/` and `02-DOCS/` part, under a `docs(auto) … [skip ci]` message.
-- **Before each message**, what teammates sent is brought into **the branch you are on**, and you are
-  told in one line. Only the knowledge folders are touched.
+- **When a turn ends**, your changes in those folders are committed on your branch as
+  `📝 docs(auto): …` and sent to `rsc/knowledge` on `origin`, from whatever branch you are on. Only
+  the copy on `rsc/knowledge` carries `[skip ci]`; the commit on your branch does not, so your next
+  ordinary push still runs CI. Two cases commit nothing on your branch: a closed `main`, and code of
+  yours still uncommitted (a docs commit would land ahead of the code it describes). Then the snapshot
+  is built aside, only goes to `rsc/knowledge`, and the files stay modified for you to commit with
+  your work. Knowledge that you or the agent already **committed** on the branch goes up too — only
+  its knowledge part, under a `docs(auto) … [skip ci]` message. Commits that came in by merging
+  `main` are your teammates', not yours, and are not sent again.
+- **Before each message**, what teammates sent is brought into **the branch you are on** as a
+  `📥 docs(auto): sync` commit, and you are told in one line. Only the knowledge folders are touched.
+  A doc that `main` on `origin` already has, identical, is left for your ordinary merge of `main`. On
+  a closed `main` nothing is written at all — an uncommitted file there would make your next
+  `git pull` refuse to run — you are told what is waiting, and it arrives with that pull or in the
+  next branch you open. When the last fetch is more than ten minutes old, the message fetches first
+  (three seconds at most), so even a one-message session sees fresh docs.
   A branch you open later catches up on its first message: everything on `rsc/knowledge` since it
   left `main` comes down, including what you wrote yourself on another branch.
 - **It reaches `main` the normal way.** Your feature branch now carries the team's knowledge, so it
@@ -505,7 +520,7 @@ What it will not do, by design:
 | --- | --- |
 | Push to `main` | Never. Only `rsc/knowledge` receives anything. |
 | Push your code or your unpushed commits | Only the knowledge folders go up, even from a commit that also has code. Your code waits for you. |
-| Trigger CI or a deploy | Every automatic commit says `[skip ci]`. |
+| Trigger CI or a deploy | Every commit on `rsc/knowledge` says `[skip ci]`; the one on your branch does not, so it never skips the CI of your own push. |
 | Bring in anybody else's code | Only knowledge paths come down. Code, config and `.claude/` are never pulled. |
 | Sync `02-DOCS/wiki/harness/user-profile.md` | Those are one person's dials. |
 | Overwrite a file you are editing | It tells you, and your version stays. |

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.0.7",
+  "version": "3.0.9",
   "counts": {
     "skills": 270,
     "agents": 33,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "3.0.7",
+  "version": "3.0.9",
   "description": "A guided harness builder that turns your goal into a minimal, verified AI-agent setup using strict best practices.",
   "type": "module",
   "bin": {

package/scripts/audit.js

@@ -207,6 +207,17 @@ export function stampAudit(cwd, date = new Date().toISOString()) {
   writeFileSync(join(dir, 'audit.json'), JSON.stringify({ lastRun: date }, null, 2) + '\n');
 }
 
+// The start of the cadence for a harness that has never been audited: written by onboarding so the
+// first audit falls due STALE_DAYS after install, not in the first session. `baseline` and not
+// `lastRun`, because no audit ran — the SessionStart hook reads either. Leaves an existing file alone.
+export function recordAuditBaseline(cwd, date = new Date().toISOString()) {
+  const file = join(cwd, '.rsc', 'audit.json');
+  if (existsSync(file)) return false;
+  mkdirSync(join(cwd, '.rsc'), { recursive: true });
+  writeFileSync(file, JSON.stringify({ baseline: date }, null, 2) + '\n');
+  return true;
+}
+
 // Write the report into the harness wiki when one exists; always stamp .rsc/audit.json.
 export function writeAuditReport(report, cwd = process.cwd()) {
   const written = [];

package/scripts/doctor.js

@@ -1,6 +1,7 @@
-import { hooksDir, hooksDirIsOurs } from '../targets/worktree-reaper.mjs';
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { hooksDir, hooksDirIsOurs, classifyWorktrees } from '../targets/worktree-reaper.mjs';
+import { existsSync, readFileSync, readdirSync, statSync, realpathSync } from 'node:fs';
+import { join, dirname, relative, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { targetPaths, TARGET_IDS } from '../targets/index.js';
 import { readState } from './lib/state.js';
@@ -19,6 +20,7 @@ import { metricsSummary } from '../targets/session-memory-core.mjs';
 import { agentPath } from '../targets/agents.js';
 import { projectOptOuts } from '../targets/opt-outs.js';
 import { versionReport } from './lib/versions.js';
+import { CONSTITUTION_PATH, constitutionIsDraft } from './lib/constitution-draft.js';
 
 // Gates the committed manifest says the team disarmed, still armed here. Read through the same
 // partition the installer uses, so a machine-only switch somebody's older rsc wrote into the
@@ -101,7 +103,18 @@ export function missingHookScripts({ target, home = homedir(), cwd = process.cwd
 // Is the post-merge trigger actually armed in this clone? Three states, because they need three
 // different answers: armed, absent (repair it), or someone else's (leave it — chaining is our job
 // at install time, and overwriting a husky hook to fix a convenience would be indefensible).
-function worktreeCleanupStatus(root) {
+// The skills that read or write a design identity (02-DOCS/wiki/brand/) or a starting point. The
+// state is always reported; the FIX — "run design-loop, then design-dna" — is advice, and advice needs
+// evidence. A todo web app with none of these installed was told to run two skills it does not have
+// and never asked for (E2E 2026-10-07).
+const DESIGN_SKILLS = new Set(['design', 'design-loop', 'design-dna', 'brand-voice', 'content-engine', 'marketing', 'presentations', 'make']);
+function withoutUnfoundedFix(summary, inPlay) {
+  if (inPlay || !summary || !summary.fix) return summary;
+  const { fix, ...rest } = summary;
+  return { ...rest, note: 'no design skill is installed here, so nothing is recommended' };
+}
+
+function worktreeCleanupStatus(root, policy) {
   if (!existsSync(join(root, '.git'))) return { state: 'not-a-repo' };
   if (existsSync(join(root, '.rsc', '.no-worktree-cleanup'))) return { state: 'off-by-choice' };
   // Ask git where hooks live instead of assuming `.git/hooks`. Until 2.0.1 this read the assumed
@@ -118,6 +131,13 @@ function worktreeCleanupStatus(root) {
   }
   const hook = join(dir, 'post-merge');
   if (!existsSync(hook)) {
+    // The merge hook is one of the code hooks, and the accepted plan can defer those. Recommending
+    // `repair` then is a loop with no exit — repair re-runs the same install, which honours the same
+    // plan and skips the hook again — and it contradicted `healthy: true` on every fresh small
+    // software install (E2E 2026-10-07). Said as what it is, with nothing to do.
+    if (policy?.codeHooks === false) {
+      return { state: 'not-in-plan', reason: 'the accepted plan defers code hooks, and the post-merge cleanup is one of them; `rsc reassess` revisits that.' };
+    }
     return { state: 'absent', action: 'Run `npx @ericrisco/rsc repair` to arm the post-merge cleanup in this clone.' };
   }
   try {
@@ -128,6 +148,27 @@ function worktreeCleanupStatus(root) {
   } catch { return { state: 'unreadable' }; }
 }
 
+// The two things a team trips over with worktrees (team simulation D9): a `.worktrees/` git does not
+// ignore — one `git add -A` away from committing a whole checkout — and landed worktrees still on
+// disk, which look exactly like live ones. Reported with the way out, never blocking `healthy`: both
+// cost tidiness, not work.
+const realOf = (p) => { try { return realpathSync.native(p); } catch { return p; } };
+function worktreeHygiene(root) {
+  if (!existsSync(join(root, '.git'))) return { state: 'not-a-repo' };
+  const probe = spawnSync('git', ['-C', root, 'check-ignore', '-q', '--no-index', '.worktrees/rsc-probe/file'], { encoding: 'utf8' });
+  const ignored = probe.status === 0;
+  let leftovers = [];
+  try {
+    leftovers = classifyWorktrees(root)
+      .filter((c) => c.verdict === 'safe' || c.verdict === 'ask')
+      .map((c) => ({ path: relative(realOf(root), c.path).split(sep).join('/') || c.path, branch: c.branch, verdict: c.verdict }));
+  } catch { /* unanswerable is not a finding */ }
+  const actions = [];
+  if (!ignored) actions.push('`.worktrees/` is not ignored by git here: run `npx @ericrisco/rsc sync` (it adds it to the rsc block of .gitignore) and commit .gitignore so every clone gets it.');
+  if (leftovers.length) actions.push(`${leftovers.length} landed worktree(s) are still on disk: \`npx @ericrisco/rsc worktrees\` lists them, \`npx @ericrisco/rsc worktrees reap\` removes the safe ones.`);
+  return { ignored, leftovers, ...(actions.length ? { action: actions.join(' ') } : {}) };
+}
+
 // Every skill this catalog ships declares `origin: risco` in its own frontmatter — all 272 of them,
 // uniformly. So "is this ours?" is answerable from the file itself, and does not need the list in
 // `.rsc.json` that nobody ever filled: that list is parallel accounting (P3), it has been empty in
@@ -184,8 +225,8 @@ export function doctor({ target, home, cwd }) {
     try {
       memory.metrics = hasStore
         ? metricsSummary({ cwd: root })
-        : { sessions: [], total: { cost: null, toolCalls: null }, knownTotal: { cost: 0, toolCalls: 0 }, unknown: { cost: 0, toolCalls: 0 } };
-    } catch { memory.metrics = { sessions: [], total: { cost: null, toolCalls: null }, knownTotal: { cost: 0, toolCalls: 0 }, unknown: { cost: 0, toolCalls: 0 } }; }
+        : { sessions: [], total: { cost: null, toolCalls: null }, knownTotal: { cost: null, toolCalls: null }, unknown: { cost: 0, toolCalls: 0 } };
+    } catch { memory.metrics = { sessions: [], total: { cost: null, toolCalls: null }, knownTotal: { cost: null, toolCalls: null }, unknown: { cost: 0, toolCalls: 0 } }; }
   }
   const actualSkills = listSkills({ target, home, cwd: root }).map((entry) => entry.id);
   const actualAgents = listAgents({ target, home, cwd: root }).agents.map((entry) => entry.id);
@@ -208,6 +249,9 @@ export function doctor({ target, home, cwd }) {
     const path = agentPath(target, root, id);
     return path && !existsSync(path);
   }).map((id) => ({ id, path: agentPath(target, root, id), action: 'Run `npx @ericrisco/rsc sync` to restore this managed agent.' }));
+  // What THIS harness installed, not every skill visible from here: a design skill in the user's
+  // global scope is how a todo app's doctor came to recommend design-dna (E2E 2026-10-07).
+  const designInPlay = Object.keys(state.skills || {}).some((id) => DESIGN_SKILLS.has(id));
   const report = {
     target,
     installed: Object.keys(state.skills),
@@ -224,17 +268,18 @@ export function doctor({ target, home, cwd }) {
     // The worktree cleanup's trigger is a git hook, and `.git/hooks/` is not cloned. So a repo can
     // carry a perfectly healthy harness and still never clean up, on every machine but the one that
     // ran the installer. Reported, never nagged about: `repair` is what puts it back (P6).
-    worktreeCleanup: worktreeCleanupStatus(root),
+    worktreeCleanup: worktreeCleanupStatus(root, state.policy),
+    worktreeHygiene: worktreeHygiene(root),
     ownSkills: ownSkillsIn(paths, readProjectManifest(root)?.ownSkills || []),
     sello: selloStatus(root),
     // Whether this harness has a design identity at all. `design` has always DECLARED that it
     // stops without one; until lib/design-identity.js nothing checked it (P2). Reported here,
     // never nagged about and never blocking: a missing identity is low risk (P7).
-    designIdentity: designIdentity(root),
+    designIdentity: withoutUnfoundedFix(designIdentity(root), designInPlay),
     // The other half of the same question: an identity is what this project settled on, a starting
     // point is what it has to settle FROM. Three skills promise to propose one and none could look;
     // this is the look. One field, not a section — a report grows for every user who runs it (P5).
-    designStartingPoint: startingPointSummary(root),
+    designStartingPoint: withoutUnfoundedFix(startingPointSummary(root), designInPlay),
     // An inert gate must never read as an armed one (the same rule the sello follows):
     // the gitmoji guard has a per-project kill switch, so say which state it is in.
     gitmojiGuard: state.policy?.gitmojiGuard === false
@@ -266,6 +311,11 @@ export function doctor({ target, home, cwd }) {
   for (const [id, e] of Object.entries(state.skills)) {
     for (const f of e.files) if (!existsSync(f)) report.missing.push({ id, path: f, action: 'Run `npx @ericrisco/rsc sync` to restore this managed skill.' });
   }
+  // Pending is not unhealthy: work the harness expects the user to finish, named with what does it.
+  // The draft constitution `rsc onboard` writes is the first entry; it never touches `healthy`.
+  report.pending = constitutionIsDraft(root)
+    ? [{ id: 'constitution-draft', path: CONSTITUTION_PATH, action: 'Complete it with the `constitution` phase before the first SDD feature; ratifying removes `status: draft`.' }]
+    : [];
   report.healthy = report.hookWired && !report.missing.length && !missingAgents.length && !missingCommands.length
     && !report.opencodePluginsOutdated.length;
   return report;
@@ -306,9 +356,17 @@ const bytesOf = (p) => { try { return statSync(p).size; } catch { return 0; } };
 
 // The always-on body a wired scope injects: the hook command embeds the exact SKILL.md path,
 // so read it from there rather than guessing the layout.
+// The body the SessionStart hook prints is the `.md` file its command names — today the short
+// `.rsc/suggest-always-on.md`, not the whole `suggest` SKILL.md. Reading only `…SKILL.md` out of the
+// command meant the current wiring never matched and the fallback counted the full skill: doctor said
+// 7.1 KB for a hook that injects 0.3 KB of body (E2E 2026-10-07). The command names the project
+// through ${CLAUDE_PROJECT_DIR}, so that is resolved against the scope before measuring.
 function alwaysOnBytesFor(scopeRoot, settingsRaw) {
-  const fromCommand = /"([^"]*suggest[^"]*SKILL\.md)"/.exec(settingsRaw || '');
-  if (fromCommand && bytesOf(fromCommand[1])) return bytesOf(fromCommand[1]);
+  const raw = (settingsRaw || '').replace(/\\\\/g, '/');
+  const candidates = [...raw.matchAll(/\\?"([^"\\]*suggest[^"\\]*\.md)\\?"/g)].map((m) => m[1]
+    .replace(/\$\{CLAUDE_PROJECT_DIR\}|\$CLAUDE_PROJECT_DIR/g, scopeRoot)
+    .replace(/^~(?=\/)/, homedir()));
+  for (const file of candidates) if (bytesOf(file)) return bytesOf(file);
   return bytesOf(join(scopeRoot, '.rsc', 'skills', 'suggest', 'SKILL.md'));
 }
 

package/scripts/install-apply.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { rmSync, existsSync, cpSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync, appendFileSync, readdirSync } from 'node:fs';
+import { rmSync, rmdirSync, existsSync, cpSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync, appendFileSync, readdirSync, renameSync } from 'node:fs';
 import { join, dirname, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
@@ -16,6 +16,7 @@ import { withDefaultSkillFloor } from './lib/default-skill-floor.js';
 import { isRetired, replaceRetired } from './lib/retired-skills.js';
 import { readManifest, writeManifest } from './lib/manifest-file.js';
 import { createBackup } from './lib/backups.js';
+import { removeUnmodifiedSkeleton } from './lib/tools-skeleton.js';
 import {
   targetHasCommands, resolveCommands, reconcileCommands, commandPath, allPotentialCommandNames,
 } from '../targets/commands.js';
@@ -81,6 +82,7 @@ export function generatedHookFiles({ target, cwd, policy }) {
     join(cwd, '.rsc', 'session-start.mjs'),
     join(cwd, '.rsc', 'worklog-checkpoint.mjs'),
     join(cwd, '.rsc', 'hook-once.mjs'),
+    join(cwd, '.rsc', 'shell-unwrap.mjs'),
     join(cwd, '.rsc', 'worktree-reaper.mjs'),
     join(cwd, '.rsc', 'auto-update.mjs'),
     // team-safe-default: the 3.0 start-up duties and the trunk policy (also read by branch-guard).
@@ -90,12 +92,14 @@ export function generatedHookFiles({ target, cwd, policy }) {
   // The danger guard is declared on its own terms (#273): present unless the plan says otherwise,
   // whether or not the code guards are.
   const danger = policy?.dangerGuard === false ? [] : [join(cwd, '.rsc', 'danger-guard.mjs')];
-  if (policy?.codeHooks === false) return [...lifecycle, ...danger, join(cwd, '.rsc', 'suggest-always-on.md')];
+  const laneGate = policy?.laneGate ?? policy?.codeHooks !== false;
+  const lane = laneGate ? [join(cwd, '.rsc', 'userprompt-gate.mjs'), join(cwd, '.rsc', 'ftd-nudge.mjs')] : [];
+  if (policy?.codeHooks === false) return [...lifecycle, ...danger, ...(laneGate ? lane : [join(cwd, '.rsc', 'suggest-always-on.md')])];
   return [...lifecycle, ...danger,
     join(cwd, '.rsc', 'ship-guard.mjs'),
     join(cwd, '.rsc', 'branch-guard.mjs'),
     join(cwd, '.rsc', 'gitmoji-guard.mjs'), join(cwd, '.rsc', 'userprompt-gate.mjs'),
-    join(cwd, '.rsc', 'sello.mjs')];
+    join(cwd, '.rsc', 'sello.mjs'), ...(laneGate ? [join(cwd, '.rsc', 'ftd-nudge.mjs')] : [])];
 }
 
 export function managedPathsForInstall({ skillIds, agentIds = [], target, home, cwd, policy }) {
@@ -335,6 +339,7 @@ export async function applyInstall({ skillIds = [], agentIds = [], target, home,
     alwaysOn: policy.alwaysOn !== false,
     codeHooks: policy.codeHooks !== false,
     dangerGuard: policy.dangerGuard !== false,
+    laneGate: policy.laneGate ?? policy.codeHooks !== false,
     gitmojiGuard: policy.gitmojiGuard !== false,
     memory: policy.memory !== false,
     context7: policy.context7 === true,
@@ -402,7 +407,12 @@ export function ignoreLocalState(cwd = process.cwd(), target) {
   // whole directory would quietly stop versioning their work, which is the same sin this
   // release exists to fix: treating what is theirs as if it were ours. So shared
   // directories are excluded entry by entry, and only the entries rsc manages.
-  const wanted = ['.rsc/'];
+  // `.worktrees/` is where the isolation rule sends every concurrent session (`git worktree add
+  // .worktrees/<branch>`). Nothing ignored it, so in a teammate's clone it surfaced as `?? .worktrees/`
+  // — one `git add -A` from committing a whole checkout (team simulation D9). It goes in THIS block,
+  // the committed one, so every clone inherits it with its first pull; `.git/info/exclude` would
+  // only ever cover the machine that ran the installer.
+  const wanted = ['.rsc/', '.worktrees/'];
   if (target) {
     const paths = targetPaths(target, undefined, cwd);
     const rel = (abs) => relative(cwd, abs).split(sep).join('/');
@@ -697,6 +707,11 @@ export async function syncInstalled({ target, home, cwd = process.cwd(), dryRun
     policy: manifest?.onboarding?.plan?.policy,
     onboarding: manifest?.onboarding,
   });
+  // A teammate never runs onboarding — the harness arrives in the clone — so the exclude onboarding
+  // writes for the personal profile never reached them, and their first answer to the one onboarding
+  // question sat untracked, one `git add -A` from the team repo (team simulation D13). Sync is what a
+  // clone runs, so it writes the same exclude. Lazy import: onboarding-apply imports this module.
+  try { (await import('./lib/onboarding-apply.js')).excludePersonalProfile(cwd); } catch { /* not a repo → nothing */ }
   return { synced: declared, syncedAgents: declaredAgents, backup: nextState.backup };
 }
 
@@ -706,13 +721,58 @@ export async function syncInstalled({ target, home, cwd = process.cwd(), dryRun
 // own knowledge — kept unless `withDocs` is set. Returns the paths touched.
 // Note: backups live under `.rsc/backups/`, which this removes — so purge does not
 // snapshot (a pre-purge backup would delete itself). It is the deliberate escape hatch.
-export async function purge({ home, cwd = process.cwd(), withDocs = false, dryRun = false } = {}) {
-  const removed = [];
+export async function purge(options = {}) {
+  const report = await purgeReport(options);
+  return [...report.removed, ...report.cleaned];
+}
+
+// A config file whose only content was rsc's is not "cleaned" when the rsc entries leave it as `{}`:
+// it is a stub nobody asked for, and calling it removed while it sits on disk is the lie the E2E
+// caught. `$schema` and `version` are format boilerplate rsc itself adds, not user content.
+function emptyConfig(file) {
+  let value;
+  try { value = JSON.parse(readFileSync(file, 'utf8')); } catch { return false; }
+  const empty = (v) => (Array.isArray(v) ? v.every(empty)
+    : v && typeof v === 'object' ? Object.values(v).every(empty) : false);
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const rest = Object.fromEntries(Object.entries(value).filter(([k]) => k !== '$schema' && k !== 'version'));
+  return empty(rest);
+}
+
+const RSC_IGNORE_HEADER = '# rsc local state (hooks, seals, logs) and managed skill links — machine-local';
+
+// Remove the blocks `ignoreLocalState` appended: the header line, the entries under it up to the
+// next blank line, and the blank seam before it. Lines the user wrote are never part of a block.
+function stripIgnoreBlocks(text) {
+  const lines = text.split('\n');
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i] !== RSC_IGNORE_HEADER) { out.push(lines[i]); continue; }
+    if (out.length && out[out.length - 1] === '') out.pop();
+    while (i + 1 < lines.length && lines[i + 1].trim() !== '') i++;
+  }
+  return out.join('\n');
+}
+
+/**
+ * Remove EVERYTHING rsc put in this project and say exactly what happened to each thing:
+ *   removed — gone from disk;
+ *   cleaned — rsc's entries taken out, the file kept because something of the user's remains;
+ *   kept    — left on purpose, with the reason (and the command, when it is the user's call).
+ * `02-DOCS/` is the user's own knowledge — kept unless `withDocs` is set. Remote branches are never
+ * deleted from here. Backups live under `.rsc/backups/`, which this removes — so purge does not
+ * snapshot (a pre-purge backup would delete itself). It is the deliberate escape hatch.
+ */
+export async function purgeReport({ home, cwd = process.cwd(), withDocs = false, dryRun = false } = {}) {
+  const removed = new Set();
+  const cleaned = new Set();
+  const kept = [];
   const drop = (p, recursive = false) => {
-    if (!existsSync(p)) return;
-    removed.push(p);
+    if (!existsSync(p) && !isLink(p)) return;
+    removed.add(p);
     if (!dryRun) rmSync(p, { recursive, force: true });
   };
+  const touchedConfigs = new Set();
   for (const target of TARGET_IDS) {
     const paths = targetPaths(target, home, cwd);
     if (existsSync(paths.stateFile)) {
@@ -730,25 +790,168 @@ export async function purge({ home, cwd = process.cwd(), withDocs = false, dryRu
       }
       drop(paths.stateFile);
     }
+    const bootstrap = join(paths.projectRoot || cwd, '.claude', 'rsc-bootstrap.mjs');
+    const hadBootstrap = target === 'claude' && existsSync(bootstrap);
     // Unwiring mutates shared config files, so only run it for real (dry runs report
     // those files without touching them).
     if (!dryRun) {
-      removed.push(...unwireHook(target, paths));
-      removed.push(...unwireMemory(target, cwd));
-      removed.push(...unwireUpdate(target, cwd));
-      removed.push(...unwireKnowledge(target, cwd));
-      removed.push(...unwireGitPermissions(target, cwd));
+      for (const p of [
+        ...unwireHook(target, paths),
+        ...unwireMemory(target, cwd),
+        ...unwireUpdate(target, cwd),
+        ...unwireKnowledge(target, cwd),
+        ...unwireGitPermissions(target, cwd),
+      ]) touchedConfigs.add(p);
+      if (hadBootstrap && !existsSync(bootstrap)) removed.add(bootstrap);
     } else {
-      removed.push(...memoryArtifactsPresent(target, cwd));
-      removed.push(...updateArtifactsPresent(target, cwd));
-      removed.push(...knowledgeArtifactsPresent(target, cwd));
+      for (const p of [
+        ...memoryArtifactsPresent(target, cwd),
+        ...updateArtifactsPresent(target, cwd),
+        ...knowledgeArtifactsPresent(target, cwd),
+      ]) touchedConfigs.add(p);
+      if (paths.hookTarget && existsSync(paths.hookTarget)
+        && /\.rsc\/|rsc-suggest:start|skills\/rsc\/suggest/.test(readFileSync(paths.hookTarget, 'utf8').replaceAll('\\\\', '/'))) {
+        touchedConfigs.add(paths.hookTarget);
+      }
+      if (hadBootstrap) removed.add(bootstrap);
     }
     // A lost state file also loses proof of ownership. Leave same-named user files
     // behind rather than guessing from a catalog id and deleting their work.
   }
-  drop(join(cwd, '.rsc'), true);
+  const rscDir = join(cwd, '.rsc');
+  for (const p of touchedConfigs) {
+    if (p === rscDir || p.startsWith(`${rscDir}${sep}`)) { removed.add(p); continue; }
+    if (dryRun) { if (existsSync(p)) cleaned.add(p); continue; }
+    if (!existsSync(p)) { removed.add(p); continue; }
+    let body = '';
+    try { body = readFileSync(p, 'utf8'); } catch { /* unreadable: leave it, call it cleaned */ }
+    if (/\.json$/i.test(p) ? emptyConfig(p) : body.trim() === '') {
+      rmSync(p, { force: true });
+      removed.add(p);
+    } else cleaned.add(p);
+  }
+
+  // The `.gitignore` block rsc appended. The file goes only if nothing of the user's is left in it.
+  const gitignore = join(cwd, '.gitignore');
+  if (existsSync(gitignore)) {
+    const text = readFileSync(gitignore, 'utf8');
+    if (text.includes(RSC_IGNORE_HEADER)) {
+      const rest = stripIgnoreBlocks(text);
+      if (rest.trim() === '') { removed.add(gitignore); if (!dryRun) rmSync(gitignore, { force: true }); }
+      else { cleaned.add(gitignore); if (!dryRun) writeFileSync(gitignore, rest.endsWith('\n') ? rest : `${rest}\n`); }
+    }
+  }
+
+  // The committed declaration of the harness that no longer exists.
+  drop(join(cwd, '.rsc.json'));
+
+  // The `01-TOOLS/` scaffolding onboarding wrote, only where nobody has touched it.
+  const skeleton = removeUnmodifiedSkeleton(cwd, { dryRun });
+  for (const rel of skeleton.removed) removed.add(join(cwd, rel));
+  for (const k of skeleton.kept) kept.push(k);
+
+  drop(rscDir, true);
   if (withDocs) drop(join(cwd, '02-DOCS'), true);
-  return [...new Set(removed)];
+  else if (existsSync(join(cwd, '02-DOCS'))) kept.push({ path: '02-DOCS/', reason: 'your knowledge base. Add --with-docs to remove it too.' });
+
+  // Lines rsc added to `.git/info/exclude` for files that are now gone.
+  const exclude = gitExcludeFile(cwd);
+  if (exclude && existsSync(exclude)) {
+    const gone = new Set([...removed].map((p) => `/${relative(cwd, p).split(sep).join('/')}`));
+    const lines = readFileSync(exclude, 'utf8').split('\n');
+    const keptLines = lines.filter((l) => !(gone.has(l.trim()) || l.trim().startsWith('/.rsc/')));
+    if (keptLines.length !== lines.length) {
+      cleaned.add(exclude);
+      if (!dryRun) writeFileSync(exclude, keptLines.join('\n'));
+    }
+  }
+
+  // Directories that only held what was just removed. Deepest first; never `cwd` itself.
+  const parents = new Set();
+  for (const p of removed) {
+    for (let d = dirname(p); d !== cwd && d.startsWith(`${cwd}${sep}`); d = dirname(d)) parents.add(d);
+  }
+  const ordered = [...parents].sort((a, b) => b.split(sep).length - a.split(sep).length);
+  const willBeEmpty = (dir) => {
+    try {
+      return readdirSync(dir).every((name) => {
+        const child = join(dir, name);
+        return removed.has(child);
+      });
+    } catch { return false; }
+  };
+  for (const dir of ordered) {
+    if (!existsSync(dir) || isLink(dir)) continue;
+    if (dryRun ? willBeEmpty(dir) : readdirSync(dir).length === 0) {
+      if (!dryRun) rmdirSync(dir);
+      removed.add(dir);
+    }
+  }
+
+  // The knowledge exchange branch lives on the remote, which is shared: deleting it is the user's
+  // call, so say it exists and hand them the command.
+  for (const ref of gitLines(cwd, ['for-each-ref', '--format=%(refname)', 'refs/remotes/*/rsc/knowledge', 'refs/heads/rsc/knowledge'])) {
+    const remote = /^refs\/remotes\/([^/]+)\/rsc\/knowledge$/.exec(ref)?.[1];
+    if (remote) kept.push({ path: `${remote}/rsc/knowledge`, reason: `remote branch; rsc never deletes remote branches. To delete it: git push ${remote} --delete rsc/knowledge` });
+    else kept.push({ path: 'rsc/knowledge', reason: 'local branch. To delete it: git branch -D rsc/knowledge' });
+  }
+
+  // The post-merge hook rsc installs (worktree-reaper.mjs). It lives in git's private hooks dir, so it
+  // is per clone, never committed — and left behind it kept calling a reaper that no longer exists.
+  // Only a hook carrying rsc's marker is touched; one rsc had chained aside is put back in place.
+  const [hooks] = gitLines(cwd, ['rev-parse', '--path-format=absolute', '--git-path', 'hooks']);
+  const hook = hooks ? join(hooks, 'post-merge') : null;
+  if (hook && existsSync(hook)) {
+    let body = '';
+    try { body = readFileSync(hook, 'utf8'); } catch { /* unreadable → not provably ours */ }
+    if (body.includes('# rsc-managed worktree cleanup (post-merge)')) {
+      const chained = join(hooks, 'post-merge.rsc-local');
+      if (existsSync(chained)) {
+        cleaned.add(hook);
+        if (!dryRun) { rmSync(hook, { force: true }); renameSync(chained, hook); }
+      } else drop(hook);
+    }
+  }
+
+  // The project's instruction files are never purge's to delete. Say so, so the report accounts for them.
+  for (const name of ['CLAUDE.md', 'AGENTS.md']) {
+    const file = join(cwd, name);
+    if (existsSync(file) && !removed.has(file) && !cleaned.has(file)) {
+      kept.push({ path: name, reason: 'your project instructions; purge never deletes them. If they still mention rsc or 02-DOCS, edit those lines by hand.' });
+    }
+  }
+
+  // A path that is both removed and cleaned was cleaned, then emptied, then removed.
+  for (const p of removed) cleaned.delete(p);
+  // `.rsc/` is rsc's own directory and goes whole: listing its files one by one adds noise, not truth.
+  if (removed.has(rscDir)) for (const p of [...removed]) if (p.startsWith(`${rscDir}${sep}`)) removed.delete(p);
+
+  // What of the removed or cleaned is COMMITTED. On a teammate's clone that is most of it (.rsc.json,
+  // .claude/settings.json, the bootstrap…): changing it here is local, committing the changes
+  // uninstalls rsc for everyone who pulls (team simulation D15). The index still has them after the
+  // delete, so this reads the same in a dry run and a real one.
+  const gone = new Set([...removed, ...cleaned].map((p) => relative(cwd, p).split(sep).join('/')));
+  const under = (file) => { for (let d = file; d && d !== '.'; d = d.includes('/') ? d.slice(0, d.lastIndexOf('/')) : '') if (gone.has(d)) return true; return false; };
+  const listed = spawnSync('git', ['ls-files', '-z'], { cwd, encoding: 'utf8' });
+  const tracked = listed.status === 0
+    ? listed.stdout.split('\0').filter(Boolean).filter(under) : [];
+  return { removed: [...removed], cleaned: [...cleaned], kept, tracked };
+}
+
+function isLink(p) {
+  try { return lstatSync(p).isSymbolicLink(); } catch { return false; }
+}
+
+function gitLines(cwd, args) {
+  try {
+    const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
+    return r.status === 0 ? r.stdout.split('\n').map((l) => l.trim()).filter(Boolean) : [];
+  } catch { return []; }
+}
+
+function gitExcludeFile(cwd) {
+  const [value] = gitLines(cwd, ['rev-parse', '--git-path', 'info/exclude']);
+  return value ? resolve(cwd, value) : null;
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {