@ericrisco/rsc 3.4.0 → 3.5.0

package/README.md

@@ -239,7 +239,7 @@ project. rsc handles four things by default:
 | | What happens | Turn it off |
 | --- | --- | --- |
 | **You choose how the project works** | The install asks once: straight on `main`, or branches and pull requests? With branches, a commit on `main` is refused and the agent asks before each change: this branch, a new one, or unlock `main`? It never opens a branch on its own. | «unlock main», or `rsc main unlock` |
-| **One workspace per agent** | If another session works in the same folder, new work goes to `.worktrees/<branch>/`, inside the project and never committed. A `post-merge` hook retires it once the branch lands. | `rsc isolation off` |
+| **One workspace per agent** | If another session works in the same folder, new work goes to `.worktrees/<branch>/` at the root you work in (never inside a project folder) and is never committed. A `post-merge` hook retires it once the branch lands. | `rsc isolation off` |
 | **The agent picks the method** | FTD for simple changes, SDD for complex ones. The agent decides and says why. | Ask for the other lane |
 | **Knowledge reaches everyone** | `01-TOOLS/`, `02-DOCS/wiki/` and `02-DOCS/attachments/` travel through one exchange branch, `rsc/knowledge`, and reach `main` inside your normal pull requests. | `rsc knowledge-sync off` |
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.4.0",
+  "version": "3.5.0",
   "counts": {
     "skills": 269,
     "agents": 34,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "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/rsc.js

@@ -927,7 +927,7 @@ async function main() {
             : 'rsc main lock: branches and pull requests for this project — the default branch is closed for the agent, and it asks before each code change where it goes. Commit .rsc.json so the team gets the same decision.')
           : (sub === OFF
             ? 'rsc isolation off: sessions may share this folder without a worktree. Commit .rsc.json so the team gets the same decision.'
-            : 'rsc isolation on: with another session active in this folder, new work goes to .worktrees/<branch>/. Commit .rsc.json so the team gets the same decision.'));
+            : 'rsc isolation on: with another session active in this folder, new work goes to .worktrees/<branch>/ at the root, never inside a project folder. Commit .rsc.json so the team gets the same decision.'));
         return;
       }
       if (sub === 'status') {

package/skills/ftd/SKILL.md

@@ -73,7 +73,7 @@ says which on every turn) — never a branch opened on your own:
   is no exception: an unrelated change does not go into it without asking. A new branch is named by
   intent and closes with a pull request. Unlocking is `rsc main unlock`; never without that answer.
 - **Docs, wiki or config only** → no question, no branch.
-- **Another session working in this same folder** → a worktree in `.worktrees/<branch>/`, never a
+- **Another session working in this same folder** → a worktree in `.worktrees/<branch>/` at the root you work in (never inside a project folder), never a
   branch switch under the other session. Not a question: rsc tells you when that is the case.
 
 A worktree only when another session is there: alone, setting one up costs more than it protects.

package/skills/worktrees/SKILL.md

@@ -114,11 +114,25 @@ git worktree add -b feat/<slug> .worktrees/<slug> origin/<default-branch>
 # work happens in .worktrees/<slug>; the main checkout is untouched
 ```
 
-**Inside the repo, always — never a sibling.** `.worktrees/` is already gitignored by the harness,
-the reaper already recognises it as its own, and the difference matters after the work lands: a
-sibling directory sits outside the tree, so it survives every cleanup of the repository and stops
-being visible to whoever would retire it. Two of them accumulated here before this was written down.
-Deleting the repo should delete its worktrees with it.
+**At the root you work in, always — never inside a project folder, never a sibling.** The root is
+the folder holding `.rsc.json`. For the repo at that root the worktree is `.worktrees/<slug>`. For a
+project that lives in a folder under it (a workspace with `03-PROJECTS/<p>/`), it is
+`<root>/.worktrees/<p>-<slug>`, and the path is written absolute — a relative one resolves inside
+the project, which is how they ended up there:
+
+```bash
+git -C 03-PROJECTS/<p> fetch origin
+git -C 03-PROJECTS/<p> worktree add -b feat/<slug> <root>/.worktrees/<p>-<slug> origin/<default-branch>
+```
+
+A worktree at the root is a fresh checkout with nothing above it to borrow from: install its
+dependencies inside it (`npm ci`, `uv sync`, …) before running anything. Inside the project, a
+missing `node_modules` was silently taken from the parent; at the root it fails loudly instead.
+
+rsc's branch guard denies any other place, with the right command in its message. `.worktrees/` is
+already gitignored at the root, the reaper recognises both shapes as its own, and a sibling
+directory would sit outside the tree, survive every cleanup and stop being visible to whoever would
+retire it. Deleting the workspace deletes its worktrees with it.
 
 ```bash
 # branch-only path (the degenerate case: no separate directory needed)

package/targets/branch-guard.mjs

