@ericrisco/rsc 1.3.3 → 1.3.5

package/README.md

@@ -216,6 +216,11 @@ Accept this exact harness plan?
 The terminal and chat adapters produce the same normalized answers and plan id. If project evidence
 changes between preview and acceptance, rsc returns `RSC_PLAN_CHANGED` and writes nothing. After an
 accepted application it verifies the receipt and managed state before printing `RSC_ONBOARDING_READY`.
+That verdict is not just about the receipt: it also requires the harness floor to exist —
+`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.
 
 ---
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.3.3",
+  "version": "1.3.5",
   "counts": {
     "skills": 272,
     "agents": 33,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "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/lib/onboarding-apply.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
-import { appendFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, writeFileSync } from 'node:fs';
-import { join, relative, resolve, sep } from 'node:path';
+import { appendFileSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { applyInstall, pruneSharedBases, removeTargetInstall } from '../install-apply.js';
 import { targetPaths } from '../../targets/index.js';
 import { readState } from './state.js';
@@ -204,3 +205,158 @@ export async function applyAcceptedOnboarding({ cwd = process.cwd(), plan, planI
     throw new Error(`RSC_ONBOARDING_INCOMPLETE: ${error.message}. Recover with: ${recoveryCommand(plan, planId)}`);
   }
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// El suelo del arnés: qué tiene que existir para que decir «listo» sea verdad.
+//
+// «Completado» estaba definido de forma RELATIVA — el estado real coincide con lo que el plan
+// prometió — así que un plan que promete poco se cumplía entero, y una instalación podía imprimir
+// RSC_ONBOARDING_READY con tres markdown y un `.rsc.json`. `01-TOOLS/` no existía para el
+// instalador y la constitución no se mencionaba en ningún sitio.
+//
+// Spec: 02-DOCS/wiki/sdd/specs/install-completion-floor.md
+//
+// Tres cosas que este código NO hace, y cada una es una redacción del plan que se estrelló:
+//
+//   1. NO se comprueba dentro de `applyAcceptedOnboarding`. Ese camino revierte ante cualquier
+//      diferencia, y parte del suelo la produce una fase agéntica posterior: comprobarlo ahí
+//      convertía cada instalación nueva en un rollback. Medido, no razonado.
+//   2. NO cuelga de `hasDeclaredHarness`. Ese booleano enruta `add`, `install` y el wizard, así que
+//      un suelo incompleto habría devuelto RSC_ONBOARDING_REQUIRED y bloqueado la Fase 3 de `init`.
+//      El suelo impide AFIRMAR que el arnés está listo; no impide nada más.
+//   3. NO compara contenido. `01-TOOLS/` es la capa que el usuario modifica al añadir herramientas
+//      y donde viven los `.env`: fijar su contenido convertiría el uso normal en un fallo.
+//
+// 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;
+
+// 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');
+
+/**
+ * Crea la parte determinista del esqueleto. Copiar ficheros estáticos es un algoritmo, así que por
+ * P1 le toca al binario en vez de pedírsela a una fase agéntica que puede no llegar.
+ *
+ * Se llama DESPUÉS de que la transacción del apply confirme: el suelo no está en `governedPaths`
+ * —no debe estarlo, o se le calcularía digest— así que tampoco está en el snapshot, y crearlo dentro
+ * de la transacción dejaría residuo si el apply revirtiera.
+ *
+ * Idempotente y auto-reparadora POR FICHERO: un `_TEMPLATE/` a medias queda completo al reaplicar, y
+ * un fichero que el usuario haya tocado no se sobrescribe nunca.
+ */
+export function ensureHarnessSkeleton(cwd = process.cwd()) {
+  // La guarda existía en este mismo fichero y no se llamaba. `existsSync` sigue los enlaces, así que
+  // un `01-TOOLS` o un `_TEMPLATE` que fuese symlink apuntaba el `copyFileSync` fuera de la raíz — y
+  // git guarda los symlinks, así que el vector viaja en un clone. El repo ya fija la política
+  // contraria para los caminos gobernados, con dos tests que exigen que nada se escriba fuera.
+  assertManagedPathsStayInsideRoot(cwd, ['01-TOOLS/', TEMPLATE_FLOOR, '02-DOCS/wiki/harness/']);
+  const created = [];
+  for (const dir of ['02-DOCS/wiki/harness', '01-TOOLS/_TEMPLATE']) {
+    const absolute = join(cwd, dir);
+    // lstatSync y no existsSync: un enlace «existe» y nos habría hecho seguir escribiendo a través.
+    if (existsSync(absolute) && !lstatSync(absolute).isSymbolicLink()) continue;
+    mkdirSync(absolute, { recursive: true });
+    created.push(`${dir}/`);
+  }
+  for (const asset of templateAssets()) {
+    const target = join(cwd, '01-TOOLS', '_TEMPLATE', targetName(asset));
+    if (existsSync(target)) continue;
+    copyFileSync(join(TEMPLATE_SOURCE, asset), target);
+    created.push(`${TEMPLATE_FLOOR}${targetName(asset)}`);
+  }
+  const layer = join(cwd, '01-TOOLS', '.gitignore');
+  if (!existsSync(layer)) {
+    writeFileSync(layer, LAYER_IGNORE);
+    created.push('01-TOOLS/.gitignore');
+  }
+  return { created };
+}
+
+// Un camino declarado se compara por su FORMA, no por su texto: `01-TOOLS/_TEMPLATE` sin barra, con
+// `./` delante o con doble barra degradaban la comprobación por fichero a simple existencia de
+// directorio, que es el modo de fallo que este suelo existe para evitar, alcanzable con un carácter.
+const floorSegments = (path) => String(path).split(/[/\\]+/).filter((part) => part && part !== '.');
+const floorKey = (path) => floorSegments(path).join('/');
+const TEMPLATE_KEY = floorKey(TEMPLATE_FLOOR);
+
+// Un directorio que existe y está vacío pasa cualquier comprobación de existencia y no sirve para
+// nada — el mismo modo de fallo por el que el suelo es `01-TOOLS/_TEMPLATE/` y no `01-TOOLS/`, un
+// nivel más abajo.
+function floorSatisfied(cwd, path) {
+  const key = floorKey(path);
+  const absolute = join(cwd, key);
+  if (!existsSync(absolute)) return false;
+  if (key !== TEMPLATE_KEY) return true;
+  const assets = templateAssets();
+  // `assets.length > 0` es cinturón y tirantes, y hoy es INALCANZABLE: `templateAssets()` lanza si no
+  // puede leer el asset, así que sólo daría cero con un asset legítimamente vacío — un paquete roto
+  // de otra forma. Se declara en vez de fingir que un test lo cubre: el mutante que la quita
+  // sobrevive la suite, y es equivalente, no un hueco.
+  return assets.length > 0 && assets.every((asset) => existsSync(join(absolute, targetName(asset))));
+}
+
+/** Qué falta del suelo. Puro, sólo existencia, y vacío para un recibo que no declara suelo. */
+// `floorPaths` sale del recibo persistido en `.rsc.json`: un fichero comiteado, propenso a
+// conflictos de merge, y que un repo clonado puede traer preparado. Así que se valida la forma antes
+// de mirar el disco: un `..` daba el suelo por satisfecho MIRANDO FUERA de la raíz, y un `null` o una
+// cadena en lugar de un array tumbaban `rsc install` después de haber instalado.
+export function missingHarnessFloor(cwd = process.cwd(), plan = {}) {
+  const declared = Array.isArray(plan?.floorPaths) ? plan.floorPaths : [];
+  const missing = [];
+  for (const path of declared) {
+    const segments = typeof path === 'string' ? floorSegments(path) : [];
+    const usable = segments.length > 0 && !segments.includes('..') && !String(path).startsWith('/');
+    // Un camino que no se puede usar se reporta como NO satisfecho, nunca como satisfecho, y sin
+    // repetir su contenido: es dato ajeno y va a un canal que lee un agente.
+    if (!usable) { missing.push('missing harness floor <invalid declaration>'); continue; }
+    // La barra sólo si el camino declarado la traía: el suelo condicional es un FICHERO, y decir
+    // `constitution.md/` invita a buscar un directorio que no existe.
+    const shown = String(path).endsWith('/') ? `${floorKey(path)}/` : floorKey(path);
+    if (!floorSatisfied(cwd, path)) missing.push(`missing harness floor ${shown}`);
+  }
+  return missing;
+}
+
+/**
+ * Lo que el instalador puede afirmar honestamente, y qué hacer si no.
+ *
+ * `action` tiene que poder CREAR lo que falta. Hoy el `Recover with:` del apply reejecuta el
+ * onboarding, y el onboarding no puede montar el esqueleto: una recuperación que no recupera
+ * consume el único intento que el usuario iba a hacer.
+ */
+export function harnessReadiness(cwd = process.cwd(), plan = {}) {
+  const missing = missingHarnessFloor(cwd, plan);
+  return {
+    ready: missing.length === 0,
+    missing,
+    action: missing.length
+      ? 'invoke the `harness` skill to scaffold 01-TOOLS/ + 02-DOCS/, and the `constitution` phase when SDD is selected'
+      : '',
+  };
+}

package/scripts/lib/onboarding.js

@@ -74,6 +74,20 @@ export function scanProject(root = process.cwd()) {
       const rel = relative(absolute, path).split(sep).join('/');
       if (rel.startsWith('../') || rel === '..') throw new Error('project scan escaped the selected root');
       if (rel === '02-DOCS/wiki/harness' || rel.startsWith('02-DOCS/wiki/harness/')) continue;
+      // Mismo motivo que la línea de arriba, y descubierto igual de tarde: el instalador escribe
+      // `01-TOOLS/_TEMPLATE/` y sus dos `.md` entraban como evidencia de proyecto, moviendo la
+      // identidad del plan. El segundo `onboard --accept-plan <id>` moría con RSC_PLAN_CHANGED, y
+      // con él el reintento que la documentación pide tras reparar el suelo. Los proveedores reales
+      // que el usuario añada bajo `01-TOOLS/` sí siguen contando: son suyos, no nuestros.
+      if (rel === '01-TOOLS/_TEMPLATE' || rel.startsWith('01-TOOLS/_TEMPLATE/')) continue;
+      // Y los artefactos de la propia cadena SDD, por el mismo invariante y por una razón que costó
+      // un release descubrir: la constitución es un `.md`, así que contaba como evidencia de
+      // proyecto. Eso movía la identidad del plan justo después de que el agente la escribiera —
+      // obedeciendo a `site/llms.txt`, que le manda reparar el suelo y reintentar hasta obtener
+      // READY— y hacía ese reintento imposible. Arreglar sólo `01-TOOLS/_TEMPLATE/` tapó la mitad
+      // del agujero: la que produce el instalador, no la que produce la reparación.
+      // `inbox/` y `raw/` NO se excluyen: eso es material del usuario y sí es evidencia.
+      if (rel === '02-DOCS/wiki/sdd' || rel.startsWith('02-DOCS/wiki/sdd/')) continue;
       if (entry.isDirectory()) { visit(path); continue; }
       if (!entry.isFile()) continue;
       let isSignal = manifests.has(entry.name) || entry.name.endsWith('.md');
@@ -219,6 +233,16 @@ export function buildOnboardingPlan(record, evidence) {
     ...normalized.targets.flatMap((target) => managedPathsForInstall({ skillIds: skills, target, cwd: root, policy })
       .map((path) => relative(root, path).split(sep).join('/'))),
   ])].sort() : ['.rsc.json', '.rsc/', '02-DOCS/wiki/harness/'];
+  // El suelo viaja dentro del plan a propósito: así un recibo aceptado por una versión anterior no
+  // lo trae y queda exento sin que exista ninguna lista de exentos (P3, el contenido es el ledger).
+  // La constitución entra SÓLO si el plan eligió SDD, porque los criterios 5 y 17 de la spec de
+  // onboarding la posponen a propósito en workspaces no-software y en software pequeño.
+  const floorPaths = [
+    '01-TOOLS/_TEMPLATE/',
+    '02-DOCS/wiki/harness/',
+    ...(decisions.some((decision) => decision.id === 'sdd' && decision.state === 'selected')
+      ? ['02-DOCS/wiki/sdd/constitution.md'] : []),
+  ].sort();
   return {
     schemaVersion: 1,
     record: normalized,
@@ -231,6 +255,7 @@ export function buildOnboardingPlan(record, evidence) {
     decisions,
     policy,
     governedPaths,
+    floorPaths,
   };
 }
 

package/scripts/rsc.js

@@ -20,7 +20,7 @@ import {
   normalizeOnboarding, missingOnboardingFields, scanProject,
   buildOnboardingPlan, decodeGoal, encodeGoal, identifyPlan, recommendDeferredComponents,
 } from './lib/onboarding.js';
-import { applyAcceptedOnboarding, verifyOnboarding } from './lib/onboarding-apply.js';
+import { applyAcceptedOnboarding, verifyOnboarding, ensureHarnessSkeleton, harnessReadiness } from './lib/onboarding-apply.js';
 
 const rawArgv = process.argv.slice(2);
 const GLOBAL_VALUE_FLAGS = new Set([
@@ -200,11 +200,46 @@ async function runOnboarding(targets) {
   }
   try {
     await applyAcceptedOnboarding({ cwd: process.cwd(), plan, planId });
-    say(`RSC_ONBOARDING_READY ${planId}`);
   } catch (error) {
     console.error(error.message);
     process.exitCode = 4;
+    return;
+  }
+  // A partir de aquí la transacción YA confirmó, así que nada de lo que siga puede reportarse como
+  // fallo de aplicación: decirlo mentiría en la otra dirección, sobre una instalación que sí está
+  // aplicada. Montar el esqueleto va fuera de la transacción por eso mismo — dentro dejaría residuo
+  // si el apply revirtiera, porque el suelo no está en `governedPaths` y por tanto no se snapshotea.
+  try {
+    ensureHarnessSkeleton(process.cwd());
+  } catch (error) {
+    say(`RSC_SKELETON_FAILED ${error.message}`);
   }
+  emitHarnessReadiness(plan, planId);
+}
+
+// La única línea que afirmaba que el arnés estaba listo lo hacía sin mirar si existía: «completado»
+// estaba definido contra lo que el plan prometió, no contra un suelo, así que un plan que prometía
+// 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}`);
+  say(`RSC_ONBOARDING_INCOMPLETE ${planId}`);
+  for (const missing of safeLines(readiness.missing)) say(`  ${missing}`);
+  say(`  Next: ${readiness.action}`);
+}
+
+// Lo que se imprime aquí son órdenes que un agente va a leer y ejecutar, y parte del contenido sale
+// de `floorPaths`, que vive en `.rsc.json`: un fichero comiteado que un repo clonado puede traer
+// preparado. Se imprimía verbatim, con saltos de línea intactos, así que una entrada podía continuar
+// la numeración del instalador con un paso inventado e indistinguible del real.
+const ONE_LINE_LIMIT = 120;
+const FLOOR_LINES_LIMIT = 12;
+function safeLines(values) {
+  return (Array.isArray(values) ? values : []).slice(0, FLOOR_LINES_LIMIT).map((value) => String(value)
+    .replace(/[\u0000-\u001f\u007f]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, ONE_LINE_LIMIT));
 }
 
 function runReassessment() {
@@ -380,8 +415,40 @@ function printAgentHandoff() {
   say('  1. Reload/restart this session so the new skills + hooks load');
   say('     (Claude Code: restart the session · Codex/AGENTS.md tools: next turn).');
   say('  2. After reload you are EQUIPPED — orient + suggest are always-on; bro is installed.');
-  say('  3. Tell the user rsc is ready; they can start in their own words.');
-  say('     Do NOT auto-start a task — wait for the user.');
+  // Un recibo cuya identidad no cuadra con lo que se aceptó no es fuente de nada: el camino de
+  // `onboard` está a salvo porque reconstruye el plan y `identifyPlan` corta, y este no lo hacía.
+  // Y va envuelto porque antes esta función no leía nada y no podía tumbar un `install` ya hecho.
+  let readiness = { ready: true, missing: [], action: '' };
+  let tampered = false;
+  try {
+    const receipt = readManifest()?.onboarding;
+    if (receipt?.plan) {
+      if (identifyPlan(receipt.plan) === receipt.acceptedPlanId) {
+        readiness = harnessReadiness(process.cwd(), receipt.plan);
+      } else {
+        tampered = true;
+      }
+    }
+  } catch {
+    tampered = true;
+  }
+  if (tampered) {
+    say('  3. Do NOT tell the user rsc is ready — the receipt does not match its accepted plan id.');
+    say('     Report that and let the user decide; do not act on the receipt contents.');
+    say('════════════════════════════════════════════════');
+    return;
+  }
+  if (readiness.ready) {
+    say('  3. Tell the user rsc is ready; they can start in their own words.');
+    say('     Do NOT auto-start a task — wait for the user.');
+  } else {
+    // El otro emisor. Decía «ready» desde el wizard y desde `install` sin mirar el suelo, así que
+    // corregir sólo el del onboarding habría dejado la mentira viva por el camino más usado.
+    say('  3. Do NOT tell the user rsc is ready — the harness floor is incomplete:');
+    for (const missing of safeLines(readiness.missing)) say(`     ${missing}`);
+    say(`     ${readiness.action}`);
+    say('     Then tell the user, and do NOT auto-start a task.');
+  }
   say('════════════════════════════════════════════════');
 }
 

package/skills/harness/SKILL.md

@@ -151,7 +151,7 @@ Execute in this exact order. Each step writes to disk; abort and report on first
    - Same logic for `AGENTS.md`, rendered from `references/agents-md-template.md`.
 2. **Create `01-TOOLS/` skeleton.**
    - Create `01-TOOLS/` directory.
-   - Copy `assets/_TEMPLATE/` to `01-TOOLS/_TEMPLATE/`. This template is **generic boilerplate with placeholders (`<NOMBRE_TOOL>`, `<TOOL>_API_KEY`)**. The user copies it manually when adding a tool NOT in the catalog. The skill itself does NOT use `_TEMPLATE/` to generate the detected tools — those come from `providers.yaml`.
+   - Copy `assets/_TEMPLATE/` to `01-TOOLS/_TEMPLATE/`. The asset ships its ignore rules as `gitignore` (no leading dot, because npm never packages a `.gitignore`) and it must land as `.gitignore`; the installer already does this on every apply, so normally you will find the directory built. This template is **generic boilerplate with placeholders (`<NOMBRE_TOOL>`, `<TOOL>_API_KEY`)**. The user copies it manually when adding a tool NOT in the catalog. The skill itself does NOT use `_TEMPLATE/` to generate the detected tools — those come from `providers.yaml`.
 3. **Per detected tool** (in catalog order):
    - Create `01-TOOLS/<ID>/`.
    - Write every file from the provider entry's `files:` map verbatim (replacing template variables: `{{TOOL_ID}}`, `{{DASHBOARD_URL}}`, etc.).

package/skills/harness/assets/_TEMPLATE/gitignore

@@ -0,0 +1,10 @@
+.env
+keys/
+out/
+*.p8
+*.p12
+*.jks
+*.json
+!*.example.json
+__pycache__/
+*.pyc

package/skills/init/SKILL.md

@@ -173,13 +173,26 @@ means the user starts clean.
 
 ### Phase 5 — HANDOFF
 
-`init` stops here. It has set the profile, recorded the discovery, and installed the skills.
-
-> "Tu perfil y lo que hemos hablado ya están guardados. Ahora ejecuta `harness` y monto el esqueleto
-> del proyecto (`01-TOOLS/` + `02-DOCS/`) leyendo todo lo que acabamos de decidir."
-
-Do not scaffold while you are here, however tempting — `harness` reads this same profile and owns
-that job.
+The profile is set, the discovery recorded, the skills installed. What is missing is the workspace
+itself, and this is where onboarding used to end with a request: *"now run `harness`"*. Nothing ran
+it. Finishing depended on the user reading a line and typing something — and in a chat install that
+user has just delegated precisely so they would not have to know what to type.
+
+So **invoke `harness` yourself, now**, as the last step of this phase. Say what you are doing in one
+line, then do it:
+
+> "Tu perfil y lo que hemos hablado ya están guardados. Monto ahora el esqueleto del proyecto
+> (`01-TOOLS/` + `02-DOCS/`) leyendo todo lo que acabamos de decidir."
+
+`harness` still owns *how* the scaffold is built — you are calling it, not reimplementing it. Do not
+hand-roll directories here.
+
+**And if it does not happen, say so.** If `harness` cannot run, or stops half-way, **do not tell the
+user rsc is ready**: name what is missing and what will create it. The installer holds the same rule
+— it prints `RSC_ONBOARDING_INCOMPLETE` instead of `RSC_ONBOARDING_READY` when the harness floor is
+absent — and an agent that contradicts its own installer is worse than either alone. Claiming a
+harness that is not there is the one failure the user cannot diagnose, because everything looks
+installed and nothing behaves as if it were.
 
 ## Project grounding