@trycore/spec-build-harness 0.8.4 → 0.10.0

package/dist/lib/paths.js

@@ -43,6 +43,7 @@ export const ASSETS = {
     buildConfigTemplate: path.join(PACKAGE_ROOT, 'config', 'build-config.template.json'),
     templateClaudeMd: path.join(PACKAGE_ROOT, 'templates', 'CLAUDE.md.template'),
     settingsHooksTemplate: path.join(PACKAGE_ROOT, 'templates', 'settings-hooks.template.json'),
+    assetTypes: path.join(PACKAGE_ROOT, 'asset-types.json'),
 };
 /** Rutas dentro del proyecto consumidor (relativas a `targetDir`). */
 export function targetPaths(targetDir) {
@@ -64,6 +65,11 @@ export function targetPaths(targetDir) {
         stateSchema: path.join(claudeDir, 'state', 'build-state.schema.json'),
         stateReadme: path.join(claudeDir, 'state', 'README.md'),
         stateFile: path.join(claudeDir, 'state', 'build-state.json'),
+        assetTypesFile: path.join(claudeDir, 'asset-types.json'),
+        runtimeCredentialsFile: path.join(claudeDir, 'state', 'runtime.credentials'),
+        runtimeLockFile: path.join(claudeDir, 'state', 'context.lock'),
+        runtimeProjectionFile: path.join(claudeDir, 'state', 'runtime-projection.json'),
+        outboxDir: path.join(claudeDir, 'state', 'outbox'),
         settingsFile: path.join(claudeDir, 'settings.json'),
         versionFile: path.join(claudeDir, '.build-harness-version'),
         claudeMd: path.join(targetDir, 'CLAUDE.md'),

package/dist/lib/runtime-client.js

@@ -0,0 +1,196 @@
+// runtime-client.ts — cliente TS del Agent Orchestrator Runtime, para el CLI (init/doctor/status).
+// Mismo contrato de red que hooks/build/lib/runtime-client.sh (docs/runtime/protocolo-cliente-runtime.md).
+// Fail-open: ninguna función lanza; ante red caída, timeout o JSON corrupto degrada a un
+// resultado distinguible ({ok:false, status:0}) y nunca corrompe el estado local.
+import fs from 'node:fs';
+import path from 'node:path';
+import { targetPaths } from './paths.js';
+function runtimePaths(targetDir) {
+    const t = targetPaths(targetDir);
+    return {
+        credentials: t.runtimeCredentialsFile,
+        lock: t.runtimeLockFile,
+        projection: t.runtimeProjectionFile,
+        outboxDir: t.outboxDir,
+        buildConfigFile: t.buildConfigFile,
+    };
+}
+/** runtime_mode: TRYCORE_RUNTIME_MODE (env) > build-config.json runtime.mode > "legacy". */
+export function runtimeMode(targetDir) {
+    const env = process.env.TRYCORE_RUNTIME_MODE;
+    const raw = env ?? readBuildConfigMode(targetDir);
+    return raw === 'dual' || raw === 'runtime' ? raw : 'legacy';
+}
+function readBuildConfigMode(targetDir) {
+    const p = runtimePaths(targetDir).buildConfigFile;
+    try {
+        const cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+        return typeof cfg?.runtime?.mode === 'string' ? cfg.runtime.mode : 'legacy';
+    }
+    catch {
+        return 'legacy';
+    }
+}
+/** Lee las credenciales; fail-open a {} si el fichero falta o es ilegible. */
+export function readCredentials(targetDir) {
+    const p = runtimePaths(targetDir).credentials;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(p, 'utf8'));
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Upsert atómico de un fragmento sobre runtime.credentials (0600, nunca imprime el token).
+ * Nunca lanza: devuelve false si la escritura falló.
+ */
+export function mergeCredentials(targetDir, fragment) {
+    const p = runtimePaths(targetDir).credentials;
+    const dir = path.dirname(p);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        const current = readCredentials(targetDir);
+        const merged = { ...current, ...fragment };
+        const tmp = path.join(dir, `.runtime-credentials.${process.pid}.${Date.now()}.tmp`);
+        fs.writeFileSync(tmp, JSON.stringify(merged, null, 2) + '\n', { mode: 0o600 });
+        fs.chmodSync(tmp, 0o600);
+        fs.renameSync(tmp, p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const TIMEOUT_MS = 10_000;
+/** Primitivo HTTP: nunca lanza. status=0 ante red caída/timeout/URL ausente. */
+async function request(url, method, token, body) {
+    if (!url)
+        return { ok: false, status: 0, body: null, raw: '' };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+        const headers = {};
+        if (token)
+            headers.Authorization = `Bearer ${token}`;
+        if (body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+            signal: controller.signal,
+        });
+        const raw = await res.text();
+        let parsed = null;
+        try {
+            parsed = raw ? JSON.parse(raw) : null;
+        }
+        catch {
+            parsed = null;
+        }
+        return { ok: res.ok, status: res.status, body: parsed, raw };
+    }
+    catch {
+        return { ok: false, status: 0, body: null, raw: '' };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * POST /agents/register — registra el agente CLI (bootstrap, fuera de una sesión Claude).
+ * En éxito (200), hace upsert de las credenciales devueltas. 409 -> incompatible=true
+ * (no reintentar sin actualizar el paquete).
+ */
+export async function registerAgent(targetDir, opts) {
+    const ok0 = mergeCredentials(targetDir, { runtime_url: opts.url, project_token: opts.token });
+    if (!ok0)
+        return { ok: false, status: 0, incompatible: false, message: 'no se pudieron escribir las credenciales locales' };
+    const res = await request(`${opts.url}/agents/register`, 'POST', opts.token, {
+        harness_version: opts.harnessVersion,
+        asset_types: opts.assetTypes ?? [],
+    });
+    if (res.status === 200 && res.body && typeof res.body === 'object') {
+        const d = res.body;
+        const frag = {};
+        for (const k of ['agent_key', 'project_id', 'poll_interval_s', 'lease_ttl_s', 'manifest_hash']) {
+            if (k in d)
+                frag[k] = d[k];
+        }
+        mergeCredentials(targetDir, frag);
+        return { ok: true, status: 200, incompatible: false };
+    }
+    if (res.status === 409) {
+        const minV = res.body?.min_version;
+        return { ok: false, status: 409, incompatible: true, message: minV ? `versión mínima requerida: ${minV}` : 'incompatible_version' };
+    }
+    return { ok: false, status: res.status, incompatible: false, message: res.status === 0 ? 'sin red / runtime inalcanzable' : `rechazo del servidor (${res.status})` };
+}
+/** GET /agent/context — refresco de proyección. Nunca escribe caché (eso es de las skills/hooks). */
+export async function getAgentContext(targetDir) {
+    const creds = readCredentials(targetDir);
+    if (!creds.runtime_url)
+        return { ok: false, status: 0, body: null, raw: '' };
+    return request(`${creds.runtime_url}/agent/context`, 'GET', creds.project_token);
+}
+/** Lectura fail-open de la caché de proyección (.claude/state/runtime-projection.json). */
+export function readProjection(targetDir) {
+    const p = runtimePaths(targetDir).projection;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(p, 'utf8'));
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Lectura fail-open del lockfile de contexto (.claude/state/context.lock). */
+export function readLock(targetDir) {
+    const p = runtimePaths(targetDir).lock;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(p, 'utf8'));
+        return {
+            manifestHash: typeof parsed?.manifest_hash === 'string' ? parsed.manifest_hash : null,
+            syncedAt: typeof parsed?.synced_at === 'string' ? parsed.synced_at : null,
+            fileCount: Array.isArray(parsed?.files) ? parsed.files.length : 0,
+        };
+    }
+    catch {
+        return { manifestHash: null, syncedAt: null, fileCount: 0 };
+    }
+}
+/** Estadísticas fail-open de la cola offline (.claude/state/outbox/*.json, sin dotfiles). */
+export function outboxStats(targetDir) {
+    const dir = runtimePaths(targetDir).outboxDir;
+    try {
+        const files = fs.readdirSync(dir).filter((f) => f.endsWith('.json') && !f.startsWith('.'));
+        let totalBytes = 0;
+        let oldestMs = null;
+        for (const f of files) {
+            const st = fs.statSync(path.join(dir, f));
+            totalBytes += st.size;
+            if (oldestMs === null || st.mtimeMs < oldestMs)
+                oldestMs = st.mtimeMs;
+        }
+        return {
+            count: files.length,
+            totalBytes,
+            oldestAgeSeconds: oldestMs === null ? null : Math.floor((Date.now() - oldestMs) / 1000),
+        };
+    }
+    catch {
+        return { count: 0, totalBytes: 0, oldestAgeSeconds: null };
+    }
+}
+/** ¿El host resuelve una URL http(s) mínimamente bien formada? Validación local, sin red. */
+export function isPlausibleUrl(url) {
+    try {
+        const u = new URL(url);
+        return u.protocol === 'http:' || u.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/settings-merge.js

@@ -24,13 +24,13 @@ function cmd(script) {
 const STATUSLINE_CMD = cmd('statusline-bridge.sh');
 /** Las agrupaciones de hooks del arnés (= las de hooks/build-harness.json). */
 const HOOK_SPECS = [
-    { event: 'SessionStart', matcher: 'startup|clear|compact', scripts: ['load-build-state.sh'] },
+    { event: 'SessionStart', matcher: 'startup|clear|compact', scripts: ['session-start.sh', 'load-build-state.sh'] },
     { event: 'PreToolUse', matcher: 'Bash', scripts: ['gitflow-guard.sh'] },
     { event: 'PreToolUse', matcher: 'Write|Edit|MultiEdit', scripts: ['stack-guard.sh', 'scaffold-guard.sh', 'design-source-guard.sh'] },
     { event: 'PostToolUse', matcher: 'Write|Edit|MultiEdit', scripts: ['lint-typecheck.sh', 'coherence-flag.sh'] },
-    { event: 'PostToolUse', matcher: 'Bash|Edit|Write|MultiEdit|Task', scripts: ['context-monitor.sh'] },
+    { event: 'PostToolUse', matcher: 'Bash|Edit|Write|MultiEdit|Task', scripts: ['context-monitor.sh', 'event-emitter.sh'] },
     { event: 'PreCompact', matcher: '.*', scripts: ['context-monitor.sh'] },
-    { event: 'Stop', matcher: '.*', scripts: ['build-gate-check.sh', 'reflect-nudge.sh', 'release-gate-nudge.sh', 'context-monitor.sh'] },
+    { event: 'Stop', matcher: '.*', scripts: ['build-gate-check.sh', 'reflect-nudge.sh', 'release-gate-nudge.sh', 'dual-compare.sh', 'context-monitor.sh', 'session-stop.sh'] },
 ];
 /** Permisos MÍNIMOS y enumerados [H11]. Nunca permisos amplios (mcp__*, additionalDirectories…). */
 const MIN_PERMISSIONS = [

package/dist/lib/state-bundle.js

@@ -0,0 +1,46 @@
+// state-bundle.ts — prepara el BUNDLE NORMALIZADO que un ADMIN importa en la
+// consola del hub. Mismo principio de gobierno que scripts/lib/graph-bundle.py
+// (protocolo-cliente-runtime §6, spec §4.1-D rev. 4): el arnés PREPARA y
+// VALIDA en local — nunca sube nada. `migrate` es la contraparte CLI del
+// import histórico (docs/superpowers/specs/2026-08-20-cliente-migrate-normalizacion-eventos-design.md):
+// convierte el build-state.json legacy del piloto en la forma ImportBundleIn
+// que ya entiende el import del hub — eventos del catálogo v2, no snapshots crudos.
+import { normalizeHistory, normalizeReleases, normalizeFront, normalizeFacts, validateNormalizedBundle, } from './normalize.js';
+export const STATE_BUNDLE_VERSION = 2;
+const EPOCH_ISO = new Date(0).toISOString();
+export function buildStateBundle(raw, projectRef) {
+    const warnings = [];
+    const st = typeof raw === 'object' && raw !== null && !Array.isArray(raw) ? raw : {};
+    if (raw !== null && (typeof raw !== 'object' || Array.isArray(raw))) {
+        warnings.push('build-state.json no es un objeto JSON: se trata como vacío');
+    }
+    const historyRaw = Array.isArray(st.history) ? st.history : [];
+    if (st.history !== undefined && !Array.isArray(st.history)) {
+        warnings.push('history no es un array: se descarta (0 slices migrados)');
+    }
+    const releasesRaw = Array.isArray(st.releases) ? st.releases : [];
+    if (st.releases !== undefined && !Array.isArray(st.releases)) {
+        warnings.push('releases no es un array: se descarta (0 releases migradas)');
+    }
+    const { entries: history, unmapped: historyUnmapped } = normalizeHistory(historyRaw);
+    const { entries: releases, unmapped: releasesUnmapped } = normalizeReleases(releasesRaw);
+    const front = normalizeFront(st.parallel_front ?? null);
+    const fronts = front ? [front] : [];
+    const facts = normalizeFacts(st, EPOCH_ISO);
+    const unmapped = [...historyUnmapped, ...releasesUnmapped];
+    const validationErrors = validateNormalizedBundle({ history, releases, fronts });
+    return {
+        bundle_version: STATE_BUNDLE_VERSION,
+        kind: 'state',
+        project_ref: projectRef,
+        generated_by: 'trycore-build-harness/state-bundle.ts',
+        facts,
+        history,
+        releases,
+        fronts,
+        unmapped,
+        out_of_scope: [],
+        warnings,
+        validation_errors: validationErrors,
+    };
+}

package/docs/commands.md

@@ -2,8 +2,8 @@
 
 Esta referencia cubre los **dos planos de operación** del arnés de construcción:
 
-1. El **CLI `trycore-build`** (binario Node, paquete `@trycore/spec-build-harness` v0.7.0) — instala, actualiza, diagnostica y desinstala el arnés en el proyecto consumidor. Captura el **stack mecánico**.
-2. Los **slash commands de Claude Code** (`/opsx:*` + los 8 `/build:*`: `onboard`, `reflect`, `architect`, `slice`, `release`, `work`, `resume`, `front`) — operan el pipeline de dos loops, resuelven la parametrización **semántica** del dominio y capturan el conocimiento aprendido por slice.
+1. El **CLI `trycore-build`** (binario Node, paquete `@trycore/spec-build-harness`) — instala, actualiza, diagnostica y desinstala el arnés en el proyecto consumidor. Captura el **stack mecánico** y, opcionalmente, registra el proyecto contra el Agent Orchestrator Runtime.
+2. Los **slash commands de Claude Code** (`/opsx:*` + los 12 `/build:*`: `onboard`, `reflect`, `architect`, `prototype`, `slice`, `release`, `work`, `resume`, `front`, `claim`, `status`, `escalate`) — operan el pipeline de dos loops, resuelven la parametrización **semántica** del dominio y capturan el conocimiento aprendido por slice.
 
 > **División de responsabilidades del onboarding (dos capas).** Un binario Node **no puede** escribir la auto-memory de Claude. Por eso `trycore-build init` siembra archivos y captura el stack mecánico (lenguaje/deps, package manager, runtime, ruta del PRD), y el slash command `/build:onboard` —ejecutado por Claude— lee el PRD, pregunta por PII / capa de servicios externos-IA / capa determinista / secretos / decisiones de alto impacto, resuelve los `{{placeholders}}` del bloque marcado de `CLAUDE.md` y escribe la auto-memory.
 
@@ -11,19 +11,20 @@ Esta referencia cubre los **dos planos de operación** del arnés de construcci
 
 ## 1. CLI `trycore-build`
 
-Comandos: `init` · `update` · `status` · `uninstall` · `doctor`. Todos aceptan un argumento posicional opcional `[directory]` (por defecto `.`, el directorio actual).
+Comandos: `init` · `update` · `status` · `uninstall` · `doctor` · `migrate`. Todos aceptan un argumento posicional opcional `[directory]` (por defecto `.`, el directorio actual).
 
 | Comando | Propósito |
 |---|---|
-| `init [directory]` | Instala el arnés en el proyecto (idempotente: re-correrlo es seguro). Siembra agentes, comandos, skills y hooks; captura el stack mecánico; inserta el bloque marcado en `CLAUDE.md` y `.gitignore`; mergea hooks + permisos mínimos en `settings.json`. **Falla (exit 1)** si faltan requisitos externos duros (`openspec`, `python3`, `git`), salvo `--skip-doctor`. |
+| `init [directory]` | Instala el arnés en el proyecto (idempotente: re-correrlo es seguro). Siembra agentes, comandos, skills y hooks; captura el stack mecánico; inserta el bloque marcado en `CLAUDE.md` y `.gitignore`; mergea hooks + permisos mínimos en `settings.json`. Con `--runtime-url`/`--runtime-token` (opcional, beta — EP-OR-08), registra el agente contra el Agent Orchestrator Runtime y dispara el primer sync de contexto; sin esas flags, el proyecto queda en modo `legacy` (default). **Falla (exit 1)** si faltan requisitos externos duros (`openspec`, `python3`, `git`), salvo `--skip-doctor`. |
 | `update [directory]` | Refresca assets y schema tras actualizar el paquete npm. Alias no interactivo de `init` en modo `update`. **Nunca** pisa `build-state.json` ni `stack-allowlist.json` (estado y allowlist son del consumidor). |
-| `status [directory]` | Muestra estado de la instalación (versión instalada vs. paquete, drift), conteo de componentes, requisitos externos y la fase actual del arnés leída de `build-state.json` (slice activo, gates abiertos, historial, releases). |
+| `status [directory]` | Muestra estado de la instalación (versión instalada vs. paquete, drift), conteo de componentes, requisitos externos y la fase actual del arnés. En modo `legacy`, la lee de `build-state.json`; en `dual`/`runtime`, además muestra conectividad con el runtime y la caché de proyección. |
 | `uninstall [directory]` | Quita **solo** lo que `init` puso (agentes, comandos, skills del arnés, hooks, bloques marcados, permisos en `settings.json`). **Preserva** `.claude/state/` y `.claude/config/` (estado vivo y allowlist del equipo). |
-| `doctor [directory]` | Verifica requisitos externos (`openspec`/`python3`/`git`), bit ejecutable de los hooks y la detección de doble canal en `settings.json`. **Falla (exit 1)** si falta un requisito duro. |
+| `doctor [directory]` | Verifica requisitos externos (`openspec`/`python3`/`git`), bit ejecutable de los hooks y la detección de doble canal en `settings.json`. En `dual`/`runtime`, además verifica token, conectividad, frescura del lock de contexto y tamaño de la cola offline. **Falla (exit 1)** si falta un requisito duro. |
+| `migrate [directory]` | (Beta — EP-OR-08.) Prepara el **bundle de estado** (`history[]`/`releases[]`/hechos de proyecto de `build-state.json`) para que un **ADMIN** lo importe en la consola del hub. **Nunca sube nada**: el import es acto de gobierno. `--out <path>` (default `.claude/state/migration-bundle.json`) · `--project-ref <ref>`. |
 
 ### Flags
 
-Solo `init` y `update` aceptan flags. `status`, `uninstall` y `doctor` toman únicamente `[directory]`.
+`init`, `update` y `migrate` aceptan flags. `status`, `uninstall` y `doctor` toman únicamente `[directory]`.
 
 | Flag | Comandos | Propósito |
 |---|---|---|
@@ -35,6 +36,11 @@ Solo `init` y `update` aceptan flags. `status`, `uninstall` y `doctor` toman ún
 | `--pkg-manager <pm>` | `init` | Package manager: `npm` \| `pnpm` \| `yarn` (default `npm`). |
 | `--runtime <semver>` | `init` | Semver del runtime, p. ej. `">=18.18"` (default `>=18.18`). |
 | `--prd-path <path>` | `init` | Ruta#ancla del PRD técnico, fuente del allowlist (p. ej. `docs/01-prd/<tu-prd>.md#requisitos-tecnicos`). |
+| `--runtime-url <url>` | `init` | (Beta.) URL del Agent Orchestrator Runtime. Junto con `--runtime-token`, registra el agente y hace el primer sync de contexto. Un runtime inalcanzable **nunca aborta** `init`: degrada a `legacy` y se reintenta en la primera sesión Claude. |
+| `--runtime-token <token>` | `init` | (Beta.) Token de proyecto emitido por un ADMIN en la consola del hub. Se guarda en `.claude/state/runtime.credentials` (0600, gitignored). |
+| `--runtime-mode <mode>` | `init` | (Beta.) `legacy`\|`dual`\|`runtime` tras un registro exitoso (default `dual` si diste URL+token). Ver `docs/runtime/guia-modo-dual-y-migracion.md`. |
+| `--out <path>` | `migrate` | Ruta de salida del bundle de estado (default `.claude/state/migration-bundle.json`). |
+| `--project-ref <ref>` | `migrate` | Identificador del proyecto en el hub (default: nombre del directorio). |
 
 > Si pasas todos los datos del stack por flags (o usas `--yes`, o no hay TTY), `init` **no** abre prompt interactivo y usa flags/defaults; deja un aviso para ajustar `.claude/config/stack-allowlist.json` o correr `/build:onboard` después.
 
@@ -52,7 +58,7 @@ Solo `init` y `update` aceptan flags. `status`, `uninstall` y `doctor` toman ún
 
 ## 2. Slash commands de Claude Code
 
-El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y `.claude/commands/build/` → los 8 `/build:*` (`onboard`, `reflect`, `architect`, `slice`, `release`, `work`, `resume`, `front`).
+El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y `.claude/commands/build/` → los 12 `/build:*` (`onboard`, `reflect`, `architect`, `prototype`, `slice`, `release`, `work`, `resume`, `front`, `claim`, `status`, `escalate`).
 
 ### `/opsx:*` — pipeline OpenSpec
 
@@ -117,6 +123,23 @@ El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y
 |---|---|
 | `/build:front` | Abre y coordina un **front paralelo** de épicas NO fundacionales y disjuntas en archivos, cada una en su propio worktree/rama/PR. Delega en la skill `managing-parallel-front`: verifica precondiciones (scaffold confirmado, sin épica foundational abierta), selecciona el conjunto disjunto (`scripts/lib/front-plan.py`) y mergea en orden con re-smoke. Úsalo solo con ≥2 épicas no fundacionales disjuntas listas; para una sola épica, usa `/build:slice`. |
 
+### `/build:prototype` — prototipo HTML de referencia (fuente de diseño)
+
+| Slash command | Propósito |
+|---|---|
+| `/build:prototype` | Genera o amplía el **prototipo HTML de referencia** (el `DESIGN_SOURCE`) en `docs/05-prototipo/` (`DESIGN.md` + `tokens.css` + `manifest.json` + un HTML autocontenido por pantalla). Adaptador delgado: **delega** en la skill `prototyping-screens`. Dos modos — **greenfield** (`/build:prototype`): inventario de pantallas desde PRD/mapa/historias → confirmación humana → dirección estética (manual de marca o 2-3 variantes a elección humana) → generación por lotes con auto-verificación visual; **feature** (`/build:prototype <épica>`): pantallas nuevas coherentes con el UX/UI **ya implementado**, con **precondición dura** (app corriendo + MCP de inspección de UI: extrae CSS computado real, screenshots en 3 viewports y estructura; sin degradación estática). Es **outer-loop** (antes de abrir slices). **La skill genera; el humano aprueba**: las pantallas nacen `borrador`, solo las `aprobada` son fuente de verdad (las lee `ux-fidelity-reviewer` vía `manifest.json`) y `design_source.confirmed` sigue siendo humano. |
+
+### `/build:claim`, `/build:status`, `/build:escalate` — superficie de agente del runtime (beta, opt-in)
+
+Adaptadores delgados sobre `slice-ops.sh`; en modo `legacy` (default) devuelven `rc 3` y remiten al
+protocolo del fichero (`/build:slice`) — no rompen el flujo normal si el proyecto no está migrado.
+
+| Slash command | Propósito |
+|---|---|
+| `/build:claim [EP-XXX]` | Pide la siguiente tarea al runtime (`POST /tasks/next`): sincroniza contexto, reporta hashes locales (detección de drift) y reclama por lease. Si trae `CHECKPOINT`, continúa desde ahí — **nunca reinicia** un slice de otro agente. |
+| `/build:status` | Informe de solo lectura: modo, slice activo, gates, wiring failing, versión de contexto, lease y cola de eventos pendientes. Nunca transiciona nada. |
+| `/build:escalate <razón>` | Registra un bloqueo en el runtime (`escalation_raised`) y devuelve la decisión a un humano — recortar, diferir o desbloquear **nunca** lo decide el modelo (mismo principio que la regla 8 de METODOLOGIA §10). |
+
 ---
 
 ## 3. Caveat de canales (CLI vs. plugin)
@@ -126,7 +149,7 @@ El arnés se distribuye por **dos canales** que coexisten, pero **namespacean di
 | Aspecto | Canal **CLI** (canónico) | Canal **Plugin** nativo |
 |---|---|---|
 | Instalación | `npm i -g @trycore/spec-build-harness` → `trycore-build init` | `/plugin marketplace add <repo-github>` → `/plugin install trycore-spec-build-harness@trycore-build` |
-| Namespace de comandos | Por subcarpeta: `/opsx:*` y los 8 `/build:*` (`onboard`, `reflect`, `architect`, `slice`, `release`, `work`, `resume`, `front`) | Por nombre del plugin: `/trycore-spec-build-harness:*` (por diseño de Claude Code) |
+| Namespace de comandos | Por subcarpeta: `/opsx:*` y los 9 `/build:*` (`onboard`, `reflect`, `architect`, `prototype`, `slice`, `release`, `work`, `resume`, `front`) | Por nombre del plugin: `/trycore-spec-build-harness:*` (por diseño de Claude Code) |
 | Referencia a agentes | Por su nombre (p. ej. `build-orchestrator`) | Bajo el nombre del plugin |
 | Cross-references internas | ✔ Escritas para este canal (skills invocan `/opsx:*`, agentes por nombre) | Pueden no resolver según están escritas |
 | Recomendación | **Usar este canal para operar un proyecto** | Conveniencia a nivel usuario |

package/docs/getting-started.md

@@ -48,7 +48,7 @@ npm i -g @fission-ai/openspec @trycore/spec-build-harness
 
 ## 2 · `trycore-build init` (terminal)
 
-Desde la raíz de tu proyecto. Es **idempotente** (re-correrlo es seguro) y siembra: **14 agentes**, **15 skills** (`building-a-slice`, `building-a-micro-change`, `releasing-a-version`, `managing-parallel-front`, `setup-architecture` + 10 `openspec-*`), **10 comandos `/opsx:*`** + **8 comandos `/build:*`** (`onboard`, `reflect`, `architect`, `slice`, `release`, `work`, `resume`, `front`), **13 hooks**, el estado vacío `.claude/state/build-state.json` (gitignored, nunca se sobreescribe) y el bloque `<!-- BEGIN trycore-build-harness -->` en tu `CLAUDE.md` con `{{placeholders}}` sin resolver.
+Desde la raíz de tu proyecto. Es **idempotente** (re-correrlo es seguro) y siembra: **14 agentes**, **16 skills** (`building-a-slice`, `building-a-micro-change`, `releasing-a-version`, `managing-parallel-front`, `setup-architecture`, `prototyping-screens` + 10 `openspec-*`), **10 comandos `/opsx:*`** + **9 comandos `/build:*`** (`onboard`, `reflect`, `architect`, `prototype`, `slice`, `release`, `work`, `resume`, `front`), **13 hooks**, el estado vacío `.claude/state/build-state.json` (gitignored, nunca se sobreescribe) y el bloque `<!-- BEGIN trycore-build-harness -->` en tu `CLAUDE.md` con `{{placeholders}}` sin resolver.
 
 ```bash
 trycore-build init
@@ -121,5 +121,6 @@ Al archivar una épica, la skill te **pregunta** si correr el Release Gate (defa
 - **Agentes** → [`docs/agents.md`](agents.md) · **Hooks** → [`docs/hooks.md`](hooks.md) · **Comandos** → [`docs/commands.md`](commands.md)
 - **Metodología** (manda ante cualquier skill) → [`METODOLOGIA.md`](../METODOLOGIA.md)
 - **Extender con MCP/LSP** (opt-in) → [`docs/customization/`](customization/)
+- **Modo runtime** (cliente de un Agent Orchestrator Runtime, beta/opt-in) → [`docs/runtime/guia-modo-dual-y-migracion.md`](runtime/guia-modo-dual-y-migracion.md)
 
 > El core es **100% agnóstico** al proyecto. El ejemplo de referencia completo vive aparte en `docs/examples/reference/` (no forma parte del core).