@trycore/spec-build-harness 0.4.0 → 0.6.0

package/commands/build/onboard.md

@@ -1,6 +1,6 @@
 ---
 name: "BUILD: Onboard"
-description: Parametriza el dominio del build harness — capa de servicios externos/IA, lógica determinista, PII, secretos y decisiones de alto impacto. Rellena el bloque marcado de CLAUDE.md y escribe auto-memory. Complementa al CLI trycore-build init (que ya sembró los archivos y el stack mecánico).
+description: Parametriza el dominio del build harness — capa de servicios externos/IA, lógica determinista, PII, secretos, decisiones de alto impacto y fuente de diseño (DESIGN_SOURCE). Rellena el bloque marcado de CLAUDE.md y escribe auto-memory. Complementa al CLI trycore-build init (que ya sembró los archivos y el stack mecánico).
 category: Workflow
 tags: [onboarding, parametrizacion, build-harness, trycore]
 ---
@@ -35,7 +35,7 @@ Stop aquí si no está instalado.
 
 El CLI ya instaló agentes, comandos /opsx:*, hooks y el estado. Ahora voy a parametrizar el
 DOMINIO del arnés (2-3 min) — los puntos de extensión que leen los agentes de calidad
-(security-reviewer, stack-guardian, data-consistency-checker, ux-krug-reviewer, simple-design-reviewer).
+(security-reviewer, stack-guardian, data-consistency-checker, ux-krug-reviewer, simple-design-reviewer, ux-fidelity-reviewer).
 
 Voy a leer tu PRD/openspec para proponer valores y confirmar contigo:
 1. Ruta#ancla del PRD técnico (fuente del stack)
@@ -44,6 +44,8 @@ Voy a leer tu PRD/openspec para proponer valores y confirmar contigo:
 4. Categorías de datos sensibles / PII reguladas
 5. Secretos server-side
 6. Decisiones de alto impacto que exigen explicabilidad en UX