@@ -10,13 +10,16 @@
 //   B · another session is working in this same checkout (session-memory-core.mjs). Switching
 //       branches here would change its files under it, so it is denied, and the message says how to
 //       carry on: a worktree under `.worktrees/`.
+//   C · a worktree goes in `.worktrees/` at the root the session works in, never inside a project
+//       folder (Eric, 2026-10-27). In a workspace holding its projects as folders, `git -C <p>
+//       worktree add .worktrees/<b>` resolved inside the project; it is denied with the root's path.
 //
 // Every denial carries its way out (constitution P6). Only what the AGENT runs is seen: a person
 // committing in their own terminal is never touched (spec, P3). FAIL-OPEN: no repo, no git, a module
 // missing, anything unclear → allow. Opt-outs, both PROJECT switches: `.rsc/.no-trunk-guard`
 // («desbloquea main» / `rsc main unlock`) and `.rsc/.no-worktree-isolation` (`rsc isolation off`).
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
-import { isAbsolute, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
@@ -56,6 +59,52 @@ export function pushesTo(seg, trunk) {
   });
 }
 
+export const ADDS_WORKTREE = new RegExp(String.raw`\bgit\s+${GIT_OPTS}worktree\s+add(?![\w-])`);
+
+/** `git worktree add [opts] <path> [<commit-ish>]` → { path, branch } (branch from -b/-B), or null. */
+export function worktreeAddTarget(seg) {
+  const t = tokens(seg.replace(/^.*?\bgit\s+/, '').replace(/^(?:(?:-C|-c)\s+\S+\s+|--\S+\s+)*/, ''));
+  if (t.shift() !== 'worktree' || t.shift() !== 'add') return null;
+  let branch = null;
+  let path = null;
+  for (let i = 0; i < t.length; i++) {
+    if (/^-[bB]$/.test(t[i])) { branch = t[++i] ?? null; continue; }
+    if (t[i] === '--reason') { i++; continue; }
+    if (!t[i].startsWith('-') && path === null) path = t[i];
+  }
+  return path === null ? null : { path, branch };
+}
+
+/** realpath of what exists, with the not-yet-created tail kept: a worktree path does not exist yet. */
+function realish(p) {
+  let head = p;
+  const tail = [];
+  while (!existsSync(head)) { const up = dirname(head); if (up === head) return p; tail.unshift(basename(head)); head = up; }
+  try { return join(realpathSync(head), ...tail); } catch { return p; }
+}
+
+const within = (p, dir) => p === dir || p.startsWith(dir + sep);
+
+/** Rule C: the reason to deny this `worktree add`, or null. Repos outside the root are not judged. */
+export function worktreePlaceDenial({ root, here, seg, at }) {
+  const target = worktreeAddTarget(seg);
+  if (!target) return null;
+  const home = realish(root);
+  if (!within(here, home)) return null;
+  const dest = realish(isAbsolute(target.path) ? target.path : resolve(at, target.path));
+  const place = join(home, '.worktrees');
+  if (within(dest, place) && dest !== place) return null;
+  const slug = (target.branch || basename(dest)).replace(/[\\/]+/g, '-');
+  const b = target.branch ? ` -b ${target.branch}` : '';
+  const rel = relative(home, here).split(sep).join('/');
+  const how = here === home
+    ? `\`git worktree add .worktrees/${slug}${b}\``
+    : `\`git -C ${rel} worktree add ${join(place, `${basename(here)}-${slug}`)}${b}\``;
+  return 'rsc: a worktree goes in `.worktrees/` at the root you work in, never inside a project folder ' +
+    `and never beside it (${dest} is not under ${place}). Create it with ${how} and work inside it; ` +
+    'tell the person that is where the work now runs. To stop rsc judging worktrees: `npx @ericrisco/rsc isolation off`.';
+}
+
 export const unquoted = (command) => command.replace(/"(?:[^"\\]|\\.)*"|'[^']*'/g, '""');
 
 /** Where the git command actually runs: `git -C <dir>`, or a leading `cd <dir> &&`, else the cwd. */
