@ericrisco/rsc 2.1.0 → 3.0.0

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.
 
 ---
 
@@ -355,8 +409,9 @@ pinned version. It asks; it does not install anything on its own and it does not
 whatever you sat down to do. Say no and it stops asking on that machine.
 
 Not `@latest`, and the difference is the whole point of sharing: a teammate who clones in three
-months gets what you had, not what shipped since. Upgrading is something a person decides, writes
-into `.rsc.json`, and commits — and then it reaches everyone through git, like any other change.
+months gets what you had, not what shipped since. Once it is built, the same rules as any project
+apply: releases in the same major install themselves (see [Update](#update)), and the new
+`catalogVersion` in `.rsc.json` reaches everyone when somebody commits it.
 
 When someone changes the harness and you `git pull`, `rsc doctor` tells you what no longer
 matches. **Nothing is ever written to your machine by a pull** — you are told, and you decide.
@@ -369,6 +424,59 @@ 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`.
+- **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 its own snapshot of the knowledge folders goes up. 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.
@@ -403,8 +511,26 @@ so rsc does not repair, move or delete them — not even when rebuilding from sc
 
 ## Update
 
-`rsc` is an npm package, so updating is two steps — bump the package, then
-re-sync what's already wired into your project:
+**rsc updates itself.** When a session starts, rsc checks npm for a newer version:
+
+- **Same major** (`2.1.0 → 2.1.1` or `2.2.0`): it installs that exact version in the background.
+  It takes effect in the next session, and that session tells you it happened.
+- **New major** (`2.x → 3.0.0`): it can change how the harness works, so the assistant asks first.
+- **Failed:** the assistant asks instead, and rsc retries once a day. The output is in
+  `.rsc/auto-update.log`.
+
+A new install asks whether you want this (yes by default). To turn it off later, create
+`.rsc/.no-auto-update`; every release then asks. It is a project decision: it travels in
+`.rsc.json` like the other switches. The update can leave harness files changed in git; rsc never
+commits them for you.
+
+Where it runs on its own: **Claude Code, Codex, Gemini CLI, Cursor and OpenCode**, from a
+session-start hook. Every other assistant has no such hook, so the always-on instructions ask the
+agent to run `node .rsc/auto-update.mjs` on its first turn — same rules, but it depends on the agent
+doing it (and some assistants ask your permission before running a command). Codex asks you to
+trust new hooks once.
+
+To update by hand, bump the package, then re-sync what's already wired into your project:
 
 ```bash
 npm install -g @ericrisco/rsc@latest   # global install: pull the newest catalog

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.1.0",
+  "version": "3.0.0",
   "counts": {
     "skills": 270,
     "agents": 33,

package/package.json

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

@@ -22,6 +22,8 @@ import {
 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;
@@ -78,6 +80,10 @@ export function generatedHookFiles({ target, cwd, policy }) {
     join(cwd, '.rsc', 'worklog-checkpoint.mjs'),
     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.
@@ -85,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')];
 }
@@ -95,6 +102,8 @@ export function managedPathsForInstall({ skillIds, agentIds = [], target, home,
   const out = [paths.stateFile, versionFile(cwd), baseVersionsFile(cwd)];
   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])];
@@ -297,6 +306,12 @@ export async function applyInstall({ skillIds = [], agentIds = [], target, home,
     ? { mode: 'disabled', reason: 'onboarding-policy', paths: unwireMemory(target, cwd) }
     : wireMemory(target, cwd);
   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 });
@@ -596,6 +611,8 @@ 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)) {
@@ -704,8 +721,12 @@ export async function purge({ home, cwd = process.cwd(), withDocs = false, dryRu
     if (!dryRun) {
       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/init/SKILL.md

@@ -137,7 +137,7 @@ cargan al arrancar la sesión."* Full skill map and sample printouts → `refere
 
 ### Phase 4 — GROUND
 
-Four checks once the skills are in. The SessionStart hook nudges each of these too; doing them here
+Five checks once the skills are in. The SessionStart hook nudges each of these too; doing them here
 means the user starts clean.
 
 1. **Version control.** No `.git/` → offer `git init`; the SDD chain and the ship guard assume it.
@@ -154,6 +154,15 @@ means the user starts clean.
    `WHERE`, `dd` to a device, `curl | bash` — and asks for a safer alternative. A fully `technical`
    user is never guarded. It turns off only if the user explicitly asks: `.rsc/.no-danger-guard`.
    Mention it when you record `non-technical`, so a later block is not a surprise.
+5. **Automatic updates.** Ask once, yes by default:
+   > *"Cuando salga una versión nueva de rsc, ¿la instalo sola? Las que cambian mucho (major) te las
+   > preguntaré siempre. (sí/no)"*
+
+   > *"When a new rsc version comes out, should I install it on my own? Big ones (major) I will
+   > always ask about. (yes/no)"*
+
+   Yes, or no clear answer → do nothing; it is on. No → create `.rsc/.no-auto-update`: every
+   release then asks. It is a project switch, recorded in `.rsc.json` on the next sync.
 
 ### Phase 5 — HANDOFF
 

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/_md-block.js

@@ -13,6 +13,12 @@ const MARK_END = '<!-- rsc-suggest:end -->';
 // The exact separator wireHook writes before an appended block, so unwireHook can take
 // back precisely what it gave and leave the rest of the file untouched.
 const SEAM = '\n\n';
+// Most assistants that read a rules file have no session-start hook, so nothing checks for a new rsc
+// on its own. The agent does it instead. Here and not in suggest's body: the body is paid on every
+// turn by every assistant, Claude Code included, which already checks from its hook.
+export const UPDATE_NOTE = '**rsc updates.** Claude Code, Codex, Gemini CLI, Cursor and OpenCode check for a new rsc on their '
+  + 'own. In any other assistant, run `node .rsc/auto-update.mjs` once on the first turn of a session and relay any '
+  + 'notice it prints in one line; "up to date" needs no mention.\n';
 
 export function writeSkill(id, fromDir, toPath) {
   return linkOrCopy(fromDir, toPath);
@@ -23,7 +29,7 @@ export function wireHook(paths, sourceMd, policy = {}) {
   const body = policy.codeHooks === false
     ? `# rsc-suggest — always-on operations layer\n\nRead \`02-DOCS/wiki/harness/user-profile.md\` before acting. Use \`orient\` to keep the user situated and \`suggest\` to offer a missing skill only when the current task needs it. Close with the configured orientation block.\n`
     : full;
-  const block = `${MARK_START}\n${body}\n${MARK_END}`;
+  const block = `${MARK_START}\n${body}\n${UPDATE_NOTE}\n${MARK_END}`;
   let doc = existsSync(paths.hookTarget) ? readFileSync(paths.hookTarget, 'utf8') : '';
   if (doc.includes(MARK_START)) {
     doc = doc.replace(new RegExp(`${MARK_START}[\\s\\S]*?${MARK_END}`), block);