+7. Fuente de diseño / referencia visual (prototipo/export) y pantallas — o "N/A" si no hay UI
+8. Capa de cada épica del backlog: **fundacional** (cimiento) vs **negocio**
 ```
 
 ---
@@ -61,17 +63,37 @@ Voy a leer tu PRD/openspec para proponer valores y confirmar contigo:
    - **Datos sensibles / PII** (`SENSITIVE_DATA_CATEGORIES`): categorías reguladas del dominio.
    - **Secretos server-side** (`SERVER_SIDE_SECRETS`): claves/tokens que jamás van al cliente.
    - **Decisiones de alto impacto** (`HIGH_STAKES_DECISIONS`): decisiones que exigen explicabilidad/justificación en la UI.
+   - **Fuente de diseño** (`DESIGN_SOURCE`): ¿el producto tiene UI? Si sí, ruta/URL de la fuente
+     visual de verdad (prototipo, export de diseño o mockups) y cómo localizar cada pantalla; si no,
+     "N/A". (La escritura del estado `design_source` en `build-state.json` se hace en la Fase 3c.)
 3. Si un punto no aplica al proyecto, registra explícitamente "no aplica" (no lo dejes como `{{...}}`).
 
 ---
 
+## Fase 2b: Clasificar la capa de las épicas (cimiento vs negocio)
+
+El factor que más reduce el consumo de contexto por slice es que el **cimiento** ya esté construido y
+abstraído antes de que el loop tome historias de negocio. Para habilitar el gate de DoR "Cimiento
+construido":
+1. Lee el backlog/Story Map del proyecto (`docs/03-backlog/epicas.md`, `docs/02-user-story-map/`).
+2. Propón, vía **AskUserQuestion**, qué épicas son **`layer: foundational`** (autenticación, acceso a
+   datos, arquitectura base, design-system/componentes base del prototipo) y cuáles **`layer: business`**.
+3. Escribe el tag en el **frontmatter de cada épica** en `docs/03-backlog/epicas.md` (artefacto de
+   discovery; coordina con `@trycore/spec-product-flow` si ese paquete ya lo gobierna — el build-harness
+   solo necesita poder **leer** `layer`). El DoR rechazará abrir una épica de negocio que arrastre
+   cimiento `foundational` aún no archivado.
+
+No inventes la clasificación: derívala del PRD/Story Map y confírmala con el usuario.
+
+---
+
 ## Fase 3: Resolver el bloque de CLAUDE.md
 
 Lee `CLAUDE.md`. Encuentra el bloque entre `<!-- BEGIN trycore-build-harness` y `<!-- END trycore-build-harness -->`.
 
 Reemplaza dentro del bloque los placeholders `{{PRD_TECH_PATH}}`, `{{EXTERNAL_SERVICE_LAYER}}`,
 `{{DETERMINISTIC_LAYER}}`, `{{SENSITIVE_DATA_CATEGORIES}}`, `{{SERVER_SIDE_SECRETS}}`,
-`{{HIGH_STAKES_DECISIONS}}` por los valores confirmados.
+`{{HIGH_STAKES_DECISIONS}}`, `{{DESIGN_SOURCE}}` por los valores confirmados.
 
 **NO toques nada fuera de los markers.**
 
@@ -87,6 +109,16 @@ Si el usuario lo desea y existe `package.json` en el proyecto:
 
 ---
 
+## Fase 3c: (Si hay UI) Confirmar la fuente de diseño en el estado
+
+Espejo de la confirmación de scaffold, para `design_source` en `build-state.json`:
+- Si el producto **tiene UI**: setea `design_source.applies=true`, `source` (el puntero confirmado) y
+  `confirmed=true` **solo si** el usuario confirma que la fuente de diseño existe (con `confirmed_by`,
+  `confirmed_at`). El arnés **no genera** el prototipo.
+- Si **no hay UI**: setea `design_source.applies=false` (el mecanismo de fidelidad queda N/A).
+
+---
+
 ## Fase 4: Guardar en auto-memory
 
 Crear/actualizar memorias **tipo `project`** (los valores cambian por proyecto):
@@ -97,6 +129,7 @@ Crear/actualizar memorias **tipo `project`** (los valores cambian por proyecto):
 - `build_sensitive_data.md` → categorías PII/datos regulados
 - `build_server_side_secrets.md` → secretos server-side
 - `build_high_stakes_decisions.md` → decisiones de alto impacto
+- `build_design_source.md` → fuente de diseño / referencia visual
 
 Cada memoria con frontmatter `type: project`. Agrega entradas a `MEMORY.md`.
 
@@ -113,6 +146,7 @@ Determinista:       <...>
 PII/datos:          <...>
 Secretos:           <...>
 Decisiones clave:   <...>
+Fuente diseño:      <...>
 
 CLAUDE.md actualizado. Auto-memory escrita. Los agentes de calidad ya leen tu dominio.
 
@@ -129,7 +163,7 @@ CLAUDE.md actualizado. Auto-memory escrita. Los agentes de calidad ya leen tu do
 
 ## Guardrails
 
-- No avances sin confirmar los 6 puntos. Si el usuario omite alguno, repregunta o marca "no aplica".
+- No avances sin confirmar los 7 puntos. Si el usuario omite alguno, repregunta o marca "no aplica".
 - Si CLAUDE.md no tiene el bloque marcado (caso raro post-install), pide correr `trycore-build init` (o `update`) antes de seguir.
 - No inventes valores de dominio que no estén en el PRD ni confirmados por el usuario.
 - Si un valor ya existe en memory y cambió, sobrescríbelo (los proyectos evolucionan).

package/dist/lib/settings-merge.js

@@ -18,7 +18,7 @@ function cmd(script) {
 const HOOK_SPECS = [
     { event: 'SessionStart', matcher: 'startup|clear|compact', scripts: ['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'] },
+    { 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: 'Stop', matcher: '.*', scripts: ['build-gate-check.sh', 'reflect-nudge.sh'] },
 ];

package/dist/lib/state-seed.js

@@ -11,6 +11,7 @@ const EMPTY_STATE = {
     version: '1.0',
     harness_phase: 'authoring',
     scaffold: { confirmed: false, confirmed_by: null, confirmed_at: null, notes: '' },
+    design_source: { applies: false, confirmed: false, confirmed_by: null, confirmed_at: null, source: '', notes: '' },
     active_slice: null,
     history: [],
     releases: [],

package/docs/agents.md

@@ -1,13 +1,14 @@
 # Agentes de construcción (`agents/build/`)
 
-Los **10 agentes** de `@trycore/spec-build-harness` ejecutan los *gates* del arnés de
+Los **12 agentes** de `@trycore/spec-build-harness` ejecutan los *gates* del arnés de
 construcción de dos loops. Ninguno edita código de producto: son read-only sobre el
 repositorio (algunos ejecutan tests o levantan la app), diagnostican y **devuelven el
 veredicto al `build-orchestrator`**, que es quien propone la escritura del estado
 (`.claude/state/build-state.json`).
 
 > **Cadencia.** El `build-orchestrator` y `dor-dod-gatekeeper`, junto con
-> `change-epic-coherence`, `api-contract-tester` y `data-consistency-checker`, corren en el
+> `change-epic-coherence`, `api-contract-tester`, `data-consistency-checker`,
+> `ux-fidelity-reviewer` y `wiring-adversarial-verifier`, corren en el
 > **inner loop** (skill `building-a-slice`, por épica `EP-XXX`). Los 5 revisores pesados de
 > release (`security-reviewer`, `simple-design-reviewer`, `ux-krug-reviewer`,
 > `coherence-three-way`, `stack-guardian`) corren **una vez por release** en el **outer loop**
@@ -27,6 +28,8 @@ veredicto al `build-orchestrator`**, que es quien propone la escritura del estad
 | 8 | `api-contract-tester` | sonnet | Contrato / datos | Gate `api` — pruebas de contrato (Newman/Postman) |
 | 9 | `data-consistency-checker` | sonnet | Contrato / datos | Gate `data` — invariantes y consistencia de datos |
 | 10 | `change-epic-coherence` | sonnet | Trazabilidad | Gate `coherence_link` — enlace change↔épica↔HU |
+| 11 | `ux-fidelity-reviewer` | sonnet | Inner loop · smoke | Gate `fidelity` — fidelidad visual a la fuente de diseño declarada (verificación visual real, MCP) |
+| 12 | `wiring-adversarial-verifier` | **opus** | Inner loop · dod | Gate `wiring_verified` — verificación adversarial independiente del cableado (refuta antes de cerrar `dod`) |
 
 ---
 
@@ -131,3 +134,24 @@ exista en `docs/04-historias/` con `epica:` coincidente, la coherencia de alcanc
 `openspec validate <name> --type change --strict` pase; sugiere back-references. COHERENTE →
 `gates.coherence_link: true`. Complementa a `coherence-three-way` validando el **enlace**
 (este último valida la implementación real).
+
+## Inner loop · fidelidad y cableado
+
+### `ux-fidelity-reviewer` · modelo `sonnet` · lee el dominio
+**Revisor de fidelidad visual** (gate `fidelity`), en la fase `smoke`. Comprueba que la pantalla
+construida reproduce **composición, layout, paleta y tipografía** de la fuente de diseño declarada
+(`DESIGN_SOURCE`). **Verificación visual real, requerida para UI**: con la app corriendo usa un MCP de
+devtools de navegador (chrome-devtools) — `take_screenshot` app vs prototipo + `take_snapshot` de
+estructura. Sin MCP el veredicto es INCONCLUSO, que para UI mapea a `gates.fidelity: false` (bloquea el
+`dod`): hay que correr el slice donde el MCP esté disponible. No juzga usabilidad (eso es
+`ux-krug-reviewer`, en el outer loop).
+
+### `wiring-adversarial-verifier` · modelo `opus` · contexto virgen
+**Verificador adversarial del cableado** (gate `wiring_verified`), al inicio de la fase `dod`. Llega
+con contexto virgen e **independiente** del que construyó: su sesgo por defecto es "está incompleto" y
+su trabajo es **refutar** el slice — cazar stubs, rutas sin cablear (endpoint sin invocar, cola sin
+consumidor, componente sin enrutar), AC sin test real, puntos de integración entre capas no recorridos,
+e items de `wiring_checklist[]` aún `failing` o marcados `passing` sin `evidence`. CABLEADO COMPLETO →
+`gates.wiring_verified: true` (habilita `dod`); HUECOS → `false` (retrocede `phase`). Rompe la
+auto-confirmación del cierre prematuro: el DoD declarativo del `dor-dod-gatekeeper` es un piso, este
+agente es el arreglo.

package/docs/customization/mcp-extensions.md

@@ -2,16 +2,19 @@
 
 > Guía de personalización para **consumidores** de `@trycore/spec-build-harness`. Explica cómo
 > conectar servidores **MCP** (Model Context Protocol) y **LSP** (Language Server Protocol) para
-> apoyar los gates del arnés. **Todo lo de aquí es opcional.** El core es 100 % agnóstico: ningún
-> gate, skill ni agente **depende** de un MCP concreto. Si tu entorno no expone ningún MCP, el arnés
-> funciona igual cubriendo cada fase con sus alternativas CLI/test.
+> apoyar los gates del arnés. **Casi todo lo de aquí es opcional** y el core es agnóstico: ningún
+> gate **depende de un MCP concreto** (cualquier equivalente sirve). **Única excepción:** el gate
+> `fidelity` en slices con UI **requiere** un MCP de devtools de navegador (verificación visual real),
+> porque la fidelidad no puede acreditarse sin observar la salida real. Para todo lo demás, si tu
+> entorno no expone ningún MCP, el arnés funciona igual cubriendo cada fase con sus alternativas CLI/test.
 
 > **LSP tiene guía dedicada.** Este documento cubre sobre todo **MCP**. Para **LSP** (precisión de
 > símbolo en stacks tipados: por qué, cuándo y cómo), ver **`lsp-extensions.md`**.
 
 ## TL;DR
 
-- Los gates **pueden apoyarse** en MCP/LSP como **aceleradores**, nunca como dependencia dura.
+- Los gates **pueden apoyarse** en MCP/LSP como **aceleradores**, nunca como dependencia dura — con
+  la **única excepción** del gate `fidelity` en slices con UI, que sí exige un MCP de navegador.
 - **Tú** declaras qué MCP habilitas en **tu** `settings` (el arnés no instala ninguno).
 - La skill `building-a-slice` consulta un mapa por gate en
   `skills/building-a-slice/references/mcp-map.md`: ahí está la lista de **ejemplos representativos**.
@@ -32,7 +35,8 @@ disponible:
 | El agente/skill lo usa bajo demanda para obtener evidencia más rica (UI corriendo, BD, carga). | El mismo gate se cierra con la alternativa CLI/test indicada en `mcp-map.md`. |
 
 Por eso ningún `command` de hook, ningún agente y ninguna skill **exigen** un MCP: lo **sugieren**
-cuando aplica. El consumidor decide.
+cuando aplica. El consumidor decide. **Salvedad documentada:** el gate `fidelity` de UI sí requiere un
+MCP de navegador (categoría, no un proveedor concreto) — ver la fila `fidelity` y su nota más abajo.
 
 ## Cómo lo declara el consumidor (en TU settings)
 
@@ -70,6 +74,7 @@ cada uno por el que aplique a **tu** stack declarado en el PRD; ninguno es oblig
 | Fase / gate | Agente | Ejemplo de MCP/LSP (opt-in) | Para qué | Alternativa sin MCP |
 |---|---|---|---|---|
 | `journey_smoke` (inner) / `integration` (release) | skill `verify` / `run` | Navegador headless vía MCP (p. ej. un MCP de devtools de navegador) | Recorrer el journey con la UI **corriendo**: snapshot del árbol accesible, screenshot, consola. | Smoke por test e2e/CLI del propio proyecto. |
+| `fidelity` (inner, **slices con UI**) | `ux-fidelity-reviewer` | **MCP de devtools de navegador REQUERIDO** (p. ej. chrome-devtools): `take_screenshot` + `take_snapshot` | Acreditar fidelidad visual observando la **salida real** (app vs prototipo). | **No hay alternativa para UI**: sin verificación visual real el gate queda `false` (corre el slice donde el MCP esté disponible). El estático solo complementa. |
 | `ux` (release) | `ux-krug-reviewer` | Navegador headless con auditoría tipo Lighthouse | Accesibilidad / Best-Practices y snapshots de la UI ensamblada de la release. | Revisión heurística Krug sobre el código + capturas manuales. |
 | `api` (inner) | `api-contract-tester` | **Newman corre por CLI, no es MCP** | Contratos de endpoints sobre una colección de pruebas. | Es la vía por defecto: se ejecuta vía Bash, sin MCP. |
 | `data` (inner) | `data-consistency-checker` | MCP de base de datos (solo si tu slice usa esa BD) | Consultas de lectura / describe de tablas para validar invariantes y consistencia. | Validación por tests contra un almacén embebido o cliente del stack. |
@@ -83,6 +88,12 @@ Notas de coherencia con el arnés:
   release** en `releasing-a-version`. Habilita los MCP de esas fases pensando en el outer loop.
 - El gate `api` usa **Newman por CLI**: es un ejemplo de que la herramienta de un gate **no tiene por
   qué ser un MCP**. Lo importante es la evidencia (los contratos responden), no el canal.
+- **Excepción única — `fidelity` en slices con UI.** Es el **único** gate donde un MCP es **requerido**,
+  no opt-in: la fidelidad visual no puede acreditarse sin **observar la salida real** (cargar la página,
+  comparar contra el prototipo, leer la consola). Se mantiene la agnosticidad a nivel de **categoría**
+  (cualquier MCP de devtools de navegador sirve; chrome-devtools es el ejemplo), pero **alguno** debe
+  estar disponible: sin él, `fidelity` queda `false` y el `dod` no cierra. La evidencia aquí **es** la
+  observación de la UI corriendo; no hay alternativa CLI que la sustituya.
 
 ## Reglas de uso (no negociables)
 

package/docs/getting-started.md

@@ -1,269 +1,124 @@
-# Getting Started — Tu primer ciclo end-to-end en ~15 min
+# Quickstart — de 0 a tu primer slice
 
-Esta guía te lleva, de forma secuencial y práctica, desde cero hasta cerrar tu primer **slice**
-(una épica `EP-XXX`) con el arnés de construcción de Trycore (`@trycore/spec-build-harness`).
+Guía pragmática para empezar a construir con `@trycore/spec-build-harness` (el compañero de construcción de `@trycore/spec-product-flow`). Instalación detallada y troubleshooting → [`INSTALL.md`](../INSTALL.md). Metodología (fuente de verdad) → [`METODOLOGIA.md`](../METODOLOGIA.md).
 
-El arnés es el **compañero de construcción** de `@trycore/spec-product-flow`: la vertical de
-discovery produce los artefactos (`PRD → User Story Map → Backlog → Historias → Priorización →
-Flows`); este arnés los lleva al **código** mediante un pipeline de **dos loops**.
+## TL;DR
 
-| Loop | Skill | Frecuencia | Qué hace |
-|---|---|---|---|
-| **Inner** (rápido) | `building-a-slice` | por épica `EP-XXX` | DoR → OpenSpec change → TDD → journey-smoke → api/data → DoD reducido → PR + archive |
-| **Outer** (pesado) | `releasing-a-version` | por release (línea del Story Map) | gates de seguridad, diseño, UX, coherencia triple, arquitectura e integración con deps reales — **una sola vez** |
-
-Ambas verticales coexisten en el mismo `.claude/` sin colisión (namespaces disjuntos:
-`trycore/` para discovery vs. `opsx/` + `build/` para construcción).
+```bash
+# 1) Requisitos + CLI — una vez por máquina
+npm i -g @fission-ai/openspec @trycore/spec-build-harness
 
