@ericrisco/rsc 3.0.8 → 3.0.9

package/README.md

@@ -372,7 +372,11 @@ That verdict is not just about the receipt: it also requires the harness floor t
 `01-TOOLS/_TEMPLATE/`, `02-DOCS/wiki/harness/`, and the constitution when the plan selects SDD.
 If the floor is missing, the install applied but prints `RSC_ONBOARDING_INCOMPLETE` with each
 missing path and the action that creates it, because a plan that promised little used to be able to
-report success with three markdown files.
+report success with three markdown files. When the plan selects SDD, onboarding writes the
+constitution itself as a draft (`status: draft`, only the facts it knows, no principles), so a
+non-interactive install still ends `RSC_ONBOARDING_READY`; the draft is listed as pending — under
+READY and in `rsc doctor` — until the `constitution` phase completes it. An existing constitution is
+never overwritten.
 
 ---
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.0.8",
+  "version": "3.0.9",
   "counts": {
     "skills": 270,
     "agents": 33,

package/package.json

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

@@ -20,6 +20,7 @@ import { metricsSummary } from '../targets/session-memory-core.mjs';
 import { agentPath } from '../targets/agents.js';
 import { projectOptOuts } from '../targets/opt-outs.js';
 import { versionReport } from './lib/versions.js';
+import { CONSTITUTION_PATH, constitutionIsDraft } from './lib/constitution-draft.js';
 
 // Gates the committed manifest says the team disarmed, still armed here. Read through the same
 // partition the installer uses, so a machine-only switch somebody's older rsc wrote into the
@@ -310,6 +311,11 @@ export function doctor({ target, home, cwd }) {
   for (const [id, e] of Object.entries(state.skills)) {
     for (const f of e.files) if (!existsSync(f)) report.missing.push({ id, path: f, action: 'Run `npx @ericrisco/rsc sync` to restore this managed skill.' });
   }
+  // Pending is not unhealthy: work the harness expects the user to finish, named with what does it.
+  // The draft constitution `rsc onboard` writes is the first entry; it never touches `healthy`.
+  report.pending = constitutionIsDraft(root)
+    ? [{ id: 'constitution-draft', path: CONSTITUTION_PATH, action: 'Complete it with the `constitution` phase before the first SDD feature; ratifying removes `status: draft`.' }]
+    : [];
   report.healthy = report.hookWired && !report.missing.length && !missingAgents.length && !missingCommands.length
     && !report.opencodePluginsOutdated.length;
   return report;

package/scripts/lib/constitution-draft.js

@@ -0,0 +1,156 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// La constitución como BORRADOR.
+//
+// El suelo del arnés exige `02-DOCS/wiki/sdd/constitution.md` cuando el plan elige SDD, y sólo una
+// fase agéntica la escribía. Así que una instalación no interactiva de software complejo —terminal,
+// CI, nadie con un agente delante— terminaba en RSC_ONBOARDING_INCOMPLETE: medio instalada. En la
+// prueba de campo una sesión entera ($3.59, 67 turnos) se gastó sólo en escribirla.
+//
+// Decisión del PO (2026-10-07): el onboarding escribe un BORRADOR y no falla. El borrador lleva
+// `status: draft`, los encabezados reales de la plantilla de la fase `constitution`, y sólo los
+// hechos que el onboarding conoce — objetivo, tipo, alcance, flujo, evidencia de stack. Ningún
+// principio: ratificar es de la fase `constitution`, con el usuario delante (P4). El suelo lo acepta
+// porque sólo mira existencia; la cadena SDD lo detecta por `status: draft` y lo completa antes del
+// primer spec; `doctor` lo lista como pendiente, nunca como fallo.
+
+export const CONSTITUTION_PATH = '02-DOCS/wiki/sdd/constitution.md';
+export const DRAFT_MARK = 'borrador — complétalo con la fase `constitution` antes del primer SDD';
+
+const WORKFLOW_FACT = {
+  branches: 'branches closed with a pull request; the default branch is closed to direct work',
+  main: 'straight on the default branch',
+};
+
+// El objetivo es texto del usuario y va a un documento que leerá un agente: una línea, acotada.
+const oneLine = (value, limit = 200) => String(value ?? '').replace(/[\u0000-\u001f\u007f]+/g, ' ')
+  .replace(/\s+/g, ' ').trim().slice(0, limit);
+
+/** Puro: el texto del borrador a partir del plan aceptado. Sin reloj ni disco, salvo lo que se le pase. */
+export function renderConstitutionDraft(plan, { project = 'Project', date = new Date() } = {}) {
+  const record = plan?.record || {};
+  const evidence = plan?.evidence || {};
+  const stacks = (evidence.stacks || []).map((s) => oneLine(s, 40)).filter(Boolean);
+  const manifests = (evidence.signals || []).filter((s) => String(s).startsWith('manifest:'))
+    .map((s) => oneLine(String(s).slice('manifest:'.length), 60));
+  const day = date.toISOString().slice(0, 10);
+  const name = oneLine(project, 80) || 'Project';
+  const stackLine = stacks.length
+    ? `Detected at install: ${stacks.join(', ')}${manifests.length ? ` (from ${manifests.join(', ')})` : ''}. Not ratified yet.`
+    : 'No stack evidence was detected at install. To be decided in the `constitution` phase.';
+  const workflow = WORKFLOW_FACT[record.workflow];
+  const pending = '_Pending — to be completed in the `constitution` phase._';
+  return `---
+type: constitution
+title: ${name} — Constitution
+description: Draft written by rsc onboard from the accepted plan; not ratified.
+tags: [sdd, constitution]
+timestamp: ${date.toISOString().replace(/\.\d{3}Z$/, 'Z')}
+topic: sdd
+status: draft
+version: draft
+---
+
+# ${name} — Constitution
+
+> **${DRAFT_MARK}.**
+> Draft: complete it with the \`constitution\` phase before the first SDD feature. It holds only what
+> onboarding knew; it ratifies no principle. Ratifying it removes \`status: draft\` and starts at v1.0.0.
+
+## Known facts (from onboarding)
+
+- Goal: ${oneLine(record.goal)}
+- Project kind: ${oneLine(record.projectKind, 40)}${record.softwareScope ? ` · software scope: ${oneLine(record.softwareScope, 40)}` : ''}
+${workflow ? `- How code changes land: ${workflow} (\`--workflow ${record.workflow}\`).\n` : ''}- Stack evidence: ${stackLine}
+
+## 1. Stack canon
+
+${stackLine}
+
+## 2. Quality bar
+
+${pending}
+
+## 3. Conventions
+
+${pending}
+
+## 4. Branching & shipping
+
+${workflow ? `Chosen at install: ${workflow}. ` : ''}${pending}
+
+## 5. Security & privacy floor
+
+${pending}
+
+## 6. UX / accessibility floor (if there is a UI)
+
+${pending}
+
+## 7. Performance budgets (where they matter)
+
+${pending}
+
+## 8. Knowledge & decisions
+
+${pending}
+
+## Definition of Done (the merge bar \`verify\` runs against)
+
+${pending}
+
+## Amendment log (append-only)
+
+| Date | Version | Change | Why |
+|------|---------|--------|-----|
+| ${day} | draft | Draft generated by \`rsc onboard\`. | The SDD floor needs a constitution; ratification is the \`constitution\` phase's. |
+`;
+}
+
+/** ¿La constitución existe y está en borrador? Sólo lee el frontmatter; ilegible ⇒ no es borrador. */
+export function constitutionIsDraft(cwd = process.cwd()) {
+  const path = join(cwd, CONSTITUTION_PATH);
+  try {
+    if (!existsSync(path) || !lstatSync(path).isFile()) return false;
+    const text = readFileSync(path, 'utf8').replace(/\r\n/g, '\n');
+    const block = /^---\n([\s\S]*?)\n---(\n|$)/.exec(text);
+    return Boolean(block && /^status:\s*["']?draft["']?\s*$/m.test(block[1]));
+  } catch {
+    return false;
+  }
+}
+
+const isLink = (path) => { try { return lstatSync(path).isSymbolicLink(); } catch { return false; } };
+
+/**
+ * Escribe el borrador si el plan exige la constitución y no hay ninguna. Nunca sobrescribe: ni una
+ * ratificada ni un borrador que el usuario ya empezó. Un enlace (aunque cuelgue) cuenta como
+ * existente, y `wx` cierra la carrera entre comprobar y escribir.
+ */
+export function ensureConstitutionDraft(cwd, plan, { now = new Date() } = {}) {
+  if (!(plan?.floorPaths || []).includes(CONSTITUTION_PATH)) return { created: false };
+  // Sin importar `onboarding-apply.js` (doctor lee este módulo y no debe arrastrar el instalador):
+  // un directorio intermedio que sea enlace podría sacar la escritura de la raíz, y git versiona los
+  // enlaces, así que el vector viaja en un clone. Más estricto que la guarda general: no se sigue.
+  let cursor = cwd;
+  for (const segment of ['02-DOCS', 'wiki', 'sdd']) {
+    cursor = join(cursor, segment);
+    if (existsSync(cursor) || isLink(cursor)) {
+      if (lstatSync(cursor).isSymbolicLink()) throw new Error(`RSC_ROOT_AMBIGUOUS: ${CONSTITUTION_PATH} would be written through a symlink`);
+    }
+  }
+  const target = join(cwd, CONSTITUTION_PATH);
+  let present = false;
+  try { lstatSync(target); present = true; } catch { /* ausente */ }
+  if (present) return { created: false };
+  mkdirSync(join(cwd, '02-DOCS', 'wiki', 'sdd'), { recursive: true });
+  try {
+    writeFileSync(target, renderConstitutionDraft(plan, { project: basename(cwd), date: now }), { flag: 'wx' });
+  } catch (error) {
+    if (error.code === 'EEXIST') return { created: false };
+    throw error;
+  }
+  return { created: true };
+}

package/scripts/lib/onboarding-apply.js

@@ -10,6 +10,7 @@ import { readManifest, writeManifest } from './manifest-file.js';
 import { encodeGoal, identifyPlan } from './onboarding.js';
 import { createBackup, restoreBackup } from './backups.js';
 import { RETIRED_SKILLS, replaceRetired } from './retired-skills.js';
+import { CONSTITUTION_PATH } from './constitution-draft.js';
 import { LAYER_IGNORE, TEMPLATE_SOURCE, targetName, templateAssets } from './tools-skeleton.js';
 
 const sameSet = (a = [], b = []) => JSON.stringify([...a].sort()) === JSON.stringify([...b].sort());
@@ -370,7 +371,9 @@ export async function applyAcceptedOnboarding({ cwd = process.cwd(), plan, planI
 const TEMPLATE_FLOOR = '01-TOOLS/_TEMPLATE/';
 
 export const HARNESS_FLOOR_MINIMUM = [TEMPLATE_FLOOR, '02-DOCS/wiki/harness/'];
-export const HARNESS_FLOOR_CONSTITUTION = '02-DOCS/wiki/sdd/constitution.md';
+// El onboarding escribe ahora un BORRADOR (`constitution-draft.js`) y el suelo lo acepta: sólo
+// mira existencia, y completar el borrador es de la cadena SDD, no del instalador.
+export const HARNESS_FLOOR_CONSTITUTION = CONSTITUTION_PATH;
 
 // La plantilla, sus nombres con punto y el `.gitignore` de la capa viven en `tools-skeleton.js`:
 // lo que se copia aquí es exactamente lo que `purge` puede recuperar, y sólo si sigue intacto.

package/scripts/lib/onboarding.js

@@ -117,6 +117,13 @@ export function scanProject(root = process.cwd()) {
       // Codex stores the always-on layer in AGENTS.md. Ignore a file that contains
       // only our managed block, while retaining a user's surrounding instructions
       // as real project evidence across repair/re-onboarding.
+      // El `CLAUDE.md` raíz es el Knowledge map, y lo escriben las propias fases de rsc: la
+      // `constitution` añade su fila «create CLAUDE.md if absent», y el instalador puede dejar ahí
+      // la sombra de AGENTS.md. Contarlo como evidencia movía la identidad del plan justo después de
+      // completar el suelo, y el `--accept-plan` del mismo id moría con RSC_PLAN_CHANGED sin que
+      // nada se hubiera elegido distinto (reproducido con 3.0.8). La cuenta de markdown no decide
+      // nada del plan —sólo su identidad—, así que no se pierde ninguna decisión.
+      if (rel === 'CLAUDE.md') isSignal = false;
       if (entry.name === 'AGENTS.md') {
         const human = readFileSync(path, 'utf8')
           .replace(/\n*<!-- rsc-suggest:start -->[\s\S]*?<!-- rsc-suggest:end -->\n*/g, '')

package/scripts/rsc.js

@@ -25,6 +25,7 @@ import {
   buildOnboardingPlan, decodeGoal, encodeGoal, identifyPlan, recommendDeferredComponents,
 } from './lib/onboarding.js';
 import { applyAcceptedOnboarding, verifyOnboarding, ensureHarnessSkeleton, harnessReadiness } from './lib/onboarding-apply.js';
+import { CONSTITUTION_PATH, constitutionIsDraft, ensureConstitutionDraft } from './lib/constitution-draft.js';
 
 const rawArgv = process.argv.slice(2);
 
@@ -298,6 +299,14 @@ async function runOnboarding(targets) {
   } catch (error) {
     say(`RSC_SKELETON_FAILED ${error.message}`);
   }
+  // La constitución, como BORRADOR, cuando el plan eligió SDD y no hay ninguna. Sin esto una
+  // instalación no interactiva de software complejo acababa INCOMPLETE: sólo una fase agéntica la
+  // escribía. Mismo sitio y mismo motivo que el esqueleto: fuera de la transacción, sin residuo.
+  try {
+    ensureConstitutionDraft(process.cwd(), plan);
+  } catch (error) {
+    say(`RSC_SKELETON_FAILED ${error.message}`);
+  }
   // The audit cadence starts at install. Without a baseline the very first session after onboarding
   // announced "a skill audit is due" about a set chosen minutes earlier. Never overwrites a real run.
   try { recordAuditBaseline(process.cwd()); } catch { /* a missing baseline only means an early nudge */ }
@@ -313,7 +322,14 @@ async function runOnboarding(targets) {
 // poco se cumplía entero. Spec: 02-DOCS/wiki/sdd/specs/install-completion-floor.md
 function emitHarnessReadiness(plan, planId) {
   const readiness = harnessReadiness(process.cwd(), plan);
-  if (readiness.ready) return void say(`RSC_ONBOARDING_READY ${planId}`);
+  if (readiness.ready) {
+    say(`RSC_ONBOARDING_READY ${planId}`);
+    // Listo no es «nada pendiente»: el borrador se nombra para que la cadena SDD lo complete primero.
+    if ((plan.floorPaths || []).includes(CONSTITUTION_PATH) && constitutionIsDraft(process.cwd())) {
+      say(`  Pending: ${CONSTITUTION_PATH} is a draft — complete it with the \`constitution\` phase before the first SDD feature.`);
+    }
+    return;
+  }
   say(`RSC_ONBOARDING_INCOMPLETE ${planId}`);
   for (const missing of safeLines(readiness.missing)) say(`  ${missing}`);
   say(`  Next: ${readiness.action}`);

package/skills/constitution/SKILL.md

@@ -86,6 +86,8 @@ Write `02-DOCS/wiki/sdd/constitution.md` from the template in `references/consti
 
 Create `02-DOCS/wiki/sdd/` if it does not exist. Do not overwrite an existing constitution — amend it.
 
+**A draft is "complete me", not "amend me".** `rsc onboard` writes a skeleton with `status: draft` in the frontmatter: the template's headings, the facts onboarding knew (goal, kind, scope, workflow, detected stack) and no principle. Keep those facts, run the interview, fill the sections, then on ratification drop `status: draft`, set `version: v1.0.0` and log v1.0.0 in the amendment log.
+
 ## Versioning & amendment protocol
 
 The constitution is versioned so `analyze` and `review` can cite "constitution v1.2.0, principle 4".

package/skills/ftd/SKILL.md

@@ -34,6 +34,11 @@ repository**: whoever clones it should get code, not somebody else's notes in pr
 It is written **before the first change**, not after, and it holds exactly this:
 
 ```markdown
+---
+author: <who asked for it — git user.name>
+branch: <the branch the work runs on>
+status: in-progress
+---
 # <feature>
 
 ## Intent          — what changes, and why it is worth doing
@@ -43,6 +48,10 @@ It is written **before the first change**, not after, and it holds exactly this:
 ## Next            — the single next step, so an interruption costs nothing
 ```
 
+The frontmatter says whose work it is, so «¿qué ha hecho cada uno?» has an answer. You never close
+it by hand: when the branch lands on the default branch, rsc's post-merge hook sets `status: done`
+and replaces Next with where and when it merged (on a closed default branch, via `rsc/knowledge`).
+
 No decision journal, no phase records, no approvals. If a decision was meaningful, one line of
 rationale goes next to the task it belongs to.
 

package/skills/sdd/SKILL.md

@@ -77,7 +77,7 @@ When a request lands, do not start typing code. Place it on the map first, then
 > **The new-feature gate (hard).** The moment the user is thinking about a new feature or change — "add…", "build…", "it should also…", "quiero añadir…" — it goes to `specify` first, *even if a stack skill (nextjs/fastapi/flutter/react…) also fired and could just build it*. **No feature code is written — by any skill — until a spec AND a plan exist and the user has approved them.** A stack skill about to build an unspec'd, non-trivial feature must stop and route here. The only exception is a genuinely one-line, low-risk change; name it and skip.
 
 1. **No `02-DOCS/wiki/sdd/config.yaml` and this is non-trivial?** → `sdd-init`.
-2. **No constitution yet AND this project will grow?** → `constitution` once, then come back to the chain.
+2. **No constitution yet AND this project will grow — or its frontmatter says `status: draft` (the one `rsc onboard` writes)?** → `constitution` once, then come back to the chain.
 3. **Ambiguous / architectural / risky change before spec?** → optional proposal artifact via `specify`.
 4. **A new idea, fuzzy, no spec on disk?** → `specify`.
 5. **A spec exists but feels risky / has open questions?** → `clarify`.
@@ -93,7 +93,7 @@ If you genuinely cannot tell which phase you are in, ask the user one question:
 ### Skip rules (be honest about them)
 
 - A **one-line, low-risk change** (typo, copy tweak, config bump) does not need the full chain. Say so, do it, and verify. The method serves shipping, not ceremony.
-- `constitution` runs **once per project**, not per feature. If `02-DOCS/wiki/sdd/constitution.md` exists, read it as guardrails and move on.
+- `constitution` runs **once per project**, not per feature. If `02-DOCS/wiki/sdd/constitution.md` exists, read it as guardrails and move on — unless it is still `status: draft`: then complete it first.
 - `clarify` and `analyze` are **gates, not paperwork**. If a spec is genuinely unambiguous and tiny, name that out loud and pass through — but the bias is to run them, because skipped gates are where drift hides.
 
 ## Autopilot mode — run the whole chain on one up-front yes

package/skills/specify/SKILL.md

@@ -341,7 +341,7 @@ repeated here as prohibitions: naming a behaviour makes it more available, not l
 ## Project grounding (02-DOCS + CLAUDE.md)
 
 - Read `02-DOCS/wiki/sdd/config.yaml` if present. If it is missing and the change is non-trivial, recommend `sdd-init` before proceeding; if the user asks to continue, record the missing config as a risk.
-- Read `02-DOCS/wiki/sdd/constitution.md` first — its principles are inherited constraints, not things to re-decide. If it's missing, note that the project has no constitution yet and suggest the `constitution` phase before continuing (you can still draft a spec, but flag the absence).
+- Read `02-DOCS/wiki/sdd/constitution.md` first — its principles are inherited constraints, not things to re-decide. If it's missing, note that the project has no constitution yet and suggest the `constitution` phase before continuing (you can still draft a spec, but flag the absence). If its frontmatter says `status: draft` (written by `rsc onboard`, unratified), route to `constitution` first and come back: a draft has no principles to inherit.
 - **No constitution yet?** Still write the spec, but inherit nothing — lean harder on the wiki and the user's answers, and record every constraint you would have inherited as a *point to clarify* instead of assuming it.
 - Write the spec to `02-DOCS/wiki/sdd/specs/<slug>.md`. Create the directory if absent.
 - Add a row in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) linking the new spec under the `sdd/specs` topic (additive only — never delete existing rows). Create the index if absent.

package/targets/clone-bootstrap.mjs

@@ -43,7 +43,7 @@ const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9a-z.-]+)?$/i;
  * nothing checks is just drift with a head start.
  */
 export const PROJECT_OPT_OUTS = [
-  'audit', 'auto-update', 'claudemd-check', 'danger-guard', 'feature-gate', 'ftd-nudge', 'gitmoji', 'knowledge-sync', 'ship-guard', 'trunk-guard', 'trunk-open', 'worktree-cleanup', 'worktree-isolation',
+  'audit', 'auto-update', 'claudemd-check', 'danger-guard', 'feature-gate', 'ftd-close', 'ftd-nudge', 'gitmoji', 'knowledge-sync', 'ship-guard', 'trunk-guard', 'trunk-open', 'worktree-cleanup', 'worktree-isolation',
 ];
 
 /**

package/targets/ftd-nudge.mjs

@@ -23,7 +23,7 @@ const KEEP = 50;
 
 export const NUDGE = 'rsc · lane: this session is changing code and has no feature document yet. ' +
   'Before going on, decide the lane and say it in one line: simple → write 02-DOCS/wiki/ftd/<slug>.md now ' +
-  '(Intent, Scope, Checklist with how each item is proven, Evidence, Next) — one document per feature, ' +
+  '(frontmatter author/branch/status: in-progress; Intent, Scope, Checklist with how each item is proven, Evidence, Next) — one document per feature, ' +
   'a box ticked only with its observed proof under Evidence, Next kept current; big or ' +
   'interlocking → SDD (spec first). A one-line, zero-risk change needs no document: say so instead.';
 

package/targets/knowledge-sync.mjs

@@ -36,7 +36,7 @@
 // but Node. Never throws into a hook; whatever goes wrong is said on the next message.
 import { execFileSync, spawn } from 'node:child_process';
 import {
-  closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, statSync,
+  appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, statSync,
   unlinkSync, writeFileSync,
 } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
@@ -147,10 +147,29 @@ function acquire(root) {
 
 function release(root) { try { unlinkSync(join(root, '.rsc', LOCK)); } catch { /* gone */ } }
 
+/**
+ * Commits handed over without the lock (the post-merge close runs inside somebody's `git pull` and
+ * must not wait for a push in flight): one SHA per line, taken into the queue by the next locked body.
+ * Renamed before it is read, so a line appended meanwhile lands in a new file and is never lost.
+ */
+const PENDING = 'knowledge-sync.pending';
+function absorbPending(root, s) {
+  const path = join(root, '.rsc', PENDING);
+  const taking = `${path}.taking`;
+  try { renameSync(path, taking); } catch { return; }
+  try {
+    for (const sha of readFileSync(taking, 'utf8').split('\n').map((x) => x.trim()).filter(Boolean)) {
+      if (!s.queue.includes(sha)) s.queue.push(sha);
+    }
+  } catch { /* unreadable: nothing to take */ }
+  try { unlinkSync(taking); } catch { /* gone */ }
+}
+
 /** The lock and the state live together: a body that runs without the lock never runs. */
 function locked(root, body) {
   if (!acquire(root)) return null;
   const s = readState(root);
+  absorbPending(root, s);
   try { return body(s); } finally { writeState(root, s); release(root); }
 }
 
@@ -366,7 +385,8 @@ function replay(root, base, sha, ours = []) {
       // to replace whole. (A snapshot from a closed trunk can start from HEAD, behind our own last
       // upload — after an upgrade, or once the chain is lost.)
       const last = line(root, ['log', '-1', '--format=%H', base, '--', f]);
-      if (there === blob(root, `${sha}^`, f) || (last && ours.includes(last))) {
+      const from = blob(root, `${sha}^`, f);
+      if (there === from || (last && ours.includes(last)) || behindDefault(root, base, f, there, from, last)) {
         const entry = next && line(root, ['ls-tree', sha, '--', f]);
         const ok = next
           ? run(root, ['update-index', '--add', '--cacheinfo', `${entry.split(' ')[0]},${next},${f}`], { env }).ok
@@ -383,6 +403,23 @@ function replay(root, base, sha, ours = []) {
   }
 }
 
+/**
+ * The exchange branch holds this file only in a version the remote default branch has already gone
+ * past — or never held it — and the change starts from the default branch's version: replacing it
+ * whole is a fast-forward of the file, not a clash. rsc/knowledge is born from main and never merges
+ * it back, so a document merged through a pull request it never carried, then closed on merge
+ * (`closeLanded`), met it as a clash. A file the exchange branch once had and then lost is not this
+ * case: somebody deleted it there, and that is not ours to undo.
+ */
+function behindDefault(root, base, f, there, from, last) {
+  const def = defaultBranch(root);
+  const remoteDef = def && line(root, ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${def}`]);
+  if (!remoteDef || !from || blob(root, remoteDef, f) !== from) return false;
+  if (!there) return !last;
+  const revs = (line(root, ['rev-list', '-n', '50', remoteDef, '--', f]) || '').split('\n').filter(Boolean);
+  return revs.some((c) => blob(root, c, f) === there);
+}
+
 const clashText = (files) => `No he podido subir ${listed(files)}: choca con un cambio que ya está en ${KNOWLEDGE_BRANCH}. ` +
   'Tu versión sigue aquí; hay que juntarlas a mano.';
 
@@ -517,6 +554,8 @@ export function applyIncoming(root, s) {
     .filter(isKnowledge).filter((f) => !onDefault(f, blob(root, tip, f))).slice(0, MAX_FILES);
   const closed = branch === def && trunkClosed(root);
   const touchedBy = (f) => git(root, ['rev-list', `${seen}..${tip}`, '--', f]).split('\n').filter(Boolean);
+  const superseded = (f, mine) => touchedBy(f).some((c) => blob(root, c, f) === mine)
+    || touchedBy(f).some((c) => (line(root, ['log', '-1', '--format=%B', c]) || '').includes(`${CLOSES} ${mine} ${f}`));
 
   // A default branch closed for the agent is left exactly as the remote has it (team sim 2026-10-07,
   // D1). Nothing can be committed there, and anything written uncommitted blocks the person's next
@@ -546,7 +585,12 @@ export function applyIncoming(root, s) {
     const mine = worktreeBlob(root, f);
     if (mine === incoming) continue;
     const base = blob(root, seen, f);
-    if (mine === base && blob(root, 'HEAD', f) === base) take.push(f);
+    const committed = blob(root, 'HEAD', f);
+    if (mine === base && committed === base) take.push(f);
+    // Untouched here, and a version the exchange branch itself went past — it passed through it, or a
+    // close on merge says it replaces it (`CLOSES`). The branch has the merged document as main has it;
+    // the close is its newer version, not somebody else's competing edit (field test 3.0.8).
+    else if (mine && mine === committed && superseded(f, mine)) take.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);
   }
@@ -567,6 +611,243 @@ export function applyIncoming(root, s) {
   return said;
 }
 
+// ------------------------------------------------------------------ close on merge (FTD)
+
+// Field test 3.0.8: a feature document written on a feature branch kept saying «pendiente: abrir PR»
+// after its pull request was merged, and carried no author — «¿qué ha hecho cada uno?» got every
+// feature reported as pending and nobody's name, and the session memory kept injecting the stale Next.
+// So the close is not left to the agent remembering: when a branch LANDS on the default branch (the
+// post-merge hook, `worktree-reaper.mjs`), the feature documents that branch wrote are marked done.
+//
+// Where the edit goes is the whole design. Open default branch: a local `📝 docs(auto)` commit, like
+// any other doc commit there. Closed default branch: never on main — neither the agent nor rsc commits
+// there — so it is built on a throwaway index and handed to `ship`, which replays it onto rsc/knowledge
+// like any knowledge change. The team gets it from there, and it reaches main inside the next PR that
+// carries docs. The checkout is not touched, so the closed main stays clean and the next pull works.
+
+export const FTD_CLOSE_OPT_OUT = '.no-ftd-close';
+const CLOSE_SUBJECT = '📝 docs(auto): cierre FTD';
+/** Trailer of a close: `Cierra: <blob it replaces> <path>`, so a teammate's branch takes it (applyIncoming). */
+const CLOSES = 'Cierra:';
+const isFtdDoc = (p) => /^02-DOCS\/wiki\/ftd\/[^/]+\.md$/.test(p);
+const MAX_BRANCHES = 50;
+
+function splitFrontmatter(text) {
+  const t = String(text).replace(/\r\n/g, '\n');
+  const m = t.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+  return m ? { lines: m[1].split('\n'), body: t.slice(m[0].length) } : { lines: null, body: t };
+}
+
+function fmValue(lines, key) {
+  for (const l of lines || []) {
+    const m = l.match(/^([A-Za-z_][\w-]*):[ \t]*(.*)$/);
+    if (m && m[1] === key) return m[2].trim();
+  }
+  return null;
+}
+
+/** The frontmatter of a feature document as plain fields (`author`, `branch`, `status`, …). */
+export function frontmatter(text) {
+  const { lines } = splitFrontmatter(text);
+  const out = {};
+  for (const l of lines || []) {
+    const m = l.match(/^([A-Za-z_][\w-]*):[ \t]*(.*)$/);
+    if (m) out[m[1]] = m[2].trim();
+  }
+  return out;
+}
+
+const isDoneText = (text) => /^done$/i.test(frontmatter(text).status || '');
+
+/**
+ * The closed version of a feature document, or null when it is already done (idempotent). Sets
+ * `status: done`, `merged`, and `merged_by`/`pr` when known; fills `author`/`branch` only when missing;
+ * replaces the Next section with one line saying where and when it landed. Nothing else is rewritten:
+ * the evidence is the record.
+ */
+export function closeDoc(text, { trunk, date, sha, author, branch, mergedBy, pr } = {}) {
+  const { lines, body } = splitFrontmatter(text);
+  const fm = lines ? [...lines] : [];
+  if (/^done$/i.test(fmValue(fm, 'status') || '')) return null;
+  const set = (key, value, onlyIfMissing = false) => {
+    if (value == null || value === '') return;
+    const i = fm.findIndex((l) => l.startsWith(`${key}:`));
+    if (i < 0) fm.push(`${key}: ${value}`);
+    else if (!onlyIfMissing || !fmValue([fm[i]], key)) fm[i] = `${key}: ${value}`;
+  };
+  set('author', author, true);
+  set('branch', branch, true);
+  set('status', 'done');
+  set('merged', date);
+  set('merged_by', mergedBy);
+  set('pr', pr ? `#${String(pr).replace(/^#/, '')}` : null);
+  const landed = `Fusionado en ${trunk} el ${date} (${sha}).`;
+  const next = /^(##[ \t]*(?:Next|Siguiente|Próximo)[^\n]*\n)([\s\S]*?)(?=^##\s|(?![\s\S]))/mu;
+  const rest = next.test(body)
+    ? body.replace(next, (_, heading) => `${heading}${landed}\n\n`)
+    : `${body.replace(/\n*$/, '\n')}\n## Next\n${landed}\n`;
+  return `---\n${fm.join('\n')}\n---\n${lines ? '' : '\n'}${rest.replace(/\n+$/, '\n')}`;
+}
+
+const isAncestor = (root, a, b) => run(root, ['merge-base', '--is-ancestor', a, b]).ok;
+
+/** Would merging `tip` into `into` change nothing? (squash/rebase merges rewrite identities.) */
+function contains(root, into, tip) {
+  const merged = run(root, ['merge-tree', '--write-tree', into, tip]);
+  return merged.ok && merged.out.split('\n')[0].trim() === line(root, ['rev-parse', `${into}^{tree}`]);
+}
+
+/**
+ * The branches that landed between `orig` and `head`: in head and not before, by identity (merge,
+ * fast-forward) or by content (squash, rebase). Local branches and the remote-tracking ones, the most
+ * recent first and bounded — this runs inside somebody's `git pull`.
+ */
+function landedBranches(root, orig, head, def) {
+  const refs = (line(root, ['for-each-ref', '--sort=-committerdate', '--format=%(refname)', 'refs/heads', 'refs/remotes/origin']) || '')
+    .split('\n').filter(Boolean).slice(0, MAX_BRANCHES * 2);
+  const out = [];
+  const seen = new Set();
+  for (const ref of refs) {
+    const name = ref.replace(/^refs\/heads\//, '').replace(/^refs\/remotes\/origin\//, '');
+    if (!name || name === 'HEAD' || name === def || name === KNOWLEDGE_BRANCH || seen.has(name)) continue;
+    const tip = line(root, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+    if (!tip || isAncestor(root, tip, orig)) continue; // in before, or nothing of its own
+    if (isAncestor(root, tip, head) || (contains(root, head, tip) && !contains(root, orig, tip))) {
+      seen.add(name);
+      out.push({ name, tip });
+    }
+    if (out.length >= MAX_BRANCHES) break;
+  }
+  return out;
+}
+
+/** Where and how a branch landed: the first commit of the default branch's own line that has it. */
+function landingOf(root, orig, head, tip) {
+  const line1 = (line(root, ['rev-list', '--first-parent', '--reverse', `${orig}..${head}`]) || '').split('\n').filter(Boolean).slice(0, 20);
+  const at = line1.find((c) => isAncestor(root, tip, c)) || line1.find((c) => contains(root, c, tip)) || head;
+  const [parents = '', committer = '', date = '', subject = ''] = (line(root, ['log', '-1', '--format=%P%x00%cn%x00%cs%x00%s', at]) || '').split('\0');
+  const pr = subject.match(/Merge pull request #(\d+)/)?.[1] || subject.match(/\(#(\d+)\)\s*$/)?.[1] || null;
+  let mergedBy = null;
+  if (parents.trim().split(/\s+/).length > 1 || pr) mergedBy = committer && committer !== 'GitHub' ? committer : null;
+  else if (/^merge /.test(line(root, ['reflog', '-1', '--format=%gs', 'HEAD']) || '')) mergedBy = line(root, ['config', 'user.name']);
+  return { sha: line(root, ['rev-parse', '--short', at]) || at.slice(0, 7), date: date || new Date().toISOString().slice(0, 10), mergedBy, pr };
+}
+
+/**
+ * The documents a landed branch wrote, closed. A document says whose it is with `branch:`; one of
+ * another branch — brought along by a 📥 sync — is not this branch's to close. A document with no
+ * frontmatter (written before it existed) counts when a commit of the branch's own, not a sync,
+ * touched it; its author is then the git author of the commit that created it.
+ */
+function closuresFor(root, orig, head, def, read) {
+  const out = new Map();
+  for (const { name, tip } of landedBranches(root, orig, head, def)) {
+    const base = line(root, ['merge-base', orig, tip]);
+    if (!base) continue;
+    const files = zlist(run(root, ['diff', '--name-only', '--no-renames', '-z', base, tip, '--', '02-DOCS/wiki/ftd/']).out)
+      .filter(isFtdDoc).filter((f) => !out.has(f) && blob(root, head, f));
+    if (!files.length) continue;
+    let landing = null;
+    for (const f of files) {
+      const text = read(f);
+      if (text == null || isDoneText(text)) continue;
+      const owner = frontmatter(text).branch;
+      if (owner && owner !== name) continue;
+      if (!owner) {
+        const own = (line(root, ['log', '--no-merges', '--format=%s', `${base}..${tip}`, '--', f]) || '').split('\n').filter(Boolean);
+        if (!own.some((s) => s !== SYNC_SUBJECT)) continue;
+      }
+      landing ||= landingOf(root, orig, head, tip);
+      const created = (line(root, ['log', '--diff-filter=A', '--format=%an', tip, '--', f]) || '').split('\n').filter(Boolean).pop();
+      const closed = closeDoc(text, { trunk: def, ...landing, author: created, branch: name });
+      if (closed) out.set(f, closed);
+    }
+  }
+  return out;
+}
+
+/**
+ * The post-merge entry point: close what just landed. Returns `{ closed, via }` — via `local` (open
+ * default branch, committed here) or `knowledge` (closed default branch, queued for rsc/knowledge).
+ * Never throws: it runs inside git, mid-pull, and a failed close must never become a failed merge.
+ */
+export function closeLanded(root, { spawnShip = true } = {}) {
+  const res = { closed: [], via: null };
+  try {
+    if (existsSync(join(root, '.rsc', FTD_CLOSE_OPT_OUT)) || !existsSync(join(root, '.rsc.json'))) return res;
+    // Not `busy()`: git runs post-merge with MERGE_HEAD still on disk, so that check refused every
+    // landing (found end to end, through the real hook). A rebase or a pick in progress is no landing.
+    for (const p of ['rebase-merge', 'rebase-apply', 'CHERRY_PICK_HEAD', 'REVERT_HEAD']) {
+      const path = line(root, ['rev-parse', '--git-path', p]);
+      if (path && existsSync(isAbsolute(path) ? path : join(root, path))) return res;
+    }
+    const def = defaultBranch(root);
+    const branch = line(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+    if (!def || branch !== def) return res; // a landing is a landing on the default branch
+    const head = line(root, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}']);
+    const orig = line(root, ['rev-parse', '--verify', '--quiet', 'ORIG_HEAD^{commit}']);
+    if (!head || !orig || orig === head || !isAncestor(root, orig, head)) return res;
+    const open = !trunkClosed(root);
+    if (!open && inactiveReason(root)) return res; // closed and no rsc/knowledge: nowhere to write
+
+    let read;
+    if (open) {
+      // The checkout's own copy, and only when nobody is editing it.
+      read = (f) => (worktreeBlob(root, f) === blob(root, 'HEAD', f) ? readFileSync(join(root, f), 'utf8') : null);
+    } else {
+      // Already closed on rsc/knowledge, or waiting in the queue to go there: not again.
+      const s = readState(root);
+      let pending = [];
+      try { pending = readFileSync(join(root, '.rsc', PENDING), 'utf8').split('\n').filter(Boolean); } catch { /* none */ }
+      const elsewhere = [`refs/remotes/origin/${KNOWLEDGE_BRANCH}`, ...s.queue, ...pending];
+      const closedElsewhere = (f) => elsewhere.some((rev) => {
+        const b = blob(root, rev, f);
+        return b && isDoneText(git(root, ['cat-file', 'blob', b]));
+      });
+      read = (f) => (closedElsewhere(f) ? null : git(root, ['show', `HEAD:${f}`]));
+    }
+    const docs = closuresFor(root, orig, head, def, read);
+    if (!docs.size) return res;
+    const files = [...docs.keys()];
+
+    // One commit on top of HEAD, built on a throwaway index: plumbing, because git runs this hook
+    // with the merge state still present and refuses a porcelain commit then.
+    const env = { GIT_INDEX_FILE: join(root, '.rsc', 'knowledge-sync.close.index') };
+    let sha;
+    try {
+      mkdirSync(join(root, '.rsc'), { recursive: true });
+      git(root, ['read-tree', 'HEAD'], { env });
+      const trailers = [];
+      for (const [f, text] of docs) {
+        const b = git(root, ['hash-object', '-w', '--stdin'], { input: text }).trim();
+        const mode = (line(root, ['ls-tree', 'HEAD', '--', f]) || '100644').split(' ')[0];
+        git(root, ['update-index', '--cacheinfo', `${mode},${b},${f}`], { env });
+        trailers.push(`${CLOSES} ${blob(root, 'HEAD', f)} ${f}`);
+      }
+      const tree = line(root, ['write-tree'], { env });
+      sha = git(root, ['commit-tree', tree, '-p', head, '-F', '-'], { input: `${CLOSE_SUBJECT}: ${summary(files)}\n\n${trailers.join('\n')}\n` }).trim();
+    } finally {
+      try { unlinkSync(env.GIT_INDEX_FILE); } catch { /* never created */ }
+    }
+
+    if (open) {
+      // Open: it lands here like any docs(auto) commit — HEAD moves only if nobody moved it meanwhile,
+      // then the index and the files follow, for these paths only.
+      git(root, ['update-ref', '-m', `rsc: ${CLOSE_SUBJECT}`, 'HEAD', sha, head]);
+      for (const [f, text] of docs) writeFileSync(join(root, f), text);
+      git(root, ['--literal-pathspecs', 'update-index', '--', ...files]);
+      return { closed: files, via: 'local' };
+    }
+    // Closed: nothing here. Handed to `ship` without the lock, so a push in flight never makes the
+    // pull wait (`absorbPending`); it goes up to rsc/knowledge and reaches main in the next PR.
+    appendFileSync(join(root, '.rsc', PENDING), `${sha}\n`);
+    if (spawnShip) background(root, 'ship');
+    return { closed: files, via: 'knowledge' };
+  } catch {
+    return res;
+  }
+}
+
 // ------------------------------------------------------------------ hook entry points
 
 // `RSC_KNOWLEDGE_SYNC_FOREGROUND=1` runs the network half inline: for tests, which would otherwise race
@@ -738,5 +1019,8 @@ function stdinJson() {
 if (isMainModule(import.meta.url)) {
   const [op, a, b] = process.argv.slice(2);
   if (op === 'hook') process.stdout.write(`${JSON.stringify(hook(a, b, stdinJson()))}\n`);
-  else work(a, op); // detached: `ship <root>` or `fetch <root>`
+  else if (op === 'close') { // the post-merge hook: `close <root>`
+    const r = closeLanded(resolve(a || process.cwd()));
+    for (const f of r.closed) process.stdout.write(`rsc: FTD cerrado ${f}${r.via === 'knowledge' ? ` (vía ${KNOWLEDGE_BRANCH})` : ''}\n`);
+  } else work(a, op); // detached: `ship <root>` or `fetch <root>`
 }

package/targets/opt-outs.js

@@ -22,6 +22,7 @@ export const PROJECT_OPT_OUTS = [
   'claudemd-check',   // the root CLAUDE.md context budget
   'danger-guard',     // foot-gun denial, keyed to the committed user profile
   'feature-gate',     // per-turn re-injection of the SDD gate
+  'ftd-close',        // a landed branch's feature documents marked done by the post-merge hook
   'ftd-nudge',        // once-per-session reminder: code changed and no feature document yet
   'gitmoji',          // the commit-message convention
   'knowledge-sync',   // 01-TOOLS/ + 02-DOCS/ sync: one person off and the team stops seeing their work

package/targets/session-memory-core.mjs

@@ -612,11 +612,19 @@ function subjects(cwd, commits) {
   }).filter((item) => item && !secretShaped(item));
 }
 
+// A document whose frontmatter says `status: done` is finished work, not a next step. On a closed
+// default branch the close travels by rsc/knowledge and is not in the checkout yet (knowledge-sync
+// `closeLanded`), so the exchange branch's copy is asked too — a local ref, no network.
+const isDone = (text) => /^status:[ \t]*done[ \t]*$/mu.test(String(text || '').replace(/\r\n/gu, '\n').match(/^---\n([\s\S]*?)\n---(?:\n|$)/u)?.[1] || '');
+
 function nextSteps(cwd, files) {
   const out = [];
   for (const rel of files.filter((f) => /^02-DOCS\/wiki\/(ftd|sdd\/(specs|plans|progress))\/[^/]+\.md$/u.test(f)).slice(0, 3)) {
     let body = '';
     try { body = readFileSync(join(cwd, rel), 'utf8'); } catch { continue; }
+    if (isDone(body)) continue;
+    const exchange = git(cwd, ['show', `refs/remotes/origin/rsc/knowledge:${rel}`]);
+    if (exchange.ok && isDone(exchange.out)) continue;
     const section = body.match(/^##\s*(Next|Siguiente|Próximo)[^\n]*\n+([\s\S]*?)(?=\n##\s|$)/imu)?.[2];
     const first = section?.split('\n').map((l) => l.replace(/^[-*]\s*/u, '').trim()).find(Boolean);
     const open = (body.match(/^- \[ \]/gmu) || []).length;

package/targets/worktree-reaper.mjs

@@ -549,8 +549,12 @@ if [ -x "$hook_dir/post-merge.rsc-local" ]; then
   "$hook_dir/post-merge.rsc-local" "$@" || true
 fi
 root=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
-[ -f "$root/.rsc/worktree-reaper.mjs" ] || exit 0
 command -v node >/dev/null 2>&1 || exit 0
+# First, while the landed branch still exists: close its feature documents (off: .rsc/.no-ftd-close).
+if [ -f "$root/.rsc/knowledge-sync.mjs" ]; then
+  node "$root/.rsc/knowledge-sync.mjs" close "$root" 2>/dev/null || true
+fi
+[ -f "$root/.rsc/worktree-reaper.mjs" ] || exit 0
 node "$root/.rsc/worktree-reaper.mjs" "$root" auto 2>/dev/null || true
 exit 0
 `;