@trycore/spec-build-harness 0.5.0 → 0.6.0

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:
-
-- **11 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, ux-fidelity-reviewer).
-- **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-*`).
-- **9 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 **9 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).

package/hooks/build/load-build-state.sh

@@ -39,8 +39,24 @@ if not s:
 else:
     g=s.get("gates",{})
     abiertos=[k for k,v in g.items() if v is False]
-    print(f"   Slice activo: {s.get('hu')} ({s.get('epica')}) · change={s.get('openspec_change')} · fase={s.get('phase')}")
+    hus=", ".join(s.get("hus") or []) or "—"
+    print(f"   Slice activo: {s.get('epica')} [{hus}] · change={s.get('openspec_change')} · fase={s.get('phase')}")
     print(f"   Gates pendientes: {', '.join(abiertos) if abiertos else 'ninguno ✅'}")
+    # Handoff fino en disco (A1): items de cableado aún FAILING + última bitácora.
+    # Una sesión fresca arranca de aquí; mientras queden failing, el cableado NO está hecho.
+    failing=[w for w in (s.get("wiring_checklist") or []) if w.get("status")=="failing"]
+    if failing:
+        muestra="; ".join(f"{w.get('id')}({w.get('kind')})" for w in failing[:8])
+        extra=f" (+{len(failing)-8} más)" if len(failing)>8 else ""
+        print(f"   ⚠️  Cableado pendiente ({len(failing)} item/s failing): {muestra}{extra}")
+        print("       NO declares el slice terminado mientras queden items failing (verifica con prueba real).")
+    pend=[ss for ss in (s.get("sub_slices") or []) if ss.get("status")!="done"]
+    if pend:
+        print(f"   ⚠️  Sub-slices pendientes: {', '.join(ss.get('id') for ss in pend)}")
+    log=s.get("progress_log") or []
+    if log:
+        last=log[-1]
+        print(f"   Última bitácora: [{last.get('by')}] {last.get('note')}")
 PY
 fi
 exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trycore/spec-build-harness",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Arnés agéntico de construcción de Trycore para Claude Code: pipeline de dos loops (slice por épica + release gate) con gates de calidad, estado compartido y OpenSpec. Compañero de @trycore/spec-product-flow. Agnóstico al proyecto.",
   "type": "module",
   "bin": {

package/skills/building-a-slice/SKILL.md

@@ -25,7 +25,14 @@ el avance en el estado.
   `.claude/state/README.md`). Lee antes de actuar; escribe una vez por transición.
 - **Secuencial**: un slice activo a la vez. Un gate no se salta.
 - **Divulgación progresiva**: carga el `references/<tema>.md` solo cuando la fase lo necesita.
-- **Delega en subagentes** para revisión pesada (devuelven síntesis, protegen el contexto).
+- **Delega en subagentes** para revisión pesada y para **explorar** (devuelven síntesis condensada,
+  protegen el presupuesto de atención de la sesión principal para **cablear**, no para descubrir).
+- **Refresh de contexto = estado por defecto**: cada iteración nace **headless / contexto virgen** y
+  reconstruye el estado **desde disco** (git + `build-state.json` + logs), no desde la conversación
+  viva. Mantén el **`wiring_checklist[]`** (un item por escenario AC y por punto de integración entre
+  capas): nace `failing`, pasa a `passing` **solo tras prueba real ejecutada**. Deja una nota en
+  `progress_log[]` por hito. **Mientras quede un item `failing`, el slice NO está terminado.** Ver
+  `references/state-protocol.md`.
 
 ## Dos loops
 
@@ -39,6 +46,21 @@ inner loop: **≤ ~20 min por épica** y producto que **camina end-to-end en tod
 > cada paso sea un stub. Cada épica posterior **engorda** un paso de ese esqueleto y mantiene el
 > `journey_smoke` verde. Nunca se construyen capas horizontales aisladas que "se juntan al final".
 
+> **Cimiento antes que negocio (épicas fundacionales).** Las épicas marcadas `layer: foundational`
+> (autenticación, acceso a datos, arquitectura base, design-system/componentes base) se construyen
+> **antes** que las `layer: business`. El DoR **rechaza** abrir una épica de negocio que arrastra
+> cimiento no construido y lo extrae a una épica fundacional previa (ver `dor.md`). Así cada slice de
+> negocio **solo toca lógica aplicable** y no quema contexto creando infra.
+
+> **Descomposición por tamaño (no one-shot).** Una épica que supera el **gate de tamaño**
+> (heurística por defecto: **> 3 HU** ó **≥ 3 capas tocadas**; configurable por proyecto) es
+> demasiado grande para una pasada: el DoR obliga a trocearla en **sub-slices verificables**
+> (`sub_slices[]`) construidos **de a uno**, con `journey_smoke` verde entre cada uno antes de pasar
+> al siguiente. El orquestador trabaja por **fases encadenadas** (mapear → generar → revisar →
+> fix-loop → optimizar) y reparte la exploración **"ancho antes que profundo"** con subagentes
+> **solo-lectura por área** (frontend/backend/datos); el **cableado** lo hace la sesión, no
+> subagentes que escriben en paralelo. Trocear acota además el tamaño del `wiring_checklist[]`.
+
 ## Fase 0 · Scaffold (Paso 1 fundamental — precondición restrictiva)
 
 Antes de abrir **cualquier** slice, el scaffold runnable del proyecto debe **existir y estar
@@ -78,9 +100,9 @@ Espejo de la Fase 0, para proyectos **con UI**. Antes de abrir el primer slice c
 | 1 · dor | Validar Definition of Ready | `dor-dod-gatekeeper` | `dor` | `dor.md` |
 | 2 · change | `opsx:new` + bloque `## Trazabilidad`; validar enlace (barato) | `opsx:new`, `change-epic-coherence` | `coherence_link` | `link-change-epic.md` |
 | 3 · tdd | red → green → refactor | `superpowers:test-driven-development` | `tdd` | — |