-> **Regla de oro:** `METODOLOGIA.md` es la fuente de verdad. Si una skill la contradice, **gana la
-> metodología**.
+# 2) En la raíz de tu proyecto
+trycore-build init       # siembra el arnés (idempotente)
+trycore-build doctor     # verifica requisitos y hooks
+```
 
----
+```text
+# 3) En Claude Code (lo corre Claude, no la terminal)
+/build:onboard               # parametriza el dominio: lee tu PRD, resuelve los {{placeholders}}
+skill building-a-slice       # construye una épica: DoR → change → TDD → smoke → DoD → PR
+/build:reflect               # (opcional) captura aprendizajes del slice recién archivado
+skill releasing-a-version    # al cerrar una línea de release del Story Map
+```
 
-## Mapa de los 15 minutos
-
-| Min | Paso | Quién lo corre |
-|---|---|---|
-| 0–2 | 1. Instalar el CLI + requisitos duros | terminal |
-| 2–5 | 2. `trycore-build init` en tu proyecto | terminal |
-| 5–6 | 3. `trycore-build doctor` (verificar) | terminal |
-| 6–9 | 4. `/build:onboard` (parametrizar dominio) | Claude Code |
-| 9–14 | 5. Abrir un slice con la skill `building-a-slice` | Claude Code |
-| 14+ | 6. ¿Cuándo correr `releasing-a-version`? | Claude Code |
+Eso es el ciclo completo. Lo de abajo explica cada paso.
 
 ---
 
-## Paso 1 · Instalar el CLI y los requisitos duros (~2 min)
+## Requisitos duros
 
-El CLI `trycore-build` siembra los archivos del arnés. Pero el arnés depende de **tres binarios
-externos** que el CLI **no puede instalar por ti**. `init` y `doctor` **fallan (exit 1)** si falta
-alguno:
+`init` y `doctor` **fallan (exit 1)** si falta alguno:
 
-| Requisito | Para qué | Cómo instalarlo |
+| Requisito | Para qué | Instalación |
 |---|---|---|
-| `openspec` | columna vertebral de `/opsx:*` y las skills `openspec-*` | `npm i -g @fission-ai/openspec` |
-| `python3` | los hooks parsean `build-state.json` con python3 | gestor del sistema (brew, apt, …) |
-| `git` | los hooks y `gitflow-guard` resuelven la raíz y bloquean commits directos | gestor del sistema |
-
-Instala el CLI y OpenSpec:
-
-```bash
-npm install -g @trycore/spec-build-harness   # CLI: bin `trycore-build`
-npm install -g @fission-ai/openspec           # requisito duro
-```
+| `openspec` | base de `/opsx:*` y las skills `openspec-*` | `npm i -g @fission-ai/openspec` |
+| `python3` | los hooks leen `build-state.json` | gestor del sistema (brew/apt) |
+| `git` | ramas, PRs, archivado de changes | gestor del sistema |
 
-> **Canal CLI vs. plugin.** El canal **npm CLI es el canónico** y el recomendado para operar en un
-> proyecto: instala los comandos en `.claude/commands/{opsx,build}/`, namespaceados por subcarpeta
-> (`/opsx:*`, `/build:onboard`), y referencia los agentes por su nombre. El canal **plugin nativo**
-> (`/plugin marketplace add <repo> ; /plugin install trycore-spec-build-harness@trycore-build`) se
-> ofrece como conveniencia a nivel usuario, pero Claude Code namespacea sus componentes bajo el
-> nombre del plugin (`/trycore-spec-build-harness:*`); las cross-references internas (skills que
-> invocan `/opsx:*`, agentes por nombre) están escritas para el canal CLI. **Para construir en un
-> proyecto, usa el CLI.**
+Runtime Node ≥18. **Usa el canal CLI** (npm), no el plugin, para operar dentro de un proyecto (ver el caveat de canales en [`INSTALL.md`](../INSTALL.md)).
 
 ---
 
-## Paso 2 · `trycore-build init` en tu proyecto (~3 min)
-
-Sitúate en la raíz de tu proyecto y ejecuta:
+## 1 · Instalar (terminal)
 
 ```bash
