@ericrisco/rsc 2.2.0 → 3.0.1

package/README.md

@@ -56,6 +56,58 @@ not a pile of whatever an agent happened to install.
 
 ---
 
+## 🛡️ New in 3.0: safe for teams by default
+
+Day one with agents is easy. Day ninety is where harnesses break, especially with several people,
+several assistants and several sessions on one project:
+
+- every machine drifts, and what one person teaches their agent never reaches anyone else;
+- two agents end up working in the same folder and switch branches under each other;
+- someone's agent commits straight to `main` on a project in production;
+- every request gets the same process, whether it is a typo or a new subsystem.
+
+rsc 3.0 fixes all four, by default, with no new commands to learn:
+
+| | What happens | Turn it off |
+| --- | --- | --- |
+| **Main is closed where it matters** | In a project that is complex or in production, the agent never commits on the default branch. It opens a branch on its own (`feat/…`, `fix/…`) and finishes with a pull request. In a project of scripts or research it works on `main`, because a branch there is only ceremony. | Say **«unlock main»**, or `rsc main unlock` |
+| **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` |
+
+**How does it know a project is "complex or in production"?** There are two layers. A hook counts
+what anyone can check: a CI setup, a deployment file (`Dockerfile`, `vercel.json`, `fly.toml`…) or
+at least two people in the last 50 commits. If any of those is there, a commit on the default branch
+is refused before it runs. If none is, the agent decides change by change, using the same rule from
+its skills. If the hook gets it wrong and the project really is simple, «unlock main» opens it for
+the project. That decision is saved in `.rsc.json`, so the whole team gets it.
+
+Every refusal says how to carry on: which branch to open, how to create the worktree, or how to
+unlock. An agent is never left stuck. The rules only see what the **agent** runs; a person
+committing in their own terminal is never touched.
+
+**The first session after upgrading** does three things, once:
+
+- It explains these changes in a few lines.
+- If an agent left commits on a closed `main` that never reached the remote, it moves them to a
+  `rescue/main-<date>` branch and puts `main` back to what the remote has. Nothing is lost.
+- It moves worktrees older versions created next to the project into `.worktrees/`.
+
+```bash
+rsc main status        # open or closed for the agent, and the signals behind it
+rsc main unlock        # this project is simple: the agent may work on main (saved in .rsc.json)
+rsc main lock          # back to the default
+rsc isolation status   # whether another session would send new work to a worktree
+rsc isolation off      # never use worktrees for parallel sessions in this project
+```
+
+> **Limit, stated plainly.** The hook that refuses the commit or the branch switch runs in
+> **Claude Code**, like the other rsc guards. In Codex, Gemini, Cursor and OpenCode the same rules
+> are carried by the skills and by the session memory, which tells the agent that another session is
+> active. They are followed, but no hook enforces them. Knowledge sync works in all five.
+
+---
+
 ## 🤖 For agents: "install this harness"
 
 If you're an AI coding agent (Claude Code, Cursor, Copilot, Codex, Gemini…) and your user
@@ -98,9 +150,9 @@ before anything is written.
 
 ---
 
-## 🛣️ Three lanes, and the harness never picks the expensive one for you
+## 🛣️ Three lanes, and the agent picks the right one for you
 
-<img src="https://raw.githubusercontent.com/ericrisco/rsc-harness/main/site/lanes.svg" alt="The rsc lane decisor: a request is classified into answer (read-only), FTD (the default lane, one feature document) or SDD (the ten-phase chain, which only the user selects)." width="960">
+<img src="https://raw.githubusercontent.com/ericrisco/rsc-harness/main/site/lanes.svg" alt="The rsc lane decisor: the agent classifies each request into answer (read-only), FTD (simple change, one feature document) or SDD (the ten-phase chain for big or complex work, entered by the agent; you approve the spec)." width="960">
 
 Every turn takes exactly one lane, and your agent names the one it took in a line.
 
@@ -111,11 +163,14 @@ Every turn takes exactly one lane, and your agent names the one it took in a lin
 2. **FTD — Fast-Track Development.** The request authorises a change. This is the default for
    ordinary work and needs no ceremony. One feature document per feature holds intent, scope, a
    checklist, the evidence and the next step. Tasks are checked off against observed proof, never
-   against intention. A branch if the work writes code; nothing if it only touches docs or config.
-3. **SDD — the ten-phase chain.** Unchanged, and **the harness never enters it alone.** It proposes
-   the chain only when a durable spec, plan and task list would remove a *substantial* ambiguity —
-   a test of usefulness, not of size — and enters it only when you ask for it or accept that
-   proposal. Size, file count and perceived risk never select it on their own.
+   against intention. For the simple changes.
+3. **SDD — the ten-phase chain.** For the big or complex: several decisions that affect each other,
+   or doubts that change the result. **The agent enters it on its own** — you never have to decide
+   which method to use. Inside, you still decide *what* gets built: you approve the spec and answer
+   the clarifying questions, then choose to review every phase yourself or let it run on autopilot
+   to verified code. Publishing always asks.
+
+The agent says which lane it took and why, in one line. Ask for the other one and it switches.
 
 **Isolation cleans itself up.** When a lane opens a branch or a worktree, you no longer have to
 remember to retire it: a `post-merge` hook does it the moment the work lands on the trunk, on both
@@ -124,10 +179,9 @@ landed and holds nothing unsaved; anything it refuses tells you why. The previou
 agent to run the cleanup at the end of a long phase, and that step was skipped on both features that
 reached it.
 
-Earlier versions routed everything that sounded like building into the chain. That contradicted the
-project's own first rule — friction is proportional to risk — and a harness that interrupts the 80%
-that is harmless gets switched off, which protects nothing. Both lanes are still here; what changed
-is which one you land in by default, and who decides.
+Earlier versions asked you to accept a proposal before entering the chain. People do not want to
+choose a method; they want the work done right. Since 3.0 the agent chooses, and you keep the part
+that is genuinely yours: deciding what is built.
 
 ---
 
@@ -370,6 +424,61 @@ list somebody has to remember to update is a list that goes quietly stale. Decla
 `ownSkills` still works and still reports when someone is missing it.
 
 
+### 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
+protected, or should be; rsc assumes it is.
+
+The knowledge travels through one exchange branch, `rsc/knowledge`, that nobody works on by hand:
+
+```text
+ana    · feat/login     edits 02-DOCS/wiki/api.md ──► rsc/knowledge      (when her turn ends)
+eric   · feat/payments  📥 1 change from Ana        ◄── rsc/knowledge      (before his next message)
+main   · protected      untouched — gets it inside the next merged pull request
+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.
+- **It reaches `main` the normal way.** Your feature branch now carries the team's knowledge, so it
+  arrives in `main` inside the pull request you were going to open anyway. There is no extra pull
+  request from `rsc/knowledge`, and nobody has to merge it.
+- The first time, `rsc/knowledge` is created from the remote's default branch. If someone deletes it,
+  it is created again.
+
+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]`. |
+| 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. |
+| Run where it has no business | No `origin`, no knowledge folders, a rebase in progress, a cloud agent: it stays quiet. |
+
+It is wired into the assistant's own turn hooks (end of turn, new message) in Claude Code, Codex,
+Gemini, Cursor and OpenCode (tested end to end in Claude Code, Codex and OpenCode). The network part runs in the background, so a turn never waits for
+it. It is kept apart from the [local session memory](#new-sessions-pick-up-the-latest-local-work),
+which promises never to touch the network. The first turn says it is on. To turn it off for the
+project:
+
+```bash
+rsc knowledge-sync off      # writes .rsc/.no-knowledge-sync and records it in .rsc.json — commit that
+rsc knowledge-sync status   # active or not, and why
+```
+
+It is a **project** switch, not a personal one: if one person stopped sending, the rest of the team
+would stop seeing their work. For the rest of the 3.0 team defaults, see
+[New in 3.0](#️-new-in-30-safe-for-teams-by-default).
+
 ## 🩹 Something's off? One command
 
 Recognise any of these? They are all the same fix.

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.2.0",
+  "version": "3.0.1",
   "counts": {
     "skills": 270,
     "agents": 33,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "2.2.0",
+  "version": "3.0.1",
   "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/install-apply.js

@@ -23,6 +23,7 @@ import {
   wireMemory, unwireMemory, memoryManagedPaths, memoryModeFor, memoryEnabledForProject, memoryArtifactsPresent,
 } from '../targets/memory.js';
 import { wireUpdate, unwireUpdate, updateManagedPaths, updateArtifactsPresent } from '../targets/update-wiring.js';
+import { wireKnowledge, unwireKnowledge, knowledgeManagedPaths, knowledgeArtifactsPresent } from '../targets/knowledge-wiring.js';
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const CLI_VERSION = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version;
@@ -80,6 +81,9 @@ export function generatedHookFiles({ target, cwd, policy }) {
     join(cwd, '.rsc', 'hook-once.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).
+    join(cwd, '.rsc', 'team-safe-start.mjs'),
+    join(cwd, '.rsc', 'trunk-policy.mjs'),
   ];
   // The danger guard is declared on its own terms (#273): present unless the plan says otherwise,
   // whether or not the code guards are.
@@ -87,6 +91,7 @@ export function generatedHookFiles({ target, cwd, policy }) {
   if (policy?.codeHooks === false) return [...lifecycle, ...danger, 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')];
 }
@@ -98,6 +103,7 @@ export function managedPathsForInstall({ skillIds, agentIds = [], target, home,
   if (policy?.context7 === false) out.push(join(cwd, '.rsc', '.no-context7'));
   if (policy?.memory !== false) out.push(...memoryManagedPaths(target, cwd));
   out.push(...updateManagedPaths(target, cwd));
+  out.push(...knowledgeManagedPaths(target, cwd));
   if (targetHasAgents(target)) {
     const state = readState(paths.stateFile);
     const explicit = [...new Set([...(state.explicitAgents || readManifest(cwd)?.agents || []), ...agentIds])];
@@ -302,6 +308,10 @@ export async function applyInstall({ skillIds = [], agentIds = [], target, home,
   state.memory = { mode: memoryResult.mode, reason: memoryResult.reason, paths: memoryResult.paths };
   const updateResult = wireUpdate(target, cwd);
   state.update = { mode: updateResult.mode, ...(updateResult.reason ? { reason: updateResult.reason } : {}) };
+  // Knowledge sync is its own decision (`.no-knowledge-sync`, checked at runtime) and never part of
+  // the memory, so the memory's policy does not decide it: wired wherever the assistant can run it.
+  const knowledgeResult = wireKnowledge(target, cwd);
+  state.knowledge = { mode: knowledgeResult.mode, reason: knowledgeResult.reason || null, paths: knowledgeResult.paths };
   const context7OptOut = join(cwd, '.rsc', '.no-context7');
   if (policy?.context7 === false) {
     mkdirSync(dirname(context7OptOut), { recursive: true });
@@ -602,6 +612,7 @@ export function removeTargetInstall({ target, home, cwd = process.cwd() }) {
   unwireHook(target, paths);
   unwireMemory(target, cwd);
   unwireUpdate(target, cwd);
+  unwireKnowledge(target, cwd);
   rmSync(paths.stateFile, { force: true });
   const gitignore = join(cwd, '.gitignore');
   if (existsSync(gitignore)) {
@@ -711,9 +722,11 @@ export async function purge({ home, cwd = process.cwd(), withDocs = false, dryRu
       removed.push(...unwireHook(target, paths));
       removed.push(...unwireMemory(target, cwd));
       removed.push(...unwireUpdate(target, cwd));
+      removed.push(...unwireKnowledge(target, cwd));
     } else {
       removed.push(...memoryArtifactsPresent(target, cwd));
       removed.push(...updateArtifactsPresent(target, cwd));
+      removed.push(...knowledgeArtifactsPresent(target, cwd));
     }
     // 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.

package/scripts/rsc.js

@@ -44,7 +44,7 @@ if (['--version', '-v', 'version'].includes(rawArgv[0])) {
 const GLOBAL_VALUE_FLAGS = new Set([
   '--target', '--technical-level', '--accompaniment', '--project-kind', '--goal', '--goal-base64', '--software-scope', '--accept-plan',
 ]);
-const COMMANDS = new Set(['onboard', 'reassess', 'add', 'install', 'consult', 'catalog', 'audit', 'list', 'doctor', 'memory', 'sync', 'backups', 'restore', 'upgrade', 'registry', 'worktrees', 'capabilities', 'sello', 'repair', 'uninstall', 'purge']);
+const COMMANDS = new Set(['onboard', 'reassess', 'add', 'install', 'consult', 'catalog', 'audit', 'list', 'doctor', 'memory', 'knowledge-sync', 'main', 'isolation', 'sync', 'backups', 'restore', 'upgrade', 'registry', 'worktrees', 'capabilities', 'sello', 'repair', 'uninstall', 'purge']);
 function positionalTokens(input) {
   const out = [];
   for (let i = 0; i < input.length; i++) {
@@ -766,6 +766,72 @@ async function main() {
       printContextBudget(report.contextBudget);
       return void say(JSON.stringify({ ...report, contextBudget: undefined }, null, 2));
     }
+    case 'main':
+    case 'isolation': {
+      // team-safe-default: the two switches a person asks the agent for in plain words —
+      // «desbloquea main» / «bloquea main», «no uses worktrees» / «usa worktrees». Both are PROJECT
+      // decisions (recorded in .rsc.json optOuts by the sync below) because one person's answer is
+      // the team's: the default branch is open or closed for every agent working on the repo.
+      const isMain = cmd === 'main';
+      const sub = argv[1] || 'status';
+      const root = process.cwd();
+      const { existsSync, mkdirSync, writeFileSync, rmSync } = await import('node:fs');
+      const { join } = await import('node:path');
+      const marker = join(root, '.rsc', isMain ? '.no-trunk-guard' : '.no-worktree-isolation');
+      const OFF = isMain ? 'unlock' : 'off';
+      const ON = isMain ? 'lock' : 'on';
+      if (sub === OFF || sub === ON) {
+        mkdirSync(join(root, '.rsc'), { recursive: true });
+        if (sub === OFF) writeFileSync(marker, '');
+        else rmSync(marker, { force: true });
+        for (const t of targets) await syncInstalled({ target: t, cwd: root });
+        say(isMain
+          ? (sub === OFF
+            ? 'rsc main unlock: the agent may now work on the default branch in this project. Commit .rsc.json so the team gets the same decision.'
+            : 'rsc main lock: the default branch is closed for the agent again where the project looks complex or in production. 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.'));
+        return;
+      }
+      if (sub === 'status') {
+        if (isMain) {
+          const { trunkPolicy } = await import('../targets/trunk-policy.mjs');
+          return void say(JSON.stringify(trunkPolicy(root), null, 2));
+        }
+        const { otherActiveSessions } = await import('../targets/session-memory-core.mjs');
+        return void say(JSON.stringify({ isolation: existsSync(marker) ? 'off' : 'on', activeSessions: otherActiveSessions({ cwd: root }) }, null, 2));
+      }
+      say(`Use: npx @ericrisco/rsc ${cmd} ${ON}|${OFF}|status`);
+      process.exitCode = 2;
+      return;
+    }
+    case 'knowledge-sync': {
+      // On by default; the switch is a PROJECT decision (`.no-knowledge-sync`, recorded in `.rsc.json`
+      // optOuts by the sync below), because one person off means the team stops seeing their work.
+      const sub = argv[1] || 'status';
+      const root = process.cwd();
+      const { mkdirSync, writeFileSync, rmSync } = await import('node:fs');
+      const { join } = await import('node:path');
+      const marker = join(root, '.rsc', '.no-knowledge-sync');
+      if (sub === 'on' || sub === 'off') {
+        mkdirSync(join(root, '.rsc'), { recursive: true });
+        if (sub === 'off') writeFileSync(marker, '');
+        else rmSync(marker, { force: true });
+        for (const t of targets) await syncInstalled({ target: t, cwd: root });
+        say(sub === 'off'
+          ? 'rsc knowledge-sync off: 01-TOOLS/ and 02-DOCS/ no longer sync on their own in this project. Commit .rsc.json so the team gets the same decision.'
+          : 'rsc knowledge-sync on: 01-TOOLS/ and 02-DOCS/ go up when a turn ends and come down before each message. Commit .rsc.json so the team gets the same decision.');
+        return;
+      }
+      if (sub === 'status') {
+        const { knowledgeStatus } = await import('../targets/knowledge-sync.mjs');
+        return void say(JSON.stringify(knowledgeStatus(root), null, 2));
+      }
+      say('Use: npx @ericrisco/rsc knowledge-sync on|off|status');
+      process.exitCode = 2;
+      return;
+    }
     case 'memory': {
       const sub = argv[1] || 'status';
       const root = process.cwd();

package/skills/ftd/SKILL.md

@@ -53,10 +53,16 @@ the chain: a result asserted without evidence is treated as not done.
 
 ## Isolation
 
-If the work writes code, it runs on a branch — never on the default branch, so `origin` and the local
-tree stay clean. **No worktree**: this lane is short enough that setting one up and tearing it down
-costs more than it protects. Work that only touches documentation, the wiki or configuration needs no
-branch at all.
+Where the work runs depends on the project, judged change by change (team-safe-default):
+
+- **Complex or in production** (deploys, CI, several people committing, a protected default branch)
+  → a branch, never the default branch. Open it yourself, named by intent, and close it with a pull
+  request. Something unrelated to the current branch gets its own branch from the default one.
+- **Simple** (scripts, research, personal) → the default branch is fine.
+- **Another session working in this same folder** → a worktree in `.worktrees/<branch>/`, never a
+  branch switch under the other session. 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.
 
 `../worktrees/SKILL.md` owns the isolation mechanics if you need them. Once the branch lands, the
 cleanup is automatic and you do not run anything.

package/skills/ftd/evals/cases.yaml

@@ -34,7 +34,7 @@ should_not_trigger:
 
   - prompt: "No tengo claro si los permisos van por rol o por recurso, y afecta al esquema, a la API y a la UI."
     route_to: "specify"
-    why: "A substantial unresolved ambiguity that durable spec/plan/tasks would settle. The harness proposes the chain here; only an explicit request or an accepted proposal enters it."
+    why: "A substantial unresolved ambiguity that durable spec/plan/tasks would settle. Several interlocking decisions: the agent enters the chain itself and says why (team-safe-default)."
 
   - prompt: "Quiero especificar bien el sistema de permisos antes de tocar nada."
     route_to: "specify"

package/skills/ftd/evals/routing.json

@@ -3,7 +3,7 @@
   "lanes": {
     "answer": "information only; writes nothing, creates no artifact",
     "ftd": "authorised change, ordinary; one feature document",
-    "sdd": "the ten-phase chain, by explicit request or accepted proposal only"
+    "sdd": "the ten-phase chain, entered by the agent for big or complex work"
   },
   "cases": [
     { "request": "¿Por qué el login tarda tanto en producción?", "expect": "answer", "why": "investigation; nothing authorises a change" },
@@ -19,6 +19,6 @@
     { "request": "Migra los tres endpoints al nuevo formato de respuesta", "expect": "ftd", "why": "many files, but nothing a spec would settle that the code does not" },
     { "request": "Quiero especificar bien el sistema de permisos antes de tocar nada", "expect": "sdd", "why": "explicit request for the chain" },
     { "request": "Vamos a hacer una spec de esto", "expect": "sdd", "why": "explicit request, stated in the user's own words" },
-    { "request": "No tengo claro si los permisos van por rol o por recurso, y afecta al esquema, a la API y a la UI", "expect": "sdd", "why": "propose the chain: durable artifacts would settle a substantial ambiguity, and only an accepted proposal enters it" }
+    { "request": "No tengo claro si los permisos van por rol o por recurso, y afecta al esquema, a la API y a la UI", "expect": "sdd", "why": "enter the chain: several interlocking decisions that durable artifacts would settle; the agent enters it and says why" }
   ]
 }

package/skills/ship/SKILL.md

@@ -93,6 +93,12 @@ This mirrors the harness "siempre 3 opciones" pattern. Gather the one fact that
 | **2. Pull request** | Push the branch, open a PR with a spec-linked body, let CI / a human gate the merge | `main` is protected; a team or CI must sign off; you want the change reviewable in the forge even if you self-merge |
 | **3. Park or discard** | Keep the branch un-merged (park) or delete it (discard) | The approach was superseded, the spike answered its question, or the work is paused — it should not land |
 
+**When the default branch is closed for the agent** (team-safe-default: the project is complex or in
+production — `npx @ericrisco/rsc main status` says `closed: true`), **option 1 is not offered**: a
+local merge is a commit on the default branch. Present option 2 (the recommendation) and option 3,
+and say in one line why option 1 is absent and that «desbloquea main» (`npx @ericrisco/rsc main
+unlock`) would bring it back. The branch guard denies the local merge anyway.
+
 Recommend based on repo signals: protected `main` or an existing PR culture (look for `.github/`, prior PRs via `gh pr list`) → recommend **option 2**. A solo project with no protection and a passed review → **option 1** is honest and faster. Never default to a PR ceremony the repo doesn't use, and never force-merge a repo that gates `main`.
 
 ### Delivery strategy from SDD config

package/skills/suggest/SKILL.md

@@ -26,15 +26,15 @@ recommend. Read-only: write nothing, create no artifact, delegate no writer. Ask
 about* building something is still this lane; only asking to build authorises it. When change
 intent is ambiguous, ask one question and stay here — ambiguity slows the lane, never raises it.
 
-**FTD — Fast-Track Development** — the request authorises a change. The default for ordinary work,
-entered without ceremony. One feature document per feature in `02-DOCS`: intent, scope, checklist,
-evidence, next step. Tasks are checked off against observed proof, never intention. A branch if it
-writes code, none if it only touches docs, wiki or config; never a worktree. → `../ftd/SKILL.md`.
-
-**SDD** — the ten-phase chain, unchanged, and **never entered by the harness alone**. Propose it only
-when durable spec/plan/tasks would remove a *substantial* ambiguity — a test of usefulness, not of
-size — and enter it only on explicit request or an accepted proposal. Size, file count and perceived
-risk never select it. → `../sdd/SKILL.md`.
+**You choose the lane; never hand that choice to the person.** Simple → **FTD**: one feature document
+in `02-DOCS` (intent, scope, checklist, evidence, next step), tasks checked off against observed proof.
+Big, or decisions that affect each other → **SDD**: enter the chain; the person approves the spec and
+clarify, then picks manual or autopilot. Say which and why in one line; switch if asked.
+→ `../ftd/SKILL.md` · `../sdd/SKILL.md`.
+
+**Where.** Complex or in production → never commit on the default branch: branch yourself, close with
+a PR. Simple → the default branch. Another session in this checkout → `.worktrees/<branch>`. «desbloquea
+main» = `rsc main unlock`; «no uses worktrees» = `rsc isolation off`.
 
 Judge the **meaning**, not the wording: the trigger is semantic in any language. A bug fix restoring
 intended behaviour is `debug`. Autopilot consent covers a whole run — advance without re-asking.

package/skills/worktrees/SKILL.md

@@ -44,6 +44,7 @@ Both isolate history. A worktree also isolates the *filesystem*. Pick by what's
 | You'll run two streams of work at once (see the parallel pattern) | **worktree** | Each stream gets its own directory; no stash-juggling, no checkout thrash. |
 | The current tree is dirty and the user wants both the WIP and the new work | **worktree** | Stash-and-switch risks losing the WIP; a worktree sidesteps the stash entirely. |
 | You're an agent that may keep the main session running elsewhere | **worktree** | Filesystem isolation is the whole point — the parent session keeps its files. |
+| **Another session is working in this same folder** (rsc says so on each message) | **worktree — mandatory** | Switching branches would change its files under it; rsc's branch guard denies the switch. Tell the person that `.worktrees/<branch>/` is where the project now runs. Off for the project: `npx @ericrisco/rsc isolation off`. |
 
 When in doubt, prefer a **worktree**: it is the strictly stronger isolation and the cost is one
 extra directory. The rest of this skill assumes a worktree; the branch path is the degenerate case

package/targets/branch-guard.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// rsc Branch guard (claude). Wired by targets/claude.js onto PreToolUse (matcher Bash) as
+// `node ...`, like ship-guard. argv[2] = project root · stdin = PreToolUse hook JSON.
+//
+// Two rules from team-safe-default, each the deterministic floor of something the skills decide:
+//
+//   A · the default branch is closed for the agent where the project shows it is complex or in
+//       production (trunk-policy.mjs). A commit or a merge there is denied, and the message says
+//       how to carry on: a branch, or — if the project is in fact simple — the person unlocking it.
+//   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/`.
+//
+// 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 { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+function allow() { process.exit(0); }
+function deny(reason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason },
+  }));
+  process.exit(0);
+}
+
+const GIT_OPTS = String.raw`(?:(?:-C\s+\S+|-c\s+\S+|--(?:work-tree|git-dir|namespace)\s+\S+|--\S+)\s+)*`;
+export const COMMITS_HERE = new RegExp(String.raw`\bgit\s+${GIT_OPTS}(?:commit|merge|cherry-pick|revert|am)(?![\w-])`);
+// 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|$)))`);
+
+export const unquoted = (command) => command.replace(/"(?:[^"\\]|\\.)*"|'[^']*'/g, '""');
+
+/** Where the git command actually runs: `git -C <dir>`, or a leading `cd <dir> &&`, else the cwd. */
+export function effectiveDir(command, base) {
+  const c = command.match(/\bgit\s+(?:-c\s+\S+\s+)*-C\s+("[^"]+"|'[^']+'|\S+)/);
+  const d = command.match(/^\s*cd\s+("[^"]+"|'[^']+'|\S+)\s*&&/);
+  const raw = (c || d)?.[1]?.replace(/^["']|["']$/g, '');
+  if (!raw) return base;
+  return isAbsolute(raw) ? raw : resolve(base, raw);
+}
+
+const gitAt = (dir) => (...args) => {
+  const r = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
+  return r.status === 0 ? (r.stdout || '').trim() : null;
+};
+
+const ago = (iso) => {
+  const min = Math.max(0, Math.round((Date.now() - new Date(iso).getTime()) / 60000));
+  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());
+}
+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 .`). */
+function moveTarget(seg, dir) {
+  const t = tokens(seg.replace(/^.*?\bgit\s+/, '').replace(/^(?:(?:-C|-c)\s+\S+\s+|--\S+\s+)*/, ''));
+  const verb = t.shift();
+  const create = t.findIndex((x) => /^-[cCbB]$/.test(x));
+  if (create >= 0) return { name: t[create + 1] || null, created: true };
+  const name = t.find((x) => !x.startsWith('-'));
+  if (!name) return { name: null, created: false };
+  if (verb === 'checkout' && (name === '.' || (existsSync(resolve(dir, name)) && !gitAt(dir)('rev-parse', '--verify', '--quiet', `refs/heads/${name}`)))) return null;
+  return { name, created: false };
+}
+
+/**
+ * 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
+ * merge feat/x` is a merge on main (judged as one). `cd` and `git -C` move the folder being judged.
+ */
+export async function evaluate({ root, command, cwd, sessionId }) {
+  if (typeof command !== 'string' || !command) 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));
+  const segs = raw.map(unquoted);
+  let dir = cwd || root;
+  const branchAt = new Map(); // toplevel → branch the chain has moved it to
+
+  for (let i = 0; i < segs.length; i++) {
+    const seg = segs[i];
+    const cd = (raw[i] || seg).match(/^\s*cd\s+("[^"]+"|'[^']+'|\S+)\s*$/);
+    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 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 (moves) {
+      const target = moveTarget(seg, at);
+      if (target) {
+        if (!existsSync(join(root, '.rsc', '.no-worktree-isolation'))) {
+          const reason = await isolationDenial({ root, here, sessionId, self });
+          if (reason) return reason;
+        }
+        if (target.name) branchAt.set(here, target.name);
+      }
+    }
+
+    if (commits && !existsSync(join(root, '.rsc', '.no-trunk-guard'))) {
+      try {
+        const { trunkPolicy, defaultBranchName } = await import(self('./trunk-policy.mjs'));
+        const branch = branchAt.get(here) ?? git('symbolic-ref', '--quiet', '--short', 'HEAD');
+        const trunk = defaultBranchName(here);
+        if (branch && trunk && branch === trunk) {
+          const policy = trunkPolicy(here);
+          if (policy.closed) return await trunkDenial({ root, here, sessionId, self, trunk, policy });
+        }
+      } catch { /* policy module missing → nothing to enforce */ }
+    }
+  }
+  return null;
+}
+
+async function othersHere({ root, here, sessionId, self }) {
+  try {
+    const { otherActiveSessions } = await import(self('./session-memory-core.mjs'));
+    return otherActiveSessions({ cwd: root, worktreeCwd: here, sessionId, target: 'claude' });
+  } catch { return []; } // no memory module → no detection
+}
+
+async function trunkDenial({ root, here, sessionId, self, trunk, policy }) {
+  // Where the branch goes depends on rule B: alone → this same folder; with company → .worktrees/.
+  const others = existsSync(join(root, '.rsc', '.no-worktree-isolation')) ? [] : await othersHere({ root, here, sessionId, self });
+  const where = others.length
+    ? 'Another session is working in this folder, so open it as a worktree inside the project: `git worktree add .worktrees/<branch> -b feat/<what-you-are-doing>` and commit inside `.worktrees/<branch>/`'
+    : 'You are the only session here, so stay in this same folder, no worktree: `git switch -c feat/<what-you-are-doing>` (or fix/…, docs/…) and commit there';
+  return `This project keeps its default branch "${trunk}" closed for the agent (it looks complex or in production: ${policy.signals.join(', ')}). ` +
+    `Do this work on a branch instead. ${where}; it reaches "${trunk}" through a pull request. ` +
+    'If this project is actually simple and the person asks to unlock it, run `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;
+  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. ' +
+    'To turn this rule off for the project: `npx @ericrisco/rsc isolation off`.';
+}
+
+function isMain(metaUrl) {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  const me = fileURLToPath(metaUrl);
+  try { return realpathSync(me) === realpathSync(invoked); } catch { return me === invoked; }
+}
+
+if (isMain(import.meta.url)) {
+  const root = process.argv[2] || process.cwd();
+  if (!existsSync(join(root, '.git'))) allow();
+  let input = {};
+  try { input = JSON.parse(readFileSync(0, 'utf8') || '{}'); } catch { allow(); }
+  if ((input.tool_name || input.toolName) !== 'Bash') allow();
+  const command = input.tool_input?.command || input.toolInput?.command || '';
+  const reason = await evaluate({ root, command, cwd: input.cwd || root, sessionId: input.session_id });
+  if (reason) deny(reason);
+  allow();
+}