-| 4 · smoke | Recorrer el journey-hasta-aquí end-to-end; **slices con UI:** verificar fidelidad a la fuente de diseño | skill `verify` / `run` (+ MCP chrome-devtools), `ux-fidelity-reviewer` | `journey_smoke`,`fidelity` | `mcp-map.md` |
+| 4 · smoke | Recorrer el journey-hasta-aquí end-to-end con el **runner determinista fuera-de-chat** (`integration-check`: suite+build+reporte) en **sesión/contexto virgen**; **slices con UI:** fidelidad por **verificación visual REAL** (MCP chrome-devtools, screenshot app vs prototipo) | runner `integration-check`, skill `verify`/`run` + MCP chrome-devtools, `ux-fidelity-reviewer` | `journey_smoke`,`fidelity` | `integration-check.md`, `mcp-map.md` |
 | 5 · api/data | contratos + consistencia (si aplican al slice) | `api-contract-tester`, `data-consistency-checker` | `api`,`data` | `newman-tests.md`, `data-consistency.md` |
-| 6 · dod | Definition of Done (por slice, reducido) | `dor-dod-gatekeeper` | `dod` | `dod.md` |
+| 6 · dod | **Primero** verificación adversarial INDEPENDIENTE del cableado (contexto virgen: refuta stubs/rutas sin cablear/AC sin test/items `failing`) → `wiring_verified`; **solo entonces** Definition of Done | `wiring-adversarial-verifier`, `dor-dod-gatekeeper` | `wiring_verified`,`dod` | `dod.md`, `integration-check.md` |
 | 7 · pr | Abrir PR + archivar change en el mismo PR | `opsx:archive`, `opsx:sync` | — | `gitflow.md` |
 | 8 · release? | Preguntar si correr el Release Gate ahora | usuario (default computado) | — | abajo |
 
@@ -88,9 +110,15 @@ Los gates `stack`, `security`, `smell`, `ux` y la coherencia triple completa **y
 aquí**: pertenecen al Release Gate. Las **deps** siguen vigiladas en tiempo real por el hook
 `stack-guard.sh`; lint/tsc/gitflow por sus hooks.
 