-trycore-build init
+npm i -g @fission-ai/openspec @trycore/spec-build-harness
 ```
 
-`init` es **idempotente** (re-correrlo es seguro) y siembra:
-
-- **10 agentes** en `.claude/agents/build/` (build-orchestrator, dor-dod-gatekeeper,
-  security-reviewer, simple-design-reviewer, ux-krug-reviewer, coherence-three-way, stack-guardian,
-  api-contract-tester, data-consistency-checker, change-epic-coherence).
-- **Comandos** `/opsx:*` (10) en `.claude/commands/opsx/` + `/build:onboard` y `/build:reflect` en `.claude/commands/build/`.
-- **12 skills** en `.claude/skills/` (`building-a-slice`, `releasing-a-version`, 10 `openspec-*`).
-- **8 hooks** bash en `.claude/hooks/build/` + permisos mínimos en `settings.json`.
-- **Estado**: `.claude/state/build-state.json` (sembrado **vacío** y **nunca** sobreescrito; va al
-  `.gitignore`), más el schema y el README versionados.
-- **Config**: `.claude/config/stack-allowlist.json` (artefacto del consumidor; lo siembra el CLI y
-  lo puebla `/build:onboard`).
-- **Bloque marcado en `CLAUDE.md`** entre `<!-- BEGIN trycore-build-harness ... -->` y
-  `<!-- END trycore-build-harness -->`, con `{{placeholders}}` **sin resolver** (los resuelve
-  `/build:onboard`).
-
-### Onboarding en dos capas
-
-El onboarding tiene **dos capas** por una razón técnica: un binario Node **no puede escribir la
-auto-memory de Claude**.
-
-1. **Capa mecánica (este CLI)** — captura el stack: lenguaje/deps, package manager, runtime y ruta
-   del PRD. Por **prompt TTY** interactivo, o **CI-safe** con flags y `--yes`.
-2. **Capa semántica (`/build:onboard`, lo corre Claude)** — lee el PRD, pregunta por PII, capa de
-   servicios externos/IA, capa determinista, secretos y decisiones de alto impacto, resuelve los
-   `{{placeholders}}` y escribe la auto-memory. (Paso 4.)
+## 2 · `trycore-build init` (terminal)
 
-#### Flags de `init` (modo no interactivo / CI)
-
-| Flag | Para qué |
-|---|---|
-| `--yes` | no interactivo: usa defaults para el stack |
-| `--stack <deps>` | dependencias permitidas, coma-separadas |
-| `--pkg-manager <pm>` | package manager (`npm` \| `pnpm` \| `yarn`) |
-| `--runtime <semver>` | semver del runtime (ej. `">=18.18"`) |
-| `--prd-path <path>` | ruta#ancla del PRD técnico (fuente del allowlist) |
-| `--copy` | copiar archivos en vez de symlinkear (Windows sin admin, sandboxes) |
-| `--force-init` | fuerza modo init aunque exista instalación previa |
-| `--skip-doctor` | omite la verificación de requisitos (no recomendado) |
-
-Ejemplo CI-safe:
+Desde la raíz de tu proyecto. Es **idempotente** (re-correrlo es seguro) y siembra: **12 agentes**, **12 skills**, **10 comandos `/opsx:*`** + `/build:onboard` + `/build:reflect`, **9 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 --yes \
-  --stack "express,zod,pg" --pkg-manager pnpm \
-  --runtime ">=18.18" --prd-path "docs/01-prd/prd.md#requisitos-tecnicos"
+trycore-build init
 ```
 
