@ericrisco/rsc 3.0.7 → 3.0.8

package/targets/ship-guard.mjs

@@ -5,7 +5,10 @@
 //
 // Enforces the "close the feature before you leave it" rule at the one deterministic
 // moment it matters: when a Bash command tries to switch to the trunk (main/master)
-// or merge into it. If the current feature branch has uncommitted changes or commits
+// or merge into it. A merge run ON the feature branch (`git merge origin/main`) brings
+// the trunk in — it leaves nothing behind, so it is not judged (team simulation D10);
+// a merge counts only where it lands on a trunk checkout (`git -C ../main merge feat`).
+// rsc's own knowledge commits (📥/📝 docs(auto)) are not the person's unpushed work. If the current feature branch has uncommitted changes or commits
 // that were never pushed, the guard DENIES the command and tells the agent to run
 // `ship` (commit → push → PR). Opening the PR itself is `ship`'s job and the skill's
 // hard rule; this hook guarantees you cannot quietly abandon unsaved/unpushed work.
@@ -14,7 +17,7 @@
 // and FAIL-OPEN — any ambiguity (detached HEAD, no repo, git error) allows the command.
 // Opt out per project with .rsc/.no-ship-guard.
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { isAbsolute, join, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
 const root = process.argv[2] || process.cwd();
@@ -62,14 +65,42 @@ try {
 if (existsSync(join(root, '.rsc', '.no-ship-guard'))) allow();
 
 // Does this command try to land on / move to the trunk?
-const TRUNK = /\bgit\s+(?:checkout|switch)\s+(?:-{1,2}\S+\s+)*(?:main|master)\b/;
-const MERGE = /\bgit\s+merge\b/;
-if (!TRUNK.test(command) && !MERGE.test(command)) allow();
+// Global options may sit before the subcommand (`git -C . switch main`, `git -c k=v merge`), and the
+// command may be handed to a shell (`bash -c "git switch main"`): the segments judged are the ones the
+// shell really runs, quoted text blanked (shell-unwrap.mjs, shared with the other guards — E2E defect
+// 15). Without that sibling, the raw command as before.
+const GOPTS = String.raw`(?:(?:-[Cc]\s+\S+|--\S+)\s+)*`;
+const TRUNK = new RegExp(String.raw`\bgit\s+${GOPTS}(?:checkout|switch)\s+(?:-{1,2}\S+\s+)*(?:main|master)\b`);
+const MERGE = new RegExp(String.raw`\bgit\s+${GOPTS}merge\b`);
+const SH = await import(new URL('./shell-unwrap.mjs', import.meta.url)).catch(() => null);
+const judged = SH ? SH.expand(command).map((s) => s.replace(/"(?:[^"\\]|\\.)*"|'[^']*'/g, '""')) : [command];
 
-const git = (...args) => {
-  const r = spawnSync('git', ['-C', root, ...args], { windowsHide: true, encoding: 'utf8' });
+const gitIn = (dir, ...args) => {
+  const r = spawnSync('git', ['-C', dir, ...args], { windowsHide: true, encoding: 'utf8' });
   return r.status === 0 ? (r.stdout || '').trim() : null;
 };
+const git = (...args) => gitIn(root, ...args);
+
+// A merge lands on the trunk only where the checkout it runs in IS on the trunk. Here that means a
+// `git -C <dir> merge` aimed at another checkout; a merge in this one runs on the feature branch
+// (checked below), and `git switch main && git merge x` is already caught by its switch.
+function mergesIntoTrunk(segment) {
+  if (!MERGE.test(segment)) return false;
+  const m = segment.match(/\bgit\s+(?:-c\s+\S+\s+)*-C\s+(\S+)/);
+  if (!m) return false;
+  const dir = isAbsolute(m[1]) ? m[1] : resolve(root, m[1]);
+  const b = gitIn(dir, 'rev-parse', '--abbrev-ref', 'HEAD');
+  return b === 'main' || b === 'master';
+}
+if (!judged.some((s) => TRUNK.test(s) || mergesIntoTrunk(s))) allow();
+
+// Commits in a range that are the person's: rsc's own knowledge commits are left out.
+const RSC_OWN = /^(?:📥|📝) docs\(auto\)/u;
+function ownCommits(range) {
+  const log = git('log', '--format=%s', range);
+  if (log === null) return null;
+  return log.split('\n').filter((s) => s && !RSC_OWN.test(s)).length;
+}
 
 const branch = git('rev-parse', '--abbrev-ref', 'HEAD');
 // Not on a feature branch (already trunk, detached, or git failed) → nothing to guard.
@@ -86,13 +117,13 @@ if (dirty && dirty.length > 0) {
 // 2) Commits exist but were never pushed.
 const upstream = git('rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}');
 if (upstream) {
-  const ahead = git('rev-list', '--count', `${upstream}..HEAD`);
+  const ahead = ownCommits(`${upstream}..HEAD`);
   if (ahead && Number(ahead) > 0) {
     deny(`Feature branch "${branch}" has ${ahead} commit(s) not pushed to ${upstream}. Push them and open the PR — run the \`ship\` skill — before switching to the trunk.${tail}`);
   }
 } else {
   // No upstream at all: if the branch carries commits beyond the trunk, it was never pushed.
-  const aheadOfTrunk = git('rev-list', '--count', 'main..HEAD') ?? git('rev-list', '--count', 'master..HEAD');
+  const aheadOfTrunk = ownCommits('main..HEAD') ?? ownCommits('master..HEAD');
   if (aheadOfTrunk && Number(aheadOfTrunk) > 0) {
     deny(`Feature branch "${branch}" was never pushed (no upstream, ${aheadOfTrunk} commit(s) ahead of the trunk). Push it and open a PR — run the \`ship\` skill — before leaving it.${tail}`);
   }

package/targets/team-safe-start.mjs

@@ -12,7 +12,7 @@
 // Each returns the text to say, or ''. None throws: a session start is never worth breaking.
 // Standalone siblings under `.rsc/`: trunk-policy.mjs, worktree-reaper.mjs, session-memory-core.mjs.
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { basename, join, sep } from 'node:path';
 
 const git = (root, args) => {
@@ -92,13 +92,23 @@ export async function relocateOldWorktrees(root) {
 
 const MARK = '.team-safe-3';
 
-export function teamSafeAnnouncement(root) {
+// Which language to say it in. The profile's `language:` frontmatter field when there is one, then the
+// locale the assistant runs under, and English when neither says: this banner reached English-speaking
+// users in Spanish. The other always-on texts are English and ask the agent to relay them in the
+// person's language; this one keeps a Spanish version because it was written for Spanish users first.
+export function announcementLanguage(root, env = process.env) {
   try {
-    const mark = join(root, '.rsc', MARK);
-    if (existsSync(mark)) return '';
-    mkdirSync(join(root, '.rsc'), { recursive: true });
-    writeFileSync(mark, `${new Date().toISOString()}\n`);
-    return `
+    const profile = readFileSync(join(root, '02-DOCS', 'wiki', 'harness', 'user-profile.md'), 'utf8');
+    const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(profile)?.[1] || '';
+    const declared = /^(?:language|lang|idioma)\s*:\s*["']?([^"'\r\n]+)/mi.exec(front)?.[1]?.trim().toLowerCase();
+    if (declared) return /^(es|spa|español|espanol|castellano|spanish)\b/.test(declared) ? 'es' : 'en';
+  } catch { /* no profile: fall through to the locale */ }
+  const locale = String(env.LC_ALL || env.LC_MESSAGES || env.LANG || '').toLowerCase();
+  return /^es([_.-]|$)/.test(locale) ? 'es' : 'en';
+}
+
+const ANNOUNCEMENT = {
+  es: `
 ===== rsc 3.0 · equipo seguro por defecto =====
 ACTION: díselo a la persona en pocas líneas, una vez, antes de su petición:
 1. Si la rama principal está abierta (proyectos sencillos), el agente trabaja en ella sin preguntar.
@@ -108,9 +118,65 @@ ACTION: díselo a la persona en pocas líneas, una vez, antes de su petición:
    worktree en .worktrees/<rama>/. Para no hacerlo: «no uses worktrees».
 3. El agente elige solo entre FTD (lo sencillo) y SDD (lo grande o complejo) y lo dice; se puede
    pedir el otro.
-4. 01-TOOLS/ y 02-DOCS/ viajan al equipo por la rama rsc/knowledge y llegan a la principal dentro de
-   las PRs. Para apagarlo: rsc knowledge-sync off.
+4. Las herramientas (01-TOOLS/) y la wiki (02-DOCS/wiki/, attachments/) viajan al equipo por la
+   rama rsc/knowledge y llegan a la principal dentro de las PRs. Para apagarlo: rsc knowledge-sync off.
 ==============================================
-`;
+`,
+  en: `
+===== rsc 3.0 · team-safe by default =====
+ACTION: tell the person in a few lines, once, before their request, in their language:
+1. If the default branch is open (simple projects), the agent works on it without asking.
+   If it is closed (long-lived code, CI or a team), it asks before each change: this branch,
+   a new one, or unlock? It never opens a branch on its own. To change it: "unlock main" or
+   "lock main" (rsc main unlock | lock).
+2. If another assistant session is working in this same folder, new work goes to a worktree in
+   .worktrees/<branch>/. To turn that off: "don't use worktrees" (rsc isolation off).
+3. The agent picks between FTD (simple work) and SDD (large or complex work) and says which; you
+   can ask for the other.
+4. Tools (01-TOOLS/) and the wiki (02-DOCS/wiki/, attachments/) travel to the team on the
+   rsc/knowledge branch and reach the default branch inside pull requests. Off: rsc knowledge-sync off.
+==========================================
+`,
+};
+
+export function teamSafeAnnouncement(root, env = process.env) {
+  try {
+    const mark = join(root, '.rsc', MARK);
+    if (existsSync(mark)) return '';
+    mkdirSync(join(root, '.rsc'), { recursive: true });
+    writeFileSync(mark, `${new Date().toISOString()}\n`);
+    return ANNOUNCEMENT[announcementLanguage(root, env)];
+  } catch { return ''; }
+}
+
+/**
+ * The harness only reaches a teammate through what is committed: `.rsc.json` (the decision), the
+ * Claude settings that wire the guards and hooks, the bootstrap a clone runs. Field tests 3.0.7 and
+ * 3.0.8: five sessions each, and none of those files was ever committed — «team-safe by default»
+ * that never left the machine. Said at session start while `.rsc.json` is untracked in a repo with a
+ * remote; at most once a week, so it informs without nagging (P7). The agent proposes, never commits
+ * on its own.
+ */
+const HARNESS_FILES = ['.rsc.json', '.claude/settings.json', '.claude/rsc-bootstrap.mjs', '.gitignore'];
+const COMMIT_MARK = '.harness-commit-offered';
+const WEEK_MS = 7 * 24 * 3600 * 1000;
+
+export function harnessCommitNotice(root, now = Date.now()) {
+  try {
+    const run = (args) => execFileSync('git', args, { cwd: root, encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (!existsSync(join(root, '.rsc.json'))) return '';
+    if (!run(['remote'])) return '';
+    if (run(['ls-files', '--', '.rsc.json'])) return '';
+    const mark = join(root, '.rsc', COMMIT_MARK);
+    if (existsSync(mark) && now - Date.parse(readFileSync(mark, 'utf8').trim()) < WEEK_MS) return '';
+    mkdirSync(join(root, '.rsc'), { recursive: true });
+    writeFileSync(mark, `${new Date(now).toISOString()}\n`);
+    const files = HARNESS_FILES.filter((f) => existsSync(join(root, f)));
+    return '===== rsc · harness not committed =====\n' +
+      `The harness files (${files.join(', ')}) are not in git, so teammates and new clones get no guards, ` +
+      'hooks or decisions. ACTION: tell the person in one line, in their language, and offer to commit ' +
+      'them with their next change (on the branch this project uses). Do not commit them on your own.\n' +
+      '=======================================\n';
   } catch { return ''; }
 }
+

package/targets/worktree-reaper.mjs

@@ -16,7 +16,7 @@
 //
 // Imported by `.rsc/session-start.mjs` (the sweep) and by `scripts/rsc.js` (`rsc worktrees`), so the
 // rule exists once and both entry points cannot drift apart. Same shape as `sello.mjs`.
-import { existsSync, realpathSync, mkdirSync, readFileSync, writeFileSync, renameSync, chmodSync } from 'node:fs';
+import { existsSync, realpathSync, mkdirSync, readFileSync, readdirSync, writeFileSync, renameSync, chmodSync, copyFileSync } from 'node:fs';
 import { join, resolve, dirname, basename, relative, sep } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
@@ -50,6 +50,14 @@ export const REGENERABLE = [
 // directory name means something only as a directory.
 export const REGENERABLE_FILES = ['.DS_Store', 'Thumbs.db', '.coverage'];
 
+// rsc's OWN state inside a worktree: hook markers, knowledge-sync's index, the memory journal. It is
+// in no commit by design, so the contents check read it as work that "would be lost" and refused
+// every landed worktree a session had ever worked in (team simulation D8) — the default cleanup
+// never ran. It does not block. The one part of it that is history — the session journal — is moved
+// to the project's store before the directory goes (`adoptJournal`), never dropped.
+export const RSC_STATE = ['.rsc/', '02-DOCS/raw/worklog/.rsc-memory/'];
+const isRscState = (path) => RSC_STATE.some((prefix) => path === prefix || path === prefix.slice(0, -1) || path.startsWith(prefix));
+
 // Trunk candidates, most authoritative first. The remote tip beats a local branch that may be stale.
 const TRUNKS = ['origin/main', 'main', 'origin/master', 'master'];
 
@@ -251,7 +259,7 @@ export function contentOutsideHistory(wtPath) {
     // does not exist — the exact failure the `raw` comment above exists to prevent (P6).
     if (code[0] === 'R' || code[0] === 'C') { i++; dirty.push(path); continue; }
     if (code === '??' || code === '!!') {
-      if (!isRegenerable(path)) outside.push(path);
+      if (!isRegenerable(path) && !isRscState(path)) outside.push(path);
     } else dirty.push(path);
   }
   return { dirty, outside, readable: true };
@@ -355,6 +363,11 @@ export function reapWorktree(root, targetPath, { confirmed = false } = {}) {
     return { removed: false, reason: refusal(candidate) };
   }
 
+  // The journal first: if it cannot be carried home, the directory stays (fail towards keeping).
+  try { adoptJournal(root, target); } catch (err) {
+    return { removed: false, reason: `its session journal could not be moved to the project, so nothing was removed: ${err.message}` };
+  }
+
   const removal = git(root, ['worktree', 'remove', '--force', target]);
   if (!removal.ok) {
     return { removed: false, reason: `git refused to remove it: ${removal.err || removal.out}` };
@@ -379,6 +392,96 @@ export function reapWorktree(root, targetPath, { confirmed = false } = {}) {
   };
 }
 
+/**
+ * Carry a worktree's memory journal into the project's store before the worktree is removed.
+ *
+ * Since sessions inside `.worktrees/` journal into the project's store directly, this is the net for
+ * what older versions (and any session that ran before that fix) left inside the worktree. Merge by
+ * file name, the newer record wins, nothing in the project is ever overwritten by something older.
+ * The project's store is the same one the memory picks: the ignored wiki worklog when it is in use,
+ * `.rsc/memory` otherwise.
+ */
+export function adoptJournal(root, worktreePath) {
+  const sources = [join(worktreePath, '.rsc', 'memory'), join(worktreePath, '02-DOCS', 'raw', 'worklog', '.rsc-memory')]
+    .filter((dir) => existsSync(dir));
+  if (!sources.length) return { moved: [] };
+  const worklogStore = join(root, '02-DOCS', 'raw', 'worklog', '.rsc-memory');
+  const dest = existsSync(join(worklogStore, 'sessions')) ? worklogStore : join(root, '.rsc', 'memory');
+  const stamp = (value) => new Date(value?.timestamps?.updatedAt || value?.updatedAt || value?.approvedAt || value?.startedAt || 0).getTime() || 0;
+  const read = (path) => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; } };
+  const moved = [];
+  for (const source of sources) {
+    for (const kind of ['sessions', 'anchors', 'lessons']) {
+      const dir = join(source, kind);
+      if (!existsSync(dir)) continue;
+      for (const name of readdirSync(dir).filter((n) => n.endsWith('.json'))) {
+        const from = join(dir, name);
+        const to = join(dest, kind, name);
+        if (existsSync(to) && stamp(read(to)) >= stamp(read(from))) continue;
+        mkdirSync(join(dest, kind), { recursive: true });
+        copyFileSync(from, to);
+        chmodSync(to, 0o600);
+        moved.push(`${kind}/${name}`);
+      }
+    }
+  }
+  return { moved };
+}
+
+// Branches that are never a cleanup's side effect, whatever their state: the knowledge branch carries
+// 01-TOOLS/ and 02-DOCS/ to the team (knowledge-sync) and is merged into the trunk as a matter of course.
+export const KEEP_BRANCHES = ['rsc/knowledge'];
+
+/**
+ * Plain local branches whose work has landed: the half of "al fusionar se borra solo" that has no
+ * directory. E2E defect 14 (2026-10-07): a branch merged into the default branch — or whose remote
+ * branch the forge deleted after the PR, `[gone]` — stayed in `git branch` for ever, landed work
+ * looking exactly like live work.
+ *
+ * Deleted only when ALL hold, each failing towards keeping the branch:
+ *   - the cleanup is on, and a trunk resolves (the remote tip first, like the worktrees);
+ *   - it is not the default branch, a trunk name, `rsc/knowledge`, the current branch, or checked out
+ *     in ANY worktree (`branch -d` would refuse that last one anyway; we do not even ask);
+ *   - its tip is an ancestor of the trunk — no commit of its own left. Against `origin/<default>`
+ *     when there is one, so a branch merged locally but not yet pushed keeps its unpushed commits
+ *     (being ahead of its own upstream then loses nothing: those commits are on the remote trunk);
+ *   - it really carried work: a commit in its reflog, or an upstream the forge deleted. A branch cut a
+ *     moment ago is an ancestor of everything and has landed nothing (same rule as `hasLandedWork`).
+ * And then git decides: `branch -d`, never -D. A squash-merged branch is `[gone]` but has commits of
+ * its own by identity, so it is not an ancestor and stays — its commits remain recoverable.
+ *
+ * Never throws (it runs from the post-merge hook, like `autoReap`).
+ */
+export function reapMergedBranches(root) {
+  const out = { deleted: [], kept: [] };
+  try {
+    if (!isCleanupEnabled(root)) return out;
+    const trunk = resolveTrunk(root);
+    if (!trunk) return out;
+    const defaultName = trunk.replace(/^origin\//, '');
+    const current = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']).out || null;
+    const checkedOut = new Set(listWorktrees(root).map((wt) => wt.branch).filter(Boolean));
+    const refs = git(root, ['for-each-ref', '--format=%(refname:short)%00%(upstream:track)', 'refs/heads']);
+    if (!refs.ok) return out;
+    for (const line of refs.out.split('\n').filter(Boolean)) {
+      const [branch, track = ''] = line.split('\0');
+      const keep = (reason) => out.kept.push({ branch, reason });
+      if (branch === defaultName || isTrunkName(branch) || KEEP_BRANCHES.includes(branch)) continue;
+      if (branch === current) { keep('current branch'); continue; }
+      if (checkedOut.has(branch)) { keep('checked out in a worktree'); continue; }
+      if (!git(root, ['merge-base', '--is-ancestor', `refs/heads/${branch}`, trunk]).ok) continue; // live work
+      const gone = track.includes('gone');
+      if (!gone && !hasLandedWork(root, { branch })) { keep('never carried a commit'); continue; }
+      const del = git(root, ['branch', '-d', branch]);
+      if (del.ok) out.deleted.push(branch);
+      else keep(`git branch -d refused: ${del.err || del.out}`);
+    }
+  } catch (err) {
+    out.kept.push({ branch: null, reason: `branch cleanup could not run: ${err.message}` });
+  }
+  return out;
+}
+
 /**
  * Every refusal carries the way out, because the person receiving it may not be able to deduce one (P6).
  *
@@ -401,7 +504,7 @@ export function reapWorktree(root, targetPath, { confirmed = false } = {}) {
  *  - it is silent when there is nothing to do, so the common merge prints nothing.
  */
 export function autoReap(root) {
-  const result = { reaped: [], skipped: [], disabled: false };
+  const result = { reaped: [], skipped: [], disabled: false, branches: { deleted: [], kept: [] } };
   try {
     if (!isCleanupEnabled(root)) {
       result.disabled = true;
@@ -421,6 +524,8 @@ export function autoReap(root) {
       if (out.removed) result.reaped.push(candidate.path);
       else result.skipped.push({ path: candidate.path, reason: out.reason });
     }
+    // After the worktrees: removing one frees its branch, which may then be a landed plain branch.
+    result.branches = reapMergedBranches(root);
   } catch (err) {
     // Swallowed deliberately, and recorded rather than discarded: the merge must survive whatever
     // went wrong in here, but a silent failure that leaves no trace is how this rots unnoticed.
@@ -605,6 +710,7 @@ if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.
     // The unattended entry point, called by the post-merge hook. Prints only what it actually did.
     const out = autoReap(root);
     for (const p of out.reaped) process.stdout.write(`rsc: retired worktree ${p}\n`);
+    for (const b of out.branches.deleted) process.stdout.write(`rsc: deleted merged branch ${b}\n`);
   } else if (process.argv[3] === 'reap') {
     const one = process.argv[4];
     const targets = one ? [resolve(one)] : candidates.filter((c) => c.verdict === 'safe').map((c) => c.path);