-El gate `fidelity` (fidelidad a la fuente de diseño) **sí** es de inner loop: es barato (se computa
-en `smoke`, con la app ya levantada) y vivo por-slice; complementa al `ux-krug-reviewer` (usabilidad),
-que sigue en el Release Gate.
+El gate `fidelity` (fidelidad a la fuente de diseño) **sí** es de inner loop: se computa en `smoke`,
+con la app ya levantada, y es vivo por-slice; complementa al `ux-krug-reviewer` (usabilidad), que
+sigue en el Release Gate. **Estricto para UI:** una UI no mejora su fidelidad por el prompt sino
+porque el agente **carga la página, observa la salida real y lee la consola**. Para slices con UI
+(`design_source.applies===true`), `fidelity` **solo cierra con verificación visual real vía MCP
+chrome-devtools** (screenshot app vs prototipo). Sin MCP, `fidelity` queda `false` (INCONCLUSO ya
+**no** pasa) → el `dod` no cierra: corre el slice donde haya MCP. Mantén **cobertura** (ninguna
+pantalla del prototipo en alcance sin construir; ninguna pantalla de la app sin HU/EP) y el
+**journey-smoke de clic real como tenant no-admin**.
 
 MCP/LSP por gate: ver `references/mcp-map.md`. Protocolo de estado: `references/state-protocol.md`.
 
@@ -126,4 +154,11 @@ El usuario siempre puede sobreescribir el default. Si acepta, invoca la skill
 - El enlace change↔épica va en `## Trazabilidad` del `proposal.md`, **nunca** en frontmatter YAML
   (rompe `openspec validate`). Ver `link-change-epic.md`.
 - Integración solo por **PR** a `main` (el hook `gitflow-guard.sh` bloquea commits/push directos).
+- **`dod` exige `wiring_verified: true`** (verificación adversarial independiente, contexto virgen).
+  El DoD declarativo del gatekeeper es un **piso, no el arreglo**: reusar el mismo agente como
+  generador y verificador produce auto-confirmación. La generación y la verificación van separadas.
+- **Producto completo, no MVP.** El alcance acordado se construye entero. **Recortar o diferir es
+  bloqueante explícito** que requiere acuerdo del equipo — nunca una decisión del modelo. No derives
+  en lo complejo. La verificación es **ejecutada, no por inspección** (ver `METODOLOGIA.md` y el
+  bloque del arnés en `CLAUDE.md`).
 - Si una regla aquí contradice la metodología Trycore (`METODOLOGIA.md`), **gana la metodología**.

package/skills/building-a-slice/references/dod.md

@@ -12,9 +12,19 @@ pesadas (seguridad, diseño, UX, coherencia triple, arquitectura, integración)
 - [ ] **`data`** — `data-consistency-checker` valida invariantes de datos (salida de servicios externos validada contra esquema antes de alimentar la capa de decisión determinista del dominio) (si el slice toca datos).
 - [ ] **`api`** — `api-contract-tester` (Newman) 100% verde (o `null` si el slice no tiene endpoints).
 - [ ] **`fidelity` (slices con UI)** — `ux-fidelity-reviewer` devuelve **FIEL** (o DESVIACIONES todas
-  justificadas/documentadas) → `gates.fidelity: true`; `null` si el slice no tiene UI. INCONCLUSO
-  (MCP no disponible) se registra, **no bloquea**. Es gate **vivo** de inner loop (no la revisión Krug,
-  que sigue en el Release Gate).
+  justificadas/documentadas) → `gates.fidelity: true`; `null` si el slice no tiene UI. **ESTRICTO para
+  UI** (`design_source.applies===true`): solo `true` con **verificación visual real** vía MCP
+  chrome-devtools (screenshot app vs prototipo). **INCONCLUSO ya NO pasa**: sin MCP queda `false` y el
+  `dod` no cierra (corre el slice donde haya MCP). Mantén **cobertura** (ninguna pantalla del prototipo
+  en alcance sin construir; ninguna pantalla de la app sin HU/EP). Es gate **vivo** de inner loop (no la
+  revisión Krug, que sigue en el Release Gate).
+- [ ] **Sub-slices completos** — si la épica se descompuso (`sub_slices[]` no vacío), **todos** en
+  `status: done` con su `journey_smoke` verde. No se cierra `dod` con sub-slices pendientes.
+- [ ] **`wiring_verified`** — el `wiring-adversarial-verifier` (subagente **independiente**, contexto
+  virgen) intentó **refutar** el slice (stubs, rutas sin cablear, AC sin test, items de
+  `wiring_checklist[]` aún `failing`) y no halló huecos → `gates.wiring_verified: true`. **Prerequisito
+  duro de `dod`**: el DoD declarativo de este checklist es un **piso, no el arreglo** (la auto-confirmación
+  surge de reusar el mismo agente como generador y verificador).
 - [ ] **OpenSpec**: todas las tasks `[x]`; el archive del change va **en el mismo PR** (no PR aparte).
 - [ ] **Docs/trazabilidad**: back-ref del change añadida en la épica y en cada HU de `hus[]`.
 - [ ] **Hooks verdes (automáticos, no son gates de agente)**: `lint-typecheck.sh` (lint + chequeo de tipos del stack declarado), `stack-guard.sh` (deps en allowlist según la sección de requisitos técnicos del PRD del consumidor, ruta declarada en `stack-allowlist.json#source`), `gitflow-guard.sh` (rama `feature/*`, sin commits directos a `main`).