@@ -133,7 +182,7 @@ export async function evaluate({ root, command, cwd, sessionId }) {
   // 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;
+  if (!segs.some((s) => COMMITS_HERE.test(s) || MOVES_BRANCH.test(s) || MOVES_REF.test(s) || PUSHES.test(s) || ADDS_WORKTREE.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
@@ -146,13 +195,19 @@ export async function evaluate({ root, command, cwd, sessionId }) {
     const moves = MOVES_BRANCH.test(seg);
     const movesRef = MOVES_REF.test(seg);
     const pushes = PUSHES.test(seg);
-    if (!commits && !moves && !movesRef && !pushes) continue;
+    const addsWorktree = ADDS_WORKTREE.test(seg);
+    if (!commits && !moves && !movesRef && !pushes && !addsWorktree) continue;
     const at = effectiveDir(raw[i] || seg, dir);
     const git = gitAt(at);
     const top = git('rev-parse', '--show-toplevel');
     if (!top) continue;
     const here = (() => { try { return realpathSync(top); } catch { return top; } })();
 
+    if (addsWorktree && !existsSync(join(root, '.rsc', '.no-worktree-isolation'))) {
+      const reason = worktreePlaceDenial({ root, here, seg, at });
+      if (reason) return reason;
+    }
+
     if (moves) {
       const target = moveTarget(seg, at);
       if (target) {
@@ -237,7 +292,7 @@ async function isolationDenial({ root, here, sessionId, self }) {
   if (!others.length) return null;
   const who = others.map((o) => `${o.target}${o.branch ? ` on "${o.branch}"` : ''}, ${ago(o.updatedAt)}`).join('; ');
   return `Another session is working in this same folder (${who}). Switching branches here would change its files under it. ` +
-    'Work in a worktree instead, inside the project: `git worktree add .worktrees/<branch> -b <branch>` (or without -b for an existing branch) and run everything inside `.worktrees/<branch>/`; tell the person that is where the project now runs. ' +
+    'Work in a worktree instead, in `.worktrees/` at the root (never inside a project folder): `git worktree add .worktrees/<branch> -b <branch>` (or without -b for an existing branch; for a project in a folder, `git -C <project> worktree add <root>/.worktrees/<project>-<branch> -b <branch>`) and run everything inside it; tell the person that is where the project now runs. ' +
     'To turn this rule off for the project: `npx @ericrisco/rsc isolation off`.';
 }
 

package/targets/session-memory-adapter.mjs

@@ -122,8 +122,8 @@ export function isolationContext({ project, here, sessionId, target }) {
   if (!others.length) return '';
   const who = others.map((o) => `${o.target}${o.branch ? ` en «${o.branch}»` : ''}`).join(', ');
   return `rsc · aislamiento: otra sesión está trabajando en esta misma carpeta (${who}). ` +
-    'Cualquier cambio de esta petición se hace en un worktree dentro del proyecto: ' +
-    '`git worktree add .worktrees/<rama> -b <rama>` y se trabaja dentro de `.worktrees/<rama>/`. ' +
+    'Cualquier cambio de esta petición se hace en un worktree en `.worktrees/` de la raíz, nunca dentro de una carpeta de proyecto: ' +
+    '`git worktree add .worktrees/<rama> -b <rama>` (si el proyecto está en una subcarpeta, `git -C <proyecto> worktree add <raíz>/.worktrees/<proyecto>-<rama> -b <rama>`, con la ruta absoluta) y se trabaja dentro. ' +
     'No cambies de rama en esta carpeta. Dile a la persona en una línea dónde estás trabajando, para que ' +
     'abra o levante el proyecto desde allí.';
 }

package/targets/team-safe-start.mjs

@@ -86,6 +86,7 @@ export async function relocateOldWorktrees(root) {
     for (const wt of W.listWorktrees(root)) {
       const path = real(wt.path);
       if (isInside(path, home)) continue; // already inside
+      if (W.atWorkspaceRoot?.(path, home)) continue; // a project folder's worktree, at the workspace root on purpose
       if (W.provenanceOf(root, { ...wt, path }) !== 'rsc') continue;
       if (others(path).length) { left.push(`${path} (una sesión trabaja en él)`); continue; }
       const name = basename(path);

package/targets/worktree-reaper.mjs

@@ -169,13 +169,26 @@ export function listWorktrees(root) {
  * accumulates, nothing is lost), while one the user made by hand that happens to match the
  * convention would be indistinguishable from ours. So one signal alone is `ambiguous`, not `rsc`.
  */
+/**
+ * Where a project folder's worktree goes since 2026-10-27: `<root>/.worktrees/<repo>-<branch>`, at the
+ * workspace root that contains the repo (branch-guard rule C). Named after the repo, in a
+ * `.worktrees/` of an ancestor of the repo — both, or it is not this convention.
+ */
+export function atWorkspaceRoot(p, home) {
+  const parent = dirname(p);
+  if (basename(parent) !== '.worktrees' || !basename(p).startsWith(`${basename(home)}-`)) return false;
+  const ws = dirname(parent);
+  return home.startsWith(ws + sep) && home !== ws;
+}
+
 export function provenanceOf(root, wt) {
   const p = wt.path;
   const home = real(root);
   const inside = (dir) => p === dir || p.startsWith(dir + sep);
   const location = inside(join(home, '.worktrees'))
     || inside(join(home, 'worktrees'))
-    || (dirname(p) === dirname(home) && basename(p).startsWith(`${basename(home)}-`));
+    || (dirname(p) === dirname(home) && basename(p).startsWith(`${basename(home)}-`))
+    || atWorkspaceRoot(p, home);
   const branch = Boolean(wt.branch && RSC_BRANCH.test(wt.branch));
   if (location && branch) return 'rsc';
   if (location || branch) return 'ambiguous';