@ericrisco/rsc 3.0.7 → 3.0.9

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

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { appendFileSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
 import { applyInstall, pruneSharedBases, removeTargetInstall } from '../install-apply.js';
 import { targetPaths } from '../../targets/index.js';
 import { targetHasAgents } from '../../targets/agents.js';
@@ -10,6 +10,8 @@ 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());
 
@@ -157,12 +159,35 @@ export function mergeProfile(existing, plan, previousRecord) {
   return `---\n${front.join('\n')}\n---\n${body.startsWith('\n') ? '' : '\n'}${body}`;
 }
 
+/**
+ * The profile is one person's dials (knowledge-sync never sends it), so it never belongs in a commit
+ * either — yet it sat untracked for good, and every session's agent reported it as «cambios sin
+ * commitear» (E2E 2026-10-07). Excluded in THIS clone only (`info/exclude`, not `.gitignore`), and
+ * never when the team already tracks it: that is their decision.
+ */
+export function excludePersonalProfile(cwd) {
+  const git = (args) => { try { return execFileSync('git', args, { cwd, encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return null; } };
+  if (git(['rev-parse', '--is-inside-work-tree']) !== 'true') return false;
+  const rel = '02-DOCS/wiki/harness/user-profile.md';
+  if (git(['ls-files', '--', rel])) return false;
+  const value = git(['rev-parse', '--git-path', 'info/exclude']);
+  if (!value) return false;
+  const file = resolve(cwd, value);
+  const pattern = `/${rel}`;
+  mkdirSync(dirname(file), { recursive: true });
+  const body = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  if (body.split('\n').includes(pattern)) return true;
+  appendFileSync(file, `${body && !body.endsWith('\n') ? '\n' : ''}${pattern}\n`);
+  return true;
+}
+
 export function writeOnboardingDocuments(cwd, plan, planId, previousRecord = null) {
   const dir = join(cwd, '02-DOCS', 'wiki', 'harness');
   mkdirSync(dir, { recursive: true });
   const docs = renderOnboardingDocuments(plan, planId);
   const profilePath = join(dir, 'user-profile.md');
   writeFileSync(profilePath, mergeProfile(existsSync(profilePath) ? readFileSync(profilePath, 'utf8') : '', plan, previousRecord));
+  excludePersonalProfile(cwd);
   writeFileSync(join(dir, 'installation-plan.md'), docs.installation);
   const decisionsPath = join(dir, 'decisions.md');
   if (!existsSync(decisionsPath)) writeFileSync(decisionsPath, docs.decisions);
@@ -343,34 +368,15 @@ export async function applyAcceptedOnboarding({ cwd = process.cwd(), plan, planI
 // Y la retro-compatibilidad no es una lista de exentos (P3): el suelo viaja DENTRO del plan, así
 // que un recibo aceptado por una versión anterior no lo trae y queda exento por construcción.
 
-const LIB_DIR = dirname(fileURLToPath(import.meta.url));
-const TEMPLATE_SOURCE = join(LIB_DIR, '..', '..', 'skills', 'harness', 'assets', '_TEMPLATE');
 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';
-
-// Los ficheros que la plantilla trae hoy. Se lee del asset en vez de codificar una lista, para que
-// añadir un fichero a la plantilla no deje el suelo comprobando de menos en silencio.
-//
-// Un error aquí NO se convierte en lista vacía. Comérselo dejaba el suelo permanentemente
-// insatisfacible, con un mensaje que ofrecía una acción que leía ese mismo asset ausente y que por
-// tanto no podía arreglarlo nunca — y sin nombrar jamás la causa real, que es un paquete roto.
-function templateAssets() {
-  return readdirSync(TEMPLATE_SOURCE).sort();
-}
-
-// npm NUNCA empaqueta un fichero llamado `.gitignore`, así que el asset viaja sin punto y se copia
-// con él. Sin esto, desde el paquete publicado se copiaban 4 de 5 ficheros y el que faltaba era el
-// único que evita comitear el `.env` que el README —copiado por el propio instalador— manda crear.
-const DOTTED = { gitignore: '.gitignore' };
-const targetName = (asset) => DOTTED[asset] ?? asset;
+// 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 capa entera, no cada proveedor: el flujo documentado es copiar `_TEMPLATE/` a
-// `01-TOOLS/<PROVEEDOR>/`, y depender de que cada copia se lleve su propia protección es depender
-// de que nadie se salte un paso con credenciales de por medio.
-const LAYER_IGNORE = ['# Escrito por rsc: la capa de herramientas guarda credenciales.',
-  '*/.env', '*/.env.*', '!*/.env.example', '*/keys/', '*/out/', ''].join('\n');
+// 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.
 
 /**
  * Crea la parte determinista del esqueleto. Copiar ficheros estáticos es un algoritmo, así que por

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, '')
@@ -248,7 +255,14 @@ export function buildOnboardingPlan(record, evidence) {
   // in an invoicing workspace, and `init` promises it by technical level: non-technical and mixed get
   // it, whatever the project is. The guard also decides at runtime from the profile, so the plan only
   // chooses whether it is present, never whether it bites.
-  const dangerGuard = normalized.technicalLevel !== 'technical';
+  //
+  // And since 3.0.8 it is present for EVERYONE. A technical user used to get nothing, so a small
+  // project with `main` open had no guard at all (E2E 2026-10-07). The runtime still decides the
+  // bite: deny for non-technical, `ask` — only on lost work or rewritten history — for technical.
+  const dangerGuard = true;
+  // The FTD/SDD lane decision belongs to every software project, small ones included: without it
+  // the agent never sees the lanes (E2E 2026-10-07: five sessions, zero feature documents).
+  const laneGate = isSoftware;
   // `sdd` is installed everywhere now, but its DECISION is about practice, not presence — so where
   // the chain is not practised the explicit `deferred` entry below must be the only one, or the
   // generic "installed → selected" mapping would shadow it and `reassess` would see nothing to watch.
@@ -269,9 +283,16 @@ export function buildOnboardingPlan(record, evidence) {
   // so the chain is always one request away; this decision is what `reassess` watches, and what the
   // floor reads. Collapsing the two would have deleted reassess's reason to exist as a side effect
   // of an installer change, which is not a decision an installer change gets to make.
-  if (!practisesSdd) decisions.push(deferred('sdd', 'workflow', isSoftware
-    ? 'The software scope is small, so specification overhead is not justified yet.'
-    : 'SDD applies to substantial software work, which is not the declared project purpose.', sddTriggers, softwareTriggers));
+  // The reason says both halves, because the plan lists `.claude/skills/sdd` under managed paths
+  // and a bare "deferred" next to it read as a contradiction (E2E 2026-10-07). Only the wording
+  // changes: the decision stays the one deferred `workflow/sdd` entry that reassess watches.
+  const whyDeferred = isSoftware
+    ? 'the software scope is small, so specification overhead is not justified yet.'
+    : 'SDD applies to substantial software work, which is not the declared project purpose.';
+  const sddReason = skills.includes('sdd')
+    ? `The sdd skill is installed, so the chain is one request away; the practice is deferred: ${whyDeferred}`
+    : whyDeferred.charAt(0).toUpperCase() + whyDeferred.slice(1);
+  if (!practisesSdd) decisions.push(deferred('sdd', 'workflow', sddReason, sddTriggers, softwareTriggers));
   if (baseAgents) {
     for (const id of agents) decisions.push(selected(id, 'agent', 'The accepted substantial software workflow requires this implementation or review role.'));
   } else {
@@ -296,6 +317,7 @@ export function buildOnboardingPlan(record, evidence) {
     codeHooks: practisesSdd,
     gitmojiGuard,
     dangerGuard,
+    laneGate,
     memory: true,
     context7: false,
   };

package/scripts/lib/tools-skeleton.js

@@ -0,0 +1,76 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, lstatSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// The `01-TOOLS/` scaffolding rsc writes on onboarding, in ONE place: what `ensureHarnessSkeleton`
+// copies is exactly what `purge` may take back, and it may take back only a file still identical to
+// what was copied. `01-TOOLS/` is the layer the user edits when adding tools, so anything that
+// differs from the template is theirs and stays.
+
+const LIB_DIR = dirname(fileURLToPath(import.meta.url));
+export const TEMPLATE_SOURCE = join(LIB_DIR, '..', '..', 'skills', 'harness', 'assets', '_TEMPLATE');
+
+// Los ficheros que la plantilla trae hoy. Se lee del asset en vez de codificar una lista, para que
+// añadir un fichero a la plantilla no deje el suelo comprobando de menos en silencio.
+//
+// Un error aquí NO se convierte en lista vacía. Comérselo dejaba el suelo permanentemente
+// insatisfacible, con un mensaje que ofrecía una acción que leía ese mismo asset ausente y que por
+// tanto no podía arreglarlo nunca — y sin nombrar jamás la causa real, que es un paquete roto.
+export function templateAssets() {
+  return readdirSync(TEMPLATE_SOURCE).sort();
+}
+
+// npm NUNCA empaqueta un fichero llamado `.gitignore`, así que el asset viaja sin punto y se copia
+// con él. Sin esto, desde el paquete publicado se copiaban 4 de 5 ficheros y el que faltaba era el
+// único que evita comitear el `.env` que el README —copiado por el propio instalador— manda crear.
+const DOTTED = { gitignore: '.gitignore' };
+export const targetName = (asset) => DOTTED[asset] ?? asset;
+
+// La capa entera, no cada proveedor: el flujo documentado es copiar `_TEMPLATE/` a
+// `01-TOOLS/<PROVEEDOR>/`, y depender de que cada copia se lleve su propia protección es depender
+// de que nadie se salte un paso con credenciales de por medio.
+export const LAYER_IGNORE = ['# Escrito por rsc: la capa de herramientas guarda credenciales.',
+  '*/.env', '*/.env.*', '!*/.env.example', '*/keys/', '*/out/', ''].join('\n');
+
+const sameBytes = (a, b) => {
+  try { return readFileSync(a).equals(Buffer.isBuffer(b) ? b : readFileSync(b)); } catch { return false; }
+};
+const isPlainFile = (p) => { try { return lstatSync(p).isFile(); } catch { return false; } };
+
+/**
+ * Take back the scaffolding rsc wrote, file by file, only where it is still byte-identical to what
+ * rsc wrote. Returns `{ removed, kept }` as paths relative to `cwd`, `kept` with a reason. Empty
+ * directories left behind are removed by the caller's directory sweep.
+ */
+// Committed means the team has it: deleting it leaves the tree dirty and takes it from everybody on
+// the next push (field test 3.0.8: purge deleted a 01-TOOLS/.gitignore that was already in history).
+function tracked(cwd, rel) {
+  try { return Boolean(execFileSync('git', ['ls-files', '--', rel], { cwd, encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] }).trim()); } catch { return false; }
+}
+
+export function removeUnmodifiedSkeleton(cwd, { dryRun = false } = {}) {
+  const removed = [];
+  const kept = [];
+  const committed = (rel) => tracked(cwd, rel) && (kept.push({ path: rel, reason: 'committed to git — the team has it; delete it in a commit if you mean to' }), true);
+  const templateDir = join(cwd, '01-TOOLS', '_TEMPLATE');
+  if (existsSync(templateDir) && !lstatSync(templateDir).isSymbolicLink()) {
+    for (const asset of templateAssets()) {
+      const rel = `01-TOOLS/_TEMPLATE/${targetName(asset)}`;
+      const file = join(cwd, rel);
+      if (!existsSync(file) || committed(rel)) continue;
+      if (isPlainFile(file) && sameBytes(file, join(TEMPLATE_SOURCE, asset))) {
+        if (!dryRun) rmSync(file, { force: true });
+        removed.push(rel);
+      } else kept.push({ path: rel, reason: 'changed since rsc wrote it — yours now' });
+    }
+  }
+  const layer = join(cwd, '01-TOOLS', '.gitignore');
+  if (existsSync(layer) && !committed('01-TOOLS/.gitignore')) {
+    if (isPlainFile(layer) && sameBytes(layer, Buffer.from(LAYER_IGNORE))) {
+      if (!dryRun) rmSync(layer, { force: true });
+      removed.push('01-TOOLS/.gitignore');
+    } else kept.push({ path: '01-TOOLS/.gitignore', reason: 'changed since rsc wrote it — yours now' });
+  }
+  return { removed, kept };
+}

package/scripts/rsc.js

@@ -4,12 +4,13 @@ import { detectTarget, installedTargets, resolveTargets, TARGETS } from '../targ
 import { detectRepo } from './detect-repo.js';
 import { rank } from './consult.js';
 import { expandRecommends, toOutcomes, hasOutcome } from './lib/recommend.js';
-import { applyInstall, listInstalled, listInstalledAgents, listInstalledCommands, uninstall, syncInstalled, purge, collisions, ownSkillPaths } from './install-apply.js';
+import { applyInstall, listInstalled, listInstalledAgents, listInstalledCommands, uninstall, syncInstalled, purgeReport, collisions, ownSkillPaths } from './install-apply.js';
+import { isAbsolute, relative, sep } from 'node:path';
 import { stackAgentNames } from '../targets/agents.js';
 import { doctor } from './doctor.js';
 import { ask, say, select, pickFrom, banner, confirm, isInteractive } from './lib/ui.js';
 import { refreshRegistry, registryStatus } from './lib/registry.js';
-import { audit, writeAuditReport } from './audit.js';
+import { audit, writeAuditReport, recordAuditBaseline } from './audit.js';
 import { DOMAINS } from './lib/domains.js';
 import { listBackups, restoreBackup, whereKept } from './lib/backups.js';
 import { runUpgrade } from './lib/upgrade.js';
@@ -18,11 +19,13 @@ import { DEFAULT_SKILL_FLOOR, withDefaultSkillFloor } from './lib/default-skill-
 import { RETIRED_SKILLS, replaceRetired } from './lib/retired-skills.js';
 import { readManifest, writeManifest } from './lib/manifest-file.js';
 import { versionReport } from './lib/versions.js';
+import { templateAssets, targetName } from './lib/tools-skeleton.js';
 import {
   normalizeOnboarding, missingOnboardingFields, scanProject,
   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);
 
@@ -39,6 +42,33 @@ if (['--version', '-v', 'version'].includes(rawArgv[0])) {
   process.stdout.write(`${lines.join('\n')}\n`);
   process.exit(0);
 }
+const GENERAL_HELP = [
+  'Use: npx @ericrisco/rsc onboard | reassess | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | memory <on|off|status|save|resume|learn|metrics> | sello <on|off|status|…> | worktrees [reap [path] [--confirm]] | backups | restore <id|latest> | upgrade | repair | uninstall <id...> | purge | help',
+  'Any command takes --target <claude|codex|cursor|copilot|gemini|…> (comma-separate for several)',
+  '   → without it, rsc uses the assistant already installed here; if two are, it asks instead of guessing.',
+].join('\n');
+const UNINSTALL_HELP = [
+  'Use: npx @ericrisco/rsc uninstall <id...> [--dry-run] [--target <assistant>]',
+  '  Removes the named skills or agents from this project.',
+  '  To remove everything rsc installed here, run: npx @ericrisco/rsc purge  (keeps 02-DOCS/ unless --with-docs)',
+].join('\n');
+const PURGE_HELP = [
+  'Use: npx @ericrisco/rsc purge [--dry-run] [--with-docs]',
+  '  Removes everything rsc installed in this project and reports what was removed, cleaned and kept.',
+  '  --dry-run shows the report without touching anything. 02-DOCS/ is kept unless --with-docs.',
+].join('\n');
+
+// Asking for help must never RUN the command. `uninstall --help` used to be read as an empty id list
+// and report "Removed: (nothing)"; `purge --help` would have purged. Answered before anything else.
+{
+  const helpAsked = rawArgv.some((a) => a === '--help' || a === '-h');
+  if (rawArgv[0] === 'help' || helpAsked) {
+    const about = rawArgv[0] === 'help' ? rawArgv[1] : rawArgv.find((a) => !a.startsWith('-'));
+    const text = about === 'uninstall' ? UNINSTALL_HELP : about === 'purge' ? PURGE_HELP : GENERAL_HELP;
+    process.stdout.write(`${text}\n`);
+    process.exit(0);
+  }
+}
 // `--accompaniment` stays listed although the dial is retired: old scripts and agents still pass it,
 // and its value must keep being skipped rather than read as a command or a skill id.
 const GLOBAL_VALUE_FLAGS = new Set([
@@ -159,6 +189,12 @@ function renderPlan(plan, planId) {
   for (const decision of plan.decisions.filter((d) => d.state === 'excluded')) say(`  × ${decision.kind}/${decision.id} — ${decision.reason}`);
   say('Managed paths:');
   for (const path of plan.governedPaths) say(`  ${path}`);
+  // The scaffolding is written once and then belongs to the person, so it is not a managed (digested)
+  // path — but it IS written by this plan, and a plan that does not show it is not the whole plan.
+  if ((plan.floorPaths || []).includes('01-TOOLS/_TEMPLATE/')) {
+    say('Scaffolded once (yours to edit; never overwritten; purge removes only untouched files):');
+    for (const path of ['01-TOOLS/.gitignore', ...templateAssets().map((a) => `01-TOOLS/_TEMPLATE/${targetName(a)}`)].sort()) say(`  ${path}`);
+  }
   if (plan.replacesUserSkills?.length) {
     say('Your own skills this plan replaces:');
     for (const path of plan.replacesUserSkills) say(`  ! ${path} — already here and not put by rsc; the catalog skill of the same name takes its place, and yours is kept in .rsc/backups/`);
@@ -166,8 +202,11 @@ function renderPlan(plan, planId) {
     say('  AGENT: name each of these to the user before accepting, and ask whether to replace or rename.');
   }
   if (plan.evidence.parentHarness) say(`Parent harness detected at ${plan.evidence.parentHarness}; it is not inherited by this plan.`);
+  // Pinned to the version that computed this plan. The id is a hash of the plan, and the plan
+  // depends on the catalog of the running version: `@latest` would accept it with whatever version
+  // npm resolves next, which answers RSC_PLAN_CHANGED the day a release lands in between.
   const pieces = [
-    'npx @ericrisco/rsc@latest onboard',
+    `npx @ericrisco/rsc@${versionReport(process.cwd()).cli} onboard`,
     `--technical-level ${plan.record.technicalLevel}`,
     `--project-kind ${plan.record.projectKind}`,
     `--goal-base64 ${encodeGoal(plan.record.goal)}`,
@@ -260,6 +299,17 @@ 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 */ }
   for (const path of plan.replacesUserSkills || []) {
     const kept = whereKept({ cwd: process.cwd(), relPath: path });
     if (kept) say(`Your previous ${path} is kept in ${kept}`);
@@ -272,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}`);
@@ -370,10 +427,34 @@ function flag(name) {
 // Remove everything rsc installed in this project (skills, hooks, .rsc/), across
 // every assistant. Keeps 02-DOCS/ unless --with-docs. `purge` / `uninstall --all`.
 async function runPurge(dryRun, withDocs) {
-  const removed = await purge({ cwd: process.cwd(), withDocs, dryRun });
-  say(`${dryRun ? 'Would remove' : 'Removed'} ${removed.length} path(s):`);
-  for (const r of removed) say(`  - ${r}`);
-  if (!withDocs) say('\nKept 02-DOCS/ (your knowledge base). Add --with-docs to remove it too.');
+  const cwd = process.cwd();
+  const report = await purgeReport({ cwd, withDocs, dryRun });
+  // Relative to the project: the report is read by a person, and every path is inside it.
+  const shown = (p) => {
+    const rel = relative(cwd, p);
+    return !rel || rel.startsWith('..') || isAbsolute(rel) ? p : rel.split(sep).join('/');
+  };
+  say(`${dryRun ? 'Would remove' : 'Removed'} ${report.removed.length} path(s):`);
+  for (const r of report.removed.map(shown).sort()) say(`  - ${r}`);
+  if (report.cleaned.length) {
+    say(`\n${dryRun ? 'Would clean' : 'Cleaned'} ${report.cleaned.length} file(s) — rsc's entries ${dryRun ? 'would be' : 'were'} taken out; ${dryRun ? 'each is deleted if nothing of yours remains' : 'the rest of the file is yours and stays'}:`);
+    for (const c of report.cleaned.map(shown).sort()) say(`  - ${c}`);
+  }
+  if (report.kept.length) {
+    say(`\nKept ${report.kept.length}:`);
+    for (const k of report.kept) say(`  - ${k.path} — ${k.reason}`);
+  }
+  // On a clone most of what purge deletes is committed. Deleting it here is local; committing the
+  // deletions uninstalls rsc for the whole team (team simulation D15). Said before anyone commits.
+  if (report.tracked?.length) {
+    const quote = (p) => (/^[\w./@+-]+$/.test(p) ? p : `'${p.replace(/'/g, `'\\''`)}'`);
+    say(`\nWARNING: ${report.tracked.length} of these file(s) are committed in git and ${dryRun ? 'would show' : 'now show'} as deleted or changed:`);
+    for (const f of report.tracked.slice(0, 12)) say(`  - ${f}`);
+    if (report.tracked.length > 12) say(`  … and ${report.tracked.length - 12} more`);
+    say('Committing these changes uninstalls rsc for the whole team, on their next pull. To remove rsc only on this machine, do not commit them.');
+    if (!dryRun) say(`To undo locally: git restore -- ${report.tracked.map(quote).join(' ')}`);
+    else say('To undo after a real purge: git restore -- <those files> (purge prints the exact command).');
+  }
 }
 
 async function recommendIds(query, { labeledOnly = false } = {}) {
@@ -515,7 +596,7 @@ function printContextBudget(b) {
   if (b.notApplicable.length) {
     say(`  ${b.note}`);
   } else {
-    say(`  Per session start : ${kb(b.sessionStartBytes)}   (always-on body, per wired scope)`);
+    say(`  Per session start : ${kb(b.sessionStartBytes)}   (always-on body, per wired scope; one-time and conditional banners not counted)`);
     say(`  Per user turn     : ${kb(b.perTurnBytes)}`);
   }
   say(`  Skill descriptions: ${kb(b.descriptionsBytes)}   (${b.installedSkills} installed, always in context)`);
@@ -1006,7 +1087,15 @@ async function main() {
         // defeated by an argument the sweep itself told the agent to type.
         const confirmed = argv.includes('--confirm');
         const targets = one ? [one] : candidates.filter((c) => c.verdict === 'safe').map((c) => c.path);
-        if (!targets.length) { say('nothing to clean up.'); return; }
+        // The bulk reap also deletes plain local branches that have landed (`branch -d`, never -D):
+        // the worktree is not the only thing a merge leaves behind (E2E defect 14).
+        const reapBranches = () => {
+          if (one) return 0;
+          const { deleted } = W.reapMergedBranches(root);
+          for (const b of deleted) say(`✅ deleted merged branch ${b}`);
+          return deleted.length;
+        };
+        if (!targets.length) { if (!reapBranches()) say('nothing to clean up.'); return; }
         for (const t of targets) {
           const out = W.reapWorktree(root, t, { confirmed });
           if (out.removed) {
@@ -1018,6 +1107,7 @@ async function main() {
             process.exitCode = 1;
           }
         }
+        reapBranches();
         return;
       }
 
@@ -1272,7 +1362,14 @@ async function main() {
       const dry = argv.includes('--dry-run');
       // `uninstall --all` is an alias for a full purge.
       if (argv.includes('--all')) return void (await runPurge(dry, argv.includes('--with-docs')));
-      const selected = classifyRequested(requestedIds());
+      const ids = requestedIds();
+      // No id is not "nothing to remove": it is a command that was not given what it needs.
+      if (!ids.length) {
+        console.error(`rsc: uninstall needs at least one skill or agent id.\n${UNINSTALL_HELP}`);
+        process.exitCode = 1;
+        return;
+      }
+      const selected = classifyRequested(ids);
       // A retired skill an old install still holds is not unknown: the state file proves it is ours.
       const held = new Set(listInstalled({ target }));
       selected.skills.push(...selected.unknown.filter((id) => Object.hasOwn(RETIRED_SKILLS, id) && held.has(id)));
@@ -1306,9 +1403,7 @@ async function main() {
       return void (await runPurge(argv.includes('--dry-run'), argv.includes('--with-docs')));
     default:
       say(`rsc: unknown command '${cmd}'.`);
-      say('Use: npx @ericrisco/rsc onboard | reassess | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | memory <on|off|status|save|resume|learn|metrics> | sello <on|off|status|…> | worktrees [reap [path] [--confirm]] | backups | restore <id|latest> | upgrade | repair | uninstall <id> | purge');
-      say('Any command takes --target <claude|codex|cursor|copilot|gemini|…> (comma-separate for several)');
-      say('   → without it, rsc uses the assistant already installed here; if two are, it asks instead of guessing.');
+      say(GENERAL_HELP);
       process.exitCode = 1;
   }
 }

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.