-> Otros comandos del CLI: `trycore-build status` (estado de la instalación y fase del arnés),
-> `trycore-build update` (refresca assets/schema tras actualizar el paquete; **no** pisa estado ni
-> allowlist), `trycore-build uninstall` (quita el arnés **preservando** `state/` y `config/`).
-
----
-
-## Paso 3 · `trycore-build doctor` (~1 min)
-
-Verifica que el entorno esté listo **antes** de construir:
+CI / no interactivo:
 
 ```bash
-trycore-build doctor
+trycore-build init --yes \
+  --stack "express,zod,pg" --pkg-manager pnpm \
+  --prd-path "docs/01-prd/prd.md#requisitos-tecnicos"
 ```
 
-Comprueba:
-
-- Los **3 requisitos duros** (`git`, `python3`, `openspec`) — **falla con exit 1** si falta alguno.
-- Que los **8 hooks** tengan bit ejecutable (si no, sugiere `trycore-build init --copy` o `chmod +x`).
-- **Doble canal**: si detecta hooks del arnés en `settings.json` (canal CLI) y además instalaste el
-  plugin, te recuerda que la cadena de comando es idéntica en ambos canales y Claude Code
-  **deduplica** → el hook dispara **una sola vez**. No requiere acción.
-- **Reflexión y LSP (informativo, no falla):** reporta cuántos slices archivados están **sin
-  reflexionar** (sugiere `/build:reflect`) y, si detecta un stack tipado (`pom.xml`,
-  `build.gradle`, `*.csproj`, `tsconfig.json`…), sugiere activar **LSP**
-  (ver `docs/customization/lsp-extensions.md`).
-
-Si ves `✓ Requisitos satisfechos.`, continúa.
-
----
-
-## Paso 4 · `/build:onboard` en Claude Code (~3 min)
-
-Abre Claude Code en el proyecto y ejecuta:
+Otros: `trycore-build status` · `update` (refresca assets, no toca tu estado) · `uninstall` (preserva `state/` y `config/`). Flags completos en [`INSTALL.md`](../INSTALL.md).
 
-```
-/build:onboard
-```
+## 3 · `/build:onboard` (Claude Code)
 
-Este slash command (lo corre Claude, no el CLI) **parametriza el dominio**: lee tu PRD y/o
-`openspec/project.md` y confirma contigo, vía `AskUserQuestion`, **6 puntos** que luego leen los
-agentes de calidad:
+Abre Claude Code en el proyecto y corre `/build:onboard`. Lee tu PRD y confirma contigo, vía `AskUserQuestion`, **7 puntos de dominio** que luego leen los agentes de calidad; al terminar resuelve los `{{placeholders}}` del `CLAUDE.md` y escribe la auto-memory.
 
 | Placeholder | Qué define |
 |---|---|
 | `PRD_TECH_PATH` | ruta#ancla del PRD técnico (fuente del stack) |
-| `EXTERNAL_SERVICE_LAYER` | capa de servicios externos / IA y su frontera/aislamiento |
+| `EXTERNAL_SERVICE_LAYER` | capa de servicios externos / IA y su frontera |
 | `DETERMINISTIC_LAYER` | lógica que **no** puede delegarse a un servicio no determinista |
-| `SENSITIVE_DATA_CATEGORIES` | categorías reguladas de datos / PII del dominio |
-| `SERVER_SIDE_SECRETS` | claves/tokens que **jamás** van al cliente |
-| `HIGH_STAKES_DECISIONS` | decisiones que exigen explicabilidad/justificación en la UI |
-
-Al terminar, `/build:onboard` resuelve los `{{placeholders}}` del bloque marcado en `CLAUDE.md`,
-opcionalmente puebla el `stack-allowlist.json`, y escribe la auto-memory (memorias tipo `project`).
-Si un punto no aplica, se registra explícitamente como "no aplica" (no se deja como `{{...}}`).
+| `SENSITIVE_DATA_CATEGORIES` | datos / PII regulados del dominio |
+| `SERVER_SIDE_SECRETS` | secretos que **jamás** van al cliente |
+| `HIGH_STAKES_DECISIONS` | decisiones que exigen explicabilidad en la UI |
+| `DESIGN_SOURCE` | fuente de diseño / referencia visual (prototipo/export), o `N/A` si no hay UI |
 
----
+Si un punto no aplica, se registra como "no aplica" (no se deja como `{{...}}`).
 
-## Paso 5 · Abrir un slice con `building-a-slice` (~5 min)
+## 4 · Construir un slice (Claude Code)
 
-Esta es la unidad de trabajo del **inner loop**: **un slice = una épica = un OpenSpec change = una
-rama = un PR**. Las HU de la épica (las que tienen `epica: EP-XXX` en `docs/04-historias/`) son el
-**alcance interno** del change.
-
-En Claude Code, invoca la skill (o pídelo en lenguaje natural: *"construye la épica EP-001"*):
+**Un slice = una épica `EP-XXX` = un OpenSpec change = una rama = un PR.** Las HU de la épica son su alcance interno. Invoca `skill building-a-slice` (o pídelo en lenguaje natural: *"construye EP-001"*). Pipeline del **inner loop**:
 
 ```
-skill building-a-slice
+DoR → change (+ trazabilidad) → TDD → journey-smoke (+ fidelidad si hay UI) → api/data → DoD reducido → PR + archive
 ```
 
-La skill conduce el pipeline (delega en el `build-orchestrator`). Las fases del inner loop:
-
-| Fase | Acción | Delega en | Gate |
-|---|---|---|---|
-| 1 · dor | Validar Definition of Ready | `dor-dod-gatekeeper` | `dor` |
-| 2 · change | `/opsx:new` + bloque `## Trazabilidad` que enlaza el change a la épica | `/opsx:new`, `change-epic-coherence` | `coherence_link` |
-| 3 · tdd | red → green → refactor | `superpowers:test-driven-development` | `tdd` |
-| 4 · smoke | recorrer el journey-hasta-aquí end-to-end | skill `verify`/`run` (+ MCP) | `journey_smoke` |
-| 5 · api/data | contratos + consistencia (si aplican) | `api-contract-tester`, `data-consistency-checker` | `api`, `data` |
-| 6 · dod | Definition of Done reducido por slice | `dor-dod-gatekeeper` | `dod` |
-| 7 · pr | abrir PR + archivar el change en el mismo PR | `/opsx:archive`, `/opsx:sync` | — |
-| 8 · release? | preguntar si correr el Release Gate ahora | usuario (default computado) | — |
-
-Notas clave del inner loop:
-
-- **Esqueleto que camina.** El **primer** slice de una release construye el journey completo más
-  delgado posible (aunque cada paso sea un stub). Cada épica posterior **engorda** un paso y mantiene
-  el `journey_smoke` verde. Nunca se construyen capas horizontales aisladas que "se juntan al final".
-- **Estado = una sola fuente de verdad.** Todo se sincroniza en `.claude/state/build-state.json`
-  (schema y protocolo en `.claude/state/README.md`). Lee antes de actuar; escribe una vez por
-  transición. Un slice activo a la vez; un gate no se salta.
-- **Gates pesados NO se cierran aquí.** `stack`, `security`, `smell`, `ux` y la coherencia triple
-  completa pertenecen al Release Gate. Lo que sí corre en tiempo real son los **hooks**:
-  `stack-guard.sh` (vigila deps fuera del allowlist), `lint-typecheck.sh`, `gitflow-guard.sh`
-  (bloquea commits/push directos a `main` — integras solo por **PR**).
-- **El enlace change↔épica** va en el bloque `## Trazabilidad` del `proposal.md`, **nunca** en
-  frontmatter YAML (rompe `openspec validate`).
-- **Reflexión (ciclo autocorrectivo).** Tras archivar el slice, `/build:reflect` puede capturar las
-  convenciones aprendidas / errores recurrentes en el bloque `trycore-build-learnings` de
-  `CLAUDE.md` (con tu aprobación). Lo **sugiere** el hook `reflect-nudge.sh` al cerrar la sesión;
-  es opcional y no bloquea.
-- Objetivo: **≤ ~20 min por épica**, y producto que **camina end-to-end en todo momento**.
-
----
+Lo que importa:
 
-## Paso 6 · ¿Cuándo correr `releasing-a-version`? (outer loop)
+- **Esqueleto que camina.** El **primer** slice arma el journey completo más delgado posible; cada épica posterior engorda un paso y mantiene el `journey_smoke` verde. Nunca capas horizontales que "se juntan al final".
+- **Precondiciones duras (el arnés las exige, no las genera):** un *scaffold runnable* confirmado y —si el slice tiene UI— una *fuente de diseño declarada* (`design_source`). Los hooks `scaffold-guard` y `design-source-guard` las respaldan.
+- **Los gates pesados NO se cierran aquí** (seguridad, diseño, UX/Krug, coherencia triple, arquitectura): van al Release Gate. En el inner loop solo corre lo barato + los hooks en tiempo real (`gitflow-guard` bloquea commits/push directos a `main` → integras solo por **PR**; `stack-guard`, `lint-typecheck`).
+- **El enlace change↔épica** va en el bloque `## Trazabilidad` del `proposal.md`, nunca en frontmatter YAML.
+- **Una sola fuente de verdad:** `.claude/state/build-state.json`. Un slice activo a la vez; un gate no se salta. Objetivo: **≤ ~20 min por épica**.
 
-Tras archivar la épica (fase 8), la skill te **pregunta** si correr el Release Gate, con un
-**default computado** desde las líneas de release del Story Map (`docs/02-user-story-map/`):
+> ¿Mantenimiento que no es producto nuevo (typo, bump de dep ya permitida, copy/config)? Usa `skill building-a-micro-change` (carril ligero `fix/*`/`chore/*`), no una épica.
 
-- Si la épica **cierra una línea de release** (todas sus épicas ya están archivadas) → default
-  **"Sí, correr `releasing-a-version`"**.
-- Si no la cierra → default **"Continuar a la siguiente épica"**. Excepción (*nudge*): si hay
-  **≥ 2 épicas** archivadas desde el último Release Gate, lo recomienda igual.
+## 5 · Release Gate (Claude Code, por release)
 
-El humano siempre decide. El Release Gate corre las **revisiones pesadas una sola vez**, sobre el
-**diff acumulado** de toda la release:
+Al archivar una épica, la skill te **pregunta** si correr el Release Gate (default computado desde las líneas de release del Story Map). `skill releasing-a-version` corre las **revisiones pesadas una sola vez** sobre el diff acumulado:
 
 | Gate | Delega en |
 |---|---|
 | `security` | `security-reviewer` |
-| `smell` (4 reglas de Beck + code smells) | `simple-design-reviewer` |
+| `smell` (Beck + code smells) | `simple-design-reviewer` |
 | `ux` (Krug + lighthouse; `null` si sin UI) | `ux-krug-reviewer` |
 | `coherence` (trazabilidad triple AC↔change↔código) | `coherence-three-way` |
 | `stack_arch` (arquitectura del PRD) | `stack-guardian` |
-| `integration` (journey completo con **deps reales**, no stubs) | skill `verify`/`run` |
+| `integration` (journey completo con **deps reales**) | skill `verify`/`run` |
 
-Los resultados se registran en `build-state.json → releases[]`. **La integración con deps reales es
-obligatoria** para `status: passed`: es el gate que garantiza que el producto realmente funciona al
-terminar. Si algo falla, lo corriges como un slice normal en `building-a-slice` y re-corres el gate.
+`integration` con deps reales es obligatoria para `status: passed`. Se registra en `build-state.json → releases[]`. Si algo falla, lo corriges como un slice normal y re-corres el gate.
 
 ---
 
-## Resumen del primer ciclo
+## Siguiente
 
-```
-npm i -g @trycore/spec-build-harness @fission-ai/openspec   # paso 1
-trycore-build init                                          # paso 2
-trycore-build doctor                                        # paso 3
-# en Claude Code:
-/build:onboard                                              # paso 4
-skill building-a-slice   # EP-XXX: DoR → /opsx:new → TDD → smoke → DoD → PR   # paso 5
-/build:reflect           # opcional: captura aprendizajes del slice recién archivado
-# y cuando cierres una línea de release del Story Map:
-skill releasing-a-version                                   # paso 6
-```
+- **Instalación detallada / flags / plugin / troubleshooting** → [`INSTALL.md`](../INSTALL.md)
+- **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/)
 
-> El core del arnés es **100% agnóstico** al proyecto. El ejemplo de referencia completo vive
-> aparte, en `docs/examples/reference/` (no forma parte del core).
+> El core es **100% agnóstico** al proyecto. El ejemplo de referencia completo vive aparte en `docs/examples/reference/` (no forma parte del core).