package/skills/building-a-slice/references/dor.md

@@ -7,8 +7,10 @@ la épica; lo de abajo aplica a la épica y a **cada HU** que cubre (`hus[]`). L
 - [ ] **HU enumeradas**: la épica tiene ≥1 HU; todas las que entran se listan en `hus[]`.
 - [ ] **Frontmatter completo** en cada `docs/04-historias/HU-XXX.md`: `id, titulo, epica, prioridad, complejidad, estado` y `estado: lista`.
 - [ ] **AC en Given/When/Then** por HU, **proporcional a `complejidad`** (cubre los modos de fallo que *realmente existen*, no una cuota fija): `trivial`/baja → **1–2** (happy + el error/edge crítico si existe); `media` → **3** (happy + error + edge); `alta` → **3–5** (cobertura completa). Regla dura Trycore: si existe una rama de error/edge, **debe** tener su escenario (lo que se elimina es fabricar 3–5 para una HU trivial).
-- [ ] **INVEST** por HU: pasa los 6 criterios (Independent, Negotiable, Valuable, Estimable, Small, Testable). Ante duda, invocar `invest-validator`.
-- [ ] **Dependencias resueltas**: las épicas/HU de las que depende están archivadas (`history[]`) o explícitamente no bloquean.
+- [ ] **INVEST** por HU: pasa los 6 criterios (Independent, Negotiable, Valuable, Estimable, Small, Testable).
+- [ ] **Dependencias resueltas**: las épicas/HU de las que depende están archivadas (`history[]`) o explícitamente no bloquean. **Excepción dura — cimiento:** si la dependencia es **infraestructura fundacional** (autenticación, acceso a datos, arquitectura base, design-system/componentes base), la cláusula "explícitamente no bloquean" **NO aplica**: debe estar **construida y archivada** antes (ver criterio "Cimiento construido").
+- [ ] **Cimiento construido (épicas de negocio)**: si esta épica es `layer: business`, todo el cimiento que arrastra (auth, acceso a datos, arquitectura base, design-system/componentes base) ya existe como épica(s) `layer: foundational` **archivada(s)** en `history[]`. Si arrastra cimiento no construido → **STOP**: extráelo a una épica fundacional previa y constrúyela primero. Las épicas fundacionales se priorizan **antes** que las de negocio.
+- [ ] **Tamaño acotado (gate de descomposición)**: si la épica supera el umbral —heurística por defecto **> 3 HU** ó **≥ 3 capas tocadas** (configurable por proyecto)— **no entra como slice único**: se descompone en `sub_slices[]` verificables construidos de a uno, con `journey_smoke` verde entre cada uno. El umbral es proporcional (no cuota rígida): una épica de 1 capa y pocas HU entra directa.
 - [ ] **Cabe en el stack** del PRD §7 (no requiere tecnología fuera de `stack-allowlist.json`).
 - [ ] **Datos de prueba disponibles** o identificables (p.ej. los datos de ejemplo / fixtures sintéticos del dominio del consumidor).
 - [ ] **Fuente de diseño identificada (slices con UI)**: la fuente visual de verdad del slice
@@ -16,5 +18,6 @@ la épica; lo de abajo aplica a la épica y a **cada HU** que cubre (`hus[]`). L
   slice apunta a la(s) pantalla(s) equivalente(s). No se construye UI fuera de la fuente declarada.
 
 **Si todo ✓** → `dor-dod-gatekeeper` abre `active_slice` en `build-state.json` con `epica`, `hus[]`,
-`phase: dor`, `gates.dor: true` y el resto en `false` (`fidelity`/`api` en `null` si la épica no toca UI/endpoints).
+`phase: dor`, `gates.dor: true` y el resto en `false` —incluido **`wiring_verified: false`**—
+(`fidelity`/`api` en `null` si la épica no toca UI/endpoints; `fidelity` arranca en `false` si toca UI).
 **Si algo ✗** → no se abre el slice; se reporta qué falta y se vuelve a discovery (Trycore).

package/skills/building-a-slice/references/integration-check.md

@@ -0,0 +1,27 @@
+# Runner de integración fuera-de-chat (`integration-check`)
+
+Gate determinista que cierra `journey_smoke` **ejecutando**, no por inspección. Lleva el patrón del
+gate fuera-de-chat (como `tools/loop/gateway-check.sh` de un consumidor) al **inner-loop manual**, no
+solo al autónomo. **No crea ningún gate nuevo**: alimenta el `journey_smoke` existente del slice. El
+gate `integration` con dependencias reales sigue siendo del **Release Gate** (outer loop).
+
+## Por qué fuera de chat y en contexto virgen
+- El cableado end-to-end **se ejecuta** (build + suite + journey), no se "razona". Un script lo hace
+  reproducible y barato en contexto.
+- Quien escribió el código **no es buen juez** de su propio cableado: corre el runner en una
+  **sesión/contexto virgen** (o como paso de CI) y entra al **fix-loop** (corre → lee el reporte →
+  arregla → repite) hasta verde.
+
+## Cómo adoptarlo
+1. Copia `templates/integration-check.sh.template` a tu repo (p.ej. `tools/loop/integration-check.sh`)
+   y hazlo ejecutable (`chmod +x`).
+2. **Adapta** los comandos marcados `# ADAPTA` a tu stack (build, suite, e2e). El arnés es agnóstico:
+   el template trae defaults de Node como punto de partida.
+3. Córrelo en la fase `smoke`. Salida **0 = verde** (puedes marcar `journey_smoke: true`), **≠0 = rojo**.
+   El reporte queda en `.claude/state/integration-report.txt`.
+4. Mientras la suite no esté verde y el journey no camine end-to-end, `journey_smoke` queda `false`.
+
+## Relación con el cableado fino
+Cada paso verde del runner es la **evidence** que permite pasar items de `wiring_checklist[]` de
+`failing` a `passing` (ver `state-protocol.md`). El `wiring-adversarial-verifier` (fase `dod`) revisará
+después que esa evidencia sea real.

package/skills/building-a-slice/references/mcp-map.md

@@ -15,7 +15,7 @@ los expone, el gate se cubre con las alternativas CLI/test indicadas.
 | Fase / agente | MCP (ejemplo, si habilitado) | Para qué |
 |---|---|---|
 | `review` · `ux-krug-reviewer` | **chrome-devtools** | `take_snapshot` (árbol accesible), `lighthouse_audit` (Accessibility/Best-Practices), `take_screenshot`, `list_console_messages` para verificar la UI **corriendo**. |
-| `smoke` · `ux-fidelity-reviewer` | **chrome-devtools** *(ejemplo opt-in)* | `new_page`/`navigate_page`, `take_screenshot`, `take_snapshot` para comparar **composición/paleta/tipografía** del diseño vs la app corriendo. Requiere la app levantada; úsalo en fase `active`. Si no hay MCP, el agente degrada a comparación estática (INCONCLUSO). |
+| `smoke` · `ux-fidelity-reviewer` | **chrome-devtools** *(REQUERIDO para slices con UI)* | `new_page`/`navigate_page`, `take_screenshot`, `take_snapshot` para comparar **composición/paleta/tipografía** del diseño vs la app corriendo. Requiere la app levantada; úsalo en fase `active`. **Excepción a la regla opt-in**: para UI la verificación visual real es obligatoria; sin MCP, `fidelity` queda `false` (INCONCLUSO bloquea) y el `dod` no cierra. Cualquier MCP de devtools de navegador sirve (chrome-devtools es el ejemplo). |
 | `api` · `api-contract-tester` | — (Newman CLI) | Contratos de endpoints. Newman no es MCP; corre vía Bash. |
 | `data` · `data-consistency-checker` | **postgresql** *(solo si el slice usa Postgres)* | `read_query`/`describe_table` para validar consistencia en BD. Con un almacén embebido/cliente (según el stack declarado en el PRD del consumidor) se valida por tests, sin MCP. |
 | perf (opcional, fuera del DoD) | **k6** | `execute_k6_test` para carga/latencia si una HU de la épica lo exige. |