@ericrisco/rsc 3.0.3 → 3.0.4

package/README.md

@@ -70,7 +70,7 @@ 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` |
+| **You decide where each change goes** | Before every change that writes code, the agent asks: a new branch, or straight on `main`? It never opens a branch on its own. In a project that is complex or in production (CI, a deployment, several people), a commit on `main` is refused, and the agent asks whether to open a branch or unlock `main`. | 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` |
@@ -99,12 +99,12 @@ rsc git-permissions on       # turn it on, also for a project adopted before
 **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
+is refused before it runs, and the agent asks you whether to open a branch or unlock it. If none is,
+`main` is open, and the agent still asks before each change whether you want a branch. 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
+Every refusal says how to carry on, and the choice between a branch and unlocking goes back to you.
+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:
@@ -467,6 +467,8 @@ new    · clones main    has it all after the first message
   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.
+  A branch you open later catches up on its first message: everything on `rsc/knowledge` since it
+  left `main` comes down, including what you wrote yourself on another branch.
 - **It reaches `main` the normal way.** Your feature branch now carries the team's knowledge, so it
   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.

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.0.3",
+  "version": "3.0.4",
   "counts": {
     "skills": 270,
     "agents": 33,
@@ -1911,7 +1911,7 @@
     },
     {
       "id": "ftd",
-      "description": "Use for ordinary authorised change — the default lane once the decisor has ruled out a question and not selected the chain. Keeps one feature document per feature in 02-DOCS holding intent, scope, checklist, evidence and next step, checks tasks off only against observed proof, and branches when the work writes code. NOT the ten-phase chain (that is `sdd`), NOT the classification itself (that is the decisor in `suggest`), NOT a request for information, which writes nothing.",
+      "description": "Use for ordinary authorised change — the default lane once the decisor has ruled out a question and not selected the chain. Keeps one feature document per feature in 02-DOCS holding intent, scope, checklist, evidence and next step, checks tasks off only against observed proof, and asks whether to branch before the work writes code. NOT the ten-phase chain (that is `sdd`), NOT the classification itself (that is the decisor in `suggest`), NOT a request for information, which writes nothing.",
       "tags": [
         "ftd",
         "lane",

package/package.json

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

package/skills/ftd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ftd
-description: "Use for ordinary authorised change — the default lane once the decisor has ruled out a question and not selected the chain. Keeps one feature document per feature in 02-DOCS holding intent, scope, checklist, evidence and next step, checks tasks off only against observed proof, and branches when the work writes code. NOT the ten-phase chain (that is `sdd`), NOT the classification itself (that is the decisor in `suggest`), NOT a request for information, which writes nothing."
+description: "Use for ordinary authorised change — the default lane once the decisor has ruled out a question and not selected the chain. Keeps one feature document per feature in 02-DOCS holding intent, scope, checklist, evidence and next step, checks tasks off only against observed proof, and asks whether to branch before the work writes code. NOT the ten-phase chain (that is `sdd`), NOT the classification itself (that is the decisor in `suggest`), NOT a request for information, which writes nothing."
 tags: [ftd, lane, default, feature-document, evidence]
 recommends: [worktrees, debug, verify]
 profiles: [minimal, core, full]
@@ -53,14 +53,16 @@ the chain: a result asserted without evidence is treated as not done.
 
 ## Isolation
 
-Where the work runs depends on the project, judged change by change (team-safe-default):
+Where the work runs is the person's call, asked change by change — never a branch opened on your own:
 
-- **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.
+- **Before each change that writes code**, ask in one line: «¿Lo hago en una rama nueva o directamente
+  en `<default branch>`?». A branch is named by intent and closes with a pull request.
+- **Default branch closed for the agent** (rsc refuses the commit there: CI, a deployment or several
+  people committing) → ask: «¿Abro una rama o desbloqueo `<default branch>`?». Unlocking is
+  `rsc main unlock`, a project decision; never run it 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
-  branch switch under the other session. rsc tells you when that is the case.
+  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/implement/SKILL.md

@@ -45,9 +45,9 @@ back — you do not write feature code anyway.
 4. **Read the register.** Open `02-DOCS/wiki/harness/user-profile.md` and read `technical_level`.
    It picks technical terms or plain words with analogies at each checkpoint (see "Checkpoints"
    below). No profile yet → use analogies, and ask before any irreversible step.
-5. **Confirm isolation.** Implementation happens on a feature branch or worktree, never directly on
-   the default branch. If you are on `main`/`master`, stop and hand to `worktrees` before the first
-   commit.
+5. **Confirm isolation.** On `main`/`master`, stop before the first commit and ask the person: a
+   feature branch, or straight on the default branch (`worktrees`)? Never branch on your own; another
+   session in this folder makes the worktree mandatory.
 6. **Scan the tasks for independence.** Mark which tasks share files/state and which are disjoint.
    Disjoint clusters are candidates for `parallel`; everything else runs in order.
 
@@ -314,7 +314,7 @@ outranks the plan, and the plan outranks your in-the-moment preference.
 - **Unresolved `analyze` findings** (contradiction between constitution ↔ spec ↔ plan ↔ tasks) →
   resolve them before any code; they will only get more expensive after the diff exists.
 - **A task forces a constitution violation** → surface it, stop, kick it back to `analyze`/`plan`.
-- **You're on the default branch** → stop before the first commit; hand to `worktrees`.
+- **You're on the default branch** → stop before the first commit and ask: branch or default branch (`worktrees`).
 - **A test won't go red** (wrong reason — import error, syntax) → fix the test before trusting it.
 - **The combined suite is red after a parallel merge** → do not checkpoint as done; debug with
   `debug` before continuing.

package/skills/suggest/SKILL.md

@@ -32,9 +32,9 @@ Big, or decisions that affect each other → **SDD**: enter the chain; the perso
 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`.
+**Where.** Before each change that writes code, ask: a branch, or straight on the default branch? Never
+branch on your own. Default branch closed (CI, deploy, team) → ask: a branch, or `rsc main unlock`?
+Another session in this checkout → `.worktrees/<branch>`; «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

@@ -27,11 +27,12 @@ constitution → specify → clarify → plan → tasks → analyze → [ worktr
 
 ## The one rule that defines this step
 
-**Never run `implement` on the default branch.** The moment a plan is about to become commits, the
-work belongs in isolation. If `git rev-parse --abbrev-ref HEAD` says `main` or `master`, you stop
-and create the isolated workspace *first* — before the first edit, not after the diff already exists
-on the wrong branch. Recovering a half-built feature off `main` is strictly more expensive than
-branching one command earlier.
+**Never run `implement` on the default branch without asking.** The moment a plan is about to become
+commits, if `git rev-parse --abbrev-ref HEAD` says `main` or `master`, you stop and ask the person
+*first* — «¿rama nueva o directamente en `main`?» — before the first edit, not after the diff already
+exists. Never branch on your own; if rsc refuses commits there (closed default branch), the question
+is «¿abro una rama o desbloqueo `main`?». The one exception is another session in this folder: then
+the worktree is mandatory, not a question.
 
 ## The decision: branch vs. worktree
 

package/targets/branch-guard.mjs

@@ -152,14 +152,16 @@ async function othersHere({ root, here, sessionId, self }) {
 }
 
 async function trunkDenial({ root, here, sessionId, self, trunk, policy }) {
-  // Where the branch goes depends on rule B: alone → this same folder; with company → .worktrees/.
+  // Where a branch would go depends on rule B: alone → this same folder; with company → .worktrees/.
+  // Whether to branch at all is the person's call: the agent asks, it never branches on its own.
   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).';
+  const branch = others.length
+    ? '`git worktree add .worktrees/<branch> -b feat/<what>` and commit inside `.worktrees/<branch>/` (another session is working in this folder)'
+    : '`git switch -c feat/<what>` in this same folder, no worktree';
+  return `This project keeps its default branch "${trunk}" closed for the agent (it looks complex or in production: ${policy.signals.join(', ')}), so this commit was not made. ` +
+    `Do not choose for the person: ask them in one line whether to open a branch for this change or to unlock "${trunk}". ` +
+    `Branch → ${branch}; it reaches "${trunk}" through a pull request. ` +
+    'Unlock → only on their explicit answer, `npx @ericrisco/rsc main unlock` (a project decision, saved in .rsc.json), then commit again.';
 }
 
 async function isolationDenial({ root, here, sessionId, self }) {

package/targets/hook-once.mjs

@@ -97,8 +97,8 @@ Classify this turn before acting, and name the lane in one line.
 - Authorises a change? YOU pick the lane, say it and why: simple -> FTD (one
   feature document, tasks checked off against observed proof); big or
   interlocking decisions -> SDD (spec + clarify approved, then autopilot or not).
-- Complex/production: no commits on the default branch, branch + PR. Simple:
-  default branch. Another session here: .worktrees/<branch>.
+- Code change? Ask first, every time: a branch or the default branch? Never
+  branch on your own. Another session here: .worktrees/<branch>.
 Method: \`ftd\` · chain: \`sdd\` · full decisor in the always-on \`suggest\` body.
 =================================================
 `;

package/targets/knowledge-sync.mjs

@@ -104,7 +104,7 @@ const worktreeBlob = (root, path) => (existsSync(join(root, path)) ? line(root,
 function readState(root) {
   let s = {};
   try { s = JSON.parse(readFileSync(join(root, '.rsc', STATE), 'utf8')); } catch { /* first run */ }
-  return { announced: false, seen: null, queue: [], ours: [], notices: [], lastFetch: 0, snap: null, head: null, ...s };
+  return { announced: false, seenBy: {}, queue: [], ours: [], notices: [], lastFetch: 0, snap: null, head: null, ...s };
 }
 
 function writeState(root, s) {
@@ -375,30 +375,35 @@ export function applyIncoming(root, s) {
   if (!branch || branch === 'HEAD') return said;
   const tip = line(root, ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${KNOWLEDGE_BRANCH}`]);
   if (!tip) return said;
-  if (!s.seen || !line(root, ['rev-parse', '--verify', '--quiet', `${s.seen}^{commit}`])) {
-    s.seen = line(root, ['merge-base', 'HEAD', tip]) || tip;
+  // Per branch, not per repo: a branch opened from main after the last sync starts behind what
+  // rsc/knowledge already has, and a single "last seen" made it look up to date (2026-10-06). A branch
+  // seen for the first time catches up from where it left rsc/knowledge.
+  s.seenBy = s.seenBy && typeof s.seenBy === 'object' ? s.seenBy : {};
+  let seen = s.seenBy[branch];
+  if (!seen || !line(root, ['rev-parse', '--verify', '--quiet', `${seen}^{commit}`])) {
+    seen = line(root, ['merge-base', 'HEAD', tip]) || tip;
   }
-  if (s.seen === tip) return said;
+  if (seen === tip) { s.seenBy[branch] = tip; return said; }
   const paths = [...KNOWLEDGE];
-  const theirs = git(root, ['rev-list', `${s.seen}..${tip}`, '--', ...paths]).split('\n').filter(Boolean)
-    .filter((c) => !s.ours.includes(c));
-  if (!theirs.length) { s.seen = tip; return said; }
+  const commits = git(root, ['rev-list', `${seen}..${tip}`, '--', ...paths]).split('\n').filter(Boolean);
+  if (!commits.length) { s.seenBy[branch] = tip; return said; }
 
-  const know = zlist(git(root, ['diff', '--name-only', '--no-renames', '-z', s.seen, tip, '--', ...paths]))
+  const know = zlist(git(root, ['diff', '--name-only', '--no-renames', '-z', seen, tip, '--', ...paths]))
     .filter(isKnowledge).slice(0, MAX_FILES);
-  const who = authorsOf(root, theirs);
   const closed = branch === defaultBranch(root) && trunkClosed(root);
+  const touchedBy = (f) => git(root, ['rev-list', `${seen}..${tip}`, '--', f]).split('\n').filter(Boolean);
   const take = [];
   const clash = [];
   for (const f of know) {
     const incoming = blob(root, tip, f);
     const mine = worktreeBlob(root, f);
     if (mine === incoming) continue;
-    const base = blob(root, s.seen, f);
+    const base = blob(root, seen, f);
     // On a closed trunk HEAD lags behind on purpose (what came in was not committed), so only the
     // working tree says whether you touched it (review H2).
     if (mine === base && (closed || blob(root, 'HEAD', f) === base)) take.push(f);
-    else clash.push(f);
+    // Touched here and changed only by your own uploads: your newer version, not a clash.
+    else if (touchedBy(f).some((c) => !s.ours.includes(c))) clash.push(f);
   }
 
   if (take.length) {
@@ -414,12 +419,16 @@ export function applyIncoming(root, s) {
     } else {
       git(root, ['--literal-pathspecs', 'reset', '--quiet', '--', ...take]); // updated, not staged
     }
-    said.push(`📥 Traídos ${theirs.length} cambio(s) de conocimiento de ${who}: ${listed(take)}.`);
+    const from = [...new Set(take.flatMap(touchedBy))];
+    const theirs = from.filter((c) => !s.ours.includes(c));
+    const who = theirs.length ? authorsOf(root, theirs) : 'ti, desde otra rama';
+    said.push(`📥 Traídos ${from.length} cambio(s) de conocimiento de ${who}: ${listed(take)}.`);
   }
   if (clash.length) {
+    const who = authorsOf(root, [...new Set(clash.flatMap(touchedBy))].filter((c) => !s.ours.includes(c)));
     said.push(`${who} cambió ${listed(clash)}, que tú también has tocado. No lo traigo solo: tu versión sigue intacta.`);
   }
-  s.seen = tip;
+  s.seenBy[branch] = tip;
   return said;
 }
 

package/targets/team-safe-start.mjs

@@ -101,8 +101,9 @@ export function teamSafeAnnouncement(root) {
     return `
 ===== 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. En proyectos complejos o con producción, el agente no trabaja en la rama principal: abre ramas y
-   cierra con PR. En proyectos sencillos trabaja en la principal. Para abrirla: «desbloquea main».
+1. Antes de cada cambio de código, el agente pregunta: ¿rama nueva o directamente en la principal?
+   Nunca abre una rama por su cuenta. Si la principal está cerrada (CI, despliegue o equipo), pregunta
+   si abre una rama o la desbloquea («desbloquea main»).
 2. Si otra sesión de un asistente está trabajando en esta misma carpeta, el trabajo nuevo va a un
    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