@trycore/spec-build-harness 0.1.0

package/docs/agents.md

@@ -0,0 +1,133 @@
+# Agentes de construcción (`agents/build/`)
+
+Los **10 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
+> **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**
+> (skill `releasing-a-version`).
+
+## Tabla resumen
+
+| # | Agente | Modelo | Grupo | Gate / propósito |
+|---|---|---|---|---|
+| 1 | `build-orchestrator` | sonnet | Orquestación | Dirige el pipeline secuencial del slice; mantiene el estado y delega |
+| 2 | `dor-dod-gatekeeper` | sonnet | Gatekeeping | Valida DoR (entrada) y DoD reducido (salida, gate `dod`) |
+| 3 | `security-reviewer` | sonnet | Revisores de release | Gate `security` — seguridad enfocada al dominio |
+| 4 | `simple-design-reviewer` | sonnet | Revisores de release | Gate `smell` — 4 reglas de Beck + code smells |
+| 5 | `ux-krug-reviewer` | sonnet | Revisores de release | Gate `ux` — usabilidad (Steve Krug) |
+| 6 | `coherence-three-way` | **opus** | Revisores de release | Gate `coherence` — coherencia triple AC↔change↔código |
+| 7 | `stack-guardian` | sonnet | Revisores de release | Gate `stack` — stack y arquitectura vs. allowlist |
+| 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 |
+
+---
+
+## Orquestación
+
+### `build-orchestrator` · modelo `sonnet`
+Es el **orquestador de construcción**. No escribe código de producto: dirige el pipeline
+secuencial del *inner loop* por épica (`dor → change → tdd → smoke → api/data → dod → pr →
+release?`), mantiene `.claude/state/build-state.json` (un solo slice activo a la vez) y
+delega en los demás agentes, en los skills `opsx:*` (motor de changes) y en
+`superpowers:test-driven-development` (motor TDD). No salta gates, hace una escritura por
+transición y, tras archivar, calcula el default del Release Gate para pasarlo a la skill
+`building-a-slice`.
+
+## Gatekeeping
+
+### `dor-dod-gatekeeper` · modelo `sonnet`
+**Gatekeeper DoR/DoD**, read-only sobre código. A la entrada valida la **Definition of
+Ready** de la épica (existe en `epicas.md` con trazabilidad al PRD; tiene ≥1 HU; cada HU con
+frontmatter completo y `estado: lista`; AC en Given/When/Then con happy/error/edge; INVEST;
+dependencias declaradas; alcance dentro de la allowlist) y abre el `active_slice` si pasa. A
+la salida valida la **Definition of Done reducida por slice** (gate `dod`): `tdd`,
+`journey_smoke`, `coherence_link`, `data`, `api`, documentación con back-refs y hooks verdes.
+**No valida aquí** `security`, `smell`, `ux`, `coherence` ni `stack`: esos son del Release Gate.
+
+## Revisores de release
+
+> Estos 5 corren una vez por release (skill `releasing-a-version`). Los **5 de valor de
+> dominio** marcados abajo leen los activos concretos (qué es PII regulada, qué servicios
+> externos/IA hay, qué es la capa determinista, qué decisiones son de alto impacto) del
+> **bloque de dominio del `CLAUDE.md` del consumidor** o de su PRD.
+
+### `security-reviewer` · modelo `sonnet` · lee el dominio
+**Revisor de seguridad** (gate `security`). Aplica vectores generales (inyección, XSS,
+deserialización, AuthN/AuthZ, secretos hardcodeados, deps vulnerables, SSRF/path traversal) y
+los **especializa al dominio declarado por el consumidor**: secretos de servicios externos
+solo server-side, datos sensibles/PII regulados no persistidos crudos, validación de archivos
+y entrada, salida de servicios externos/IA tratada como input no confiable, logs sin PII y
+decisiones auditables sin sobre-exposición. Veredicto por severidad
+(CRÍTICO/ALTO/MEDIO/BAJO); sin CRÍTICO/ALTO → `gates.security: true`.
+
+### `simple-design-reviewer` · modelo `sonnet`
+**Revisor de diseño simple y code smells** (gate `smell`), sobre código ya en verde. Aplica
+las 4 reglas de Kent Beck (pasa los tests → revela la intención → sin duplicación → mínimos
+elementos) y caza un catálogo de smells (funciones largas, clases "Dios", números mágicos,
+duplicación de validación, props drilling, código muerto, `any`, acoplamiento a servicios
+externos). Hallazgos BLOQUEANTE/RECOMENDADO/NIT; sin bloqueantes → `gates.smell: true`.
+
+### `ux-krug-reviewer` · modelo `sonnet` · lee el dominio
+**Revisor de usabilidad** según Steve Krug (gate `ux`); aplica solo a slices con UI (sin UI →
+`gates.ux: null`). Verifica "don't make me think", jerarquía visual, convenciones,
+escaneabilidad, affordances, tolerancia al error (claridad de las decisiones de alto impacto y
+su justificación según el dominio) y accesibilidad básica. Revisión estática y, si la app
+corre, dinámica vía MCP `chrome-devtools` (`take_snapshot`, `lighthouse_audit`). Sin
+bloqueantes → `gates.ux: true`.
+
+### `coherence-three-way` · modelo `opus` · lee el dominio
+**Auditor de coherencia triple** (gate `coherence`). Usa el modelo más capaz porque razona a
+la vez sobre tres documentos: los **AC (G/W/T)** de las HU de la épica ↔ el **OpenSpec change**
+(`specs/` + `tasks.md`) ↔ el **código y tests** implementados. Hace comprobaciones top-down
+(cada requisito tiene implementación) y bottom-up (nada huérfano: ni tests sin propósito ni
+código fuera del alcance de `hus[]`). Produce una matriz de trazabilidad; COHERENTE →
+`gates.coherence: true`. Complementa a `change-epic-coherence` verificando la implementación real.
+
+### `stack-guardian` · modelo `sonnet` · lee el dominio
+**Guardián del stack** (gate `stack`, arquitectura). Defiende la sección de requisitos
+técnicos del PRD del consumidor (ruta en `stack-allowlist.json#source`), operacionalizada en
+`.claude/config/stack-allowlist.json`. Verifica que las **dependencias** matcheen la
+allowlist y que la **arquitectura** respete el stack declarado (frontend/runtime del
+consumidor; servicio externo/IA usado solo en su frontera server-side; capa de decisión del
+dominio determinista sin servicio no determinista cuando el PRD lo exige; persistencia sin PII
+regulada cruda) y señala anti-patrones. STACK-OK → `gates.stack: true`. El hook
+`stack-guard.sh` bloquea deps fuera de lista en tiempo real; este agente razona sobre
+arquitectura y uso.
+
+## Contrato / datos
+
+### `api-contract-tester` · modelo `sonnet` · lee el dominio
+**Tester de contratos de API** (gate `api`); aplica solo a slices con endpoints (sin
+endpoints → `gates.api: null`). Identifica Route Handlers/Server Actions, localiza o crea la
+colección Postman (`tests/postman/<slice>.postman_collection.json` + `environment.json`) con
+casos happy/error/edge alineados a los AC, levanta la app si hace falta y ejecuta **Newman**;
+las aserciones validan status, esquema y campos clave. 100% verde → `gates.api: true`.
+
+### `data-consistency-checker` · modelo `sonnet` · lee el dominio
+**Verificador de consistencia de datos** (gate `data`); read-only sobre código pero ejecuta
+tests. Comprueba **patrones de invariante** (no valores de un dominio específico): la salida
+del servicio externo/IA validada contra esquema antes de alimentar la capa de decisión, tipos
+y unidades consistentes, campos faltantes modelados explícitamente; y en la capa de decisión
+determinista: determinismo, rango y constantes versionadas, explicabilidad (los drivers
+reconstruyen el total), consistencia cruzada y sin PII regulada cruda persistida. Todas las
+invariantes ✓ → `gates.data: true`.
+
+## Trazabilidad
+
+### `change-epic-coherence` · modelo `sonnet`
+**Auditor de coherencia change↔épica** (gate `coherence_link`); impide OpenSpec changes
+"huérfanos". Valida el bloque `## Trazabilidad` del `proposal.md` (líneas `Épica:` e
+`Historias:`, fuera del frontmatter), que la EP exista en `epicas.md`, que cada HU listada
+exista en `docs/04-historias/` con `epica:` coincidente, la coherencia de alcance
+(`Why`/`What Changes` dentro de la unión de AC de las HU cubiertas) y que
+`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).

package/docs/commands.md

@@ -0,0 +1,128 @@
+# Referencia de comandos — `@trycore/spec-build-harness`
+
+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.1.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:*` + `/build:onboard`) — operan el pipeline de dos loops y resuelven la parametrización **semántica** del dominio.
+
+> **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.
+
+---
+
+## 1. CLI `trycore-build`
+
+Comandos: `init` · `update` · `status` · `uninstall` · `doctor`. 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`. |
+| `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). |
+| `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. |
+
+### Flags
+
+Solo `init` y `update` aceptan flags. `status`, `uninstall` y `doctor` toman únicamente `[directory]`.
+
+| Flag | Comandos | Propósito |
+|---|---|---|
+| `--copy` | `init`, `update` | Copia los archivos en vez de symlinkearlos (Windows sin admin, sandboxes). En modo copia se preserva el bit ejecutable de los hooks. |
+| `--yes` | `init` | No interactivo: usa los defaults del stack sin abrir prompt TTY (CI-safe). |
+| `--skip-doctor` | `init`, `update` | Omite la verificación de `openspec`/`python3`/`git`. No recomendado: los hooks y `/opsx:*` fallarán en runtime si faltan. |
+| `--force-init` | `init` | Fuerza modo `init` aunque ya exista una instalación previa (en vez de auto-detectar `update`). |
+| `--stack <deps>` | `init` | Dependencias/paquetes permitidos, coma-separados, para poblar `stack-allowlist.json` (no interactivo). |
+| `--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`). |
+
+> 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.
+
+### Requisitos externos duros
+
+`init` y `doctor` **fallan (exit 1)** si falta alguno. El CLI no puede instalarlos por ti:
+
+| Requisito | Por qué | Instalación |
+|---|---|---|
+| `openspec` | Columna vertebral de `/opsx:*` y las skills `openspec-*`. | `npm i -g @fission-ai/openspec` |
+| `python3` | Los hooks bash parsean JSON con `python3`. | Vía el gestor de tu sistema. |
+| `git` | Los hooks y `gitflow-guard` resuelven la raíz con `git rev-parse`. | Vía el gestor de tu sistema. |
+
+---
+
+## 2. Slash commands de Claude Code
+
+El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y `.claude/commands/build/` → `/build:onboard`.
+
+### `/opsx:*` — pipeline OpenSpec
+
+| Slash command | Propósito |
+|---|---|
+| `/opsx:explore` | Entra en modo exploración: pensar ideas, investigar problemas, clarificar requisitos antes de comprometer un cambio. |
+| `/opsx:new` | Inicia un nuevo cambio OpenSpec (crea el artefacto inicial del change). |
+| `/opsx:continue` | Continúa un cambio en curso: genera el siguiente artefacto del workflow. |
+| `/opsx:apply` | Implementa las tareas declaradas en un cambio OpenSpec. |
+| `/opsx:verify` | Verifica que la implementación coincide con los artefactos del cambio **antes** de archivar. |
+| `/opsx:archive` | Archiva un cambio completado en el workflow. |
+| `/opsx:bulk-archive` | Archiva varios cambios completados de una sola vez. |
+| `/opsx:ff` | Fast-forward: crea un cambio y genera **todos** los artefactos necesarios para implementar en un solo paso. |
+| `/opsx:onboard` | Onboarding guiado: recorre un ciclo completo del workflow OpenSpec con narración (tutorial de aprendizaje). |
+| `/opsx:sync` | Sincroniza los delta specs de un cambio hacia los specs principales. |
+
+### `/build:onboard` — parametrización del dominio
+
+| Slash command | Propósito |
+|---|---|
+| `/build:onboard` | Parametriza el dominio del arnés: capa de servicios externos/IA, lógica determinista, PII, secretos y decisiones de alto impacto. Lee el PRD, pregunta vía AskUserQuestion, rellena el bloque marcado de `CLAUDE.md` y escribe la auto-memory. **Complementa** a `trycore-build init` (que ya sembró archivos y el stack mecánico). |
+
+---
+
+## 3. Caveat de canales (CLI vs. plugin)
+
+El arnés se distribuye por **dos canales** que coexisten, pero **namespacean distinto** los componentes. Esto es importante porque las cross-references internas (skills que invocan comandos, agentes referenciados por nombre) están escritas para el canal CLI.
+
+| 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 `/build:onboard` | 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 |
+
+> **Recomendación:** opera tus proyectos con el **canal CLI**. El plugin nativo se ofrece como conveniencia, pero el prefijo `/trycore-spec-build-harness:*` y el namespacing por nombre de plugin pueden romper las cross-references internas escritas para `/opsx:*` y los agentes por nombre.
+
+### Hooks: una sola cadena en ambos canales
+
+Los hooks usan una **única cadena autorresolutiva idéntica** en los dos canales:
+
+```
+"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/<script>.sh"
+```
+
+Si instalas **ambos** canales, Claude Code deduplica la cadena y el hook **dispara una sola vez**. `doctor` lo detecta y lo informa; no requiere acción.
+
+---
+
+## 4. Flujo de instalación de extremo a extremo
+
+```bash
+# 1. Requisitos externos (una vez por máquina)
+npm i -g @fission-ai/openspec      # openspec
+# python3 y git: vía el gestor de tu sistema
+
+# 2. Instala el CLI del arnés
+npm i -g @trycore/spec-build-harness
+
+# 3. En la raíz del proyecto: siembra archivos + captura el stack mecánico
+cd <tu-proyecto>
+trycore-build init                 # o init --yes / --stack ... / --prd-path ...
+
+# 4. En Claude Code: parametriza el dominio y escribe la auto-memory
+/build:onboard
+```
+
+Verifica en cualquier momento con `trycore-build status` y `trycore-build doctor`.
+
+---
+
+**Fuente de verdad.** La metodología canónica vive en `METODOLOGIA.md`. Si una skill contradice la metodología, **gana la metodología**.

package/docs/customization/mcp-extensions.md

@@ -0,0 +1,117 @@
+# Extensiones MCP / LSP del arnés (opt-in, agnóstico)
+
+> 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.
+
+## TL;DR
+
+- Los gates **pueden apoyarse** en MCP/LSP como **aceleradores**, nunca como dependencia dura.
+- **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**.
+- Regla de oro: **opt-in + just-in-time + datos sintéticos**. Habilita solo lo que tu stack use,
+  invócalo solo en su fase, y nunca pases datos sensibles reales ni secretos a un MCP.
+
+## Por qué opt-in y no dependencia
+
+El arnés es el compañero de construcción de `@trycore/spec-product-flow`: del PRD/backlog al código,
+épica a épica (inner loop `building-a-slice`) y release a release (outer loop `releasing-a-version`).
+Para mantenerlo **portable a cualquier stack**, el contrato de cada gate se define por su **resultado
+verificable** (un test que pasa, un journey que camina, un contrato que responde), no por la
+herramienta que lo produce. Un MCP es solo una forma cómoda de obtener esa evidencia cuando está
+disponible:
+
+| Si tienes el MCP habilitado | Si NO lo tienes |
+|---|---|
+| 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.
+
+## Cómo lo declara el consumidor (en TU settings)
+
+Los MCP **no** se versionan en el arnés ni los siembra `trycore-build init`. Se declaran en tu
+configuración de Claude Code (a nivel proyecto o usuario), por ejemplo en
+`.claude/settings.local.json` de tu proyecto, en la sección de servidores MCP que use tu instalación
+de Claude Code. El patrón general es:
+
+1. Declaras el servidor MCP en tu `settings` (binario/transporte, según el proveedor que elijas).
+2. Lo habilitas solo en los entornos donde aplique (típicamente local/dev, no CI sin TTY).
+3. La skill `building-a-slice` y los agentes lo detectan a través de las herramientas `mcp__*`
+   expuestas y lo invocan **solo en la fase correspondiente**.
+
+> El arnés nunca escribe tus credenciales ni levanta el servidor por ti. La frontera de confianza
+> (qué se conecta, con qué permisos) es **tuya**.
+
+## El contrato: `mcp-map.md`
+
+La skill del inner loop referencia un único archivo que mapea **fase/agente → MCP de ejemplo → para
+qué**:
+
+```
+skills/building-a-slice/references/mcp-map.md
+```
+
+Trátalo como el **punto de extensión documentado**. Si en tu proyecto adoptas un MCP para un gate,
+ese mapa es donde dejas constancia de la convención (qué MCP, en qué fase, con qué alternativa CLI si
+no está disponible). Mantén la tabla en el mismo formato agnóstico: ejemplos, nunca obligaciones.
+
+## Ejemplos de extensión por gate
+
+Los siguientes son **ejemplos representativos** de cómo un MCP/LSP puede apoyar un gate. Sustituye
+cada uno por el que aplique a **tu** stack declarado en el PRD; ninguno es obligatorio.
+
+| 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. |
+| `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. |
+| `coherence` / diseño | `coherence-three-way`, `simple-design-reviewer`, `stack-guardian` | **LSP del lenguaje** (p. ej. LSP de TypeScript en stacks TS tipados) | Seguir definiciones/referencias con precisión de compilador: trazar símbolo→test, detectar duplicación y uso real. Mejor ROI que `grep` en código tipado. | Navegación con `grep`/`glob` + lectura dirigida. |
+| perf (opcional, **fuera del DoD**) | — | MCP de pruebas de carga (p. ej. un MCP de k6) | Carga/latencia si una HU de la épica lo exige explícitamente. | Omitir; no es un gate del arnés. |
+
+Notas de coherencia con el arnés:
+
+- En el **inner loop** los gates pesados (`security`, `smell`, `ux`, coherencia triple completa,
+  arquitectura, integración con deps reales) **no** se cierran por épica: corren **una vez por
+  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.
+
+## Reglas de uso (no negociables)
+
+1. **Opt-in y just-in-time.** Habilita un MCP solo si tu entorno lo expone, e invócalo **solo en su
+   fase**. No lo cargues "por si acaso": protege el contexto.
+2. **El MCP de navegador requiere la app levantada.** Úsalo en la fase con la app corriendo
+   (`journey_smoke` en el inner loop, `integration`/`ux` en el release gate).
+3. **Datos sintéticos siempre.** Ningún MCP debe recibir datos sensibles / PII regulados reales —los
+   que el consumidor declara en el bloque de dominio de su `CLAUDE.md` o su PRD— ni secretos. Los MCP
+   de BD apuntan a entornos de prueba con datos sintéticos.
+4. **No conviertas un acelerador en dependencia.** Si introduces un MCP, deja siempre documentada la
+   alternativa CLI/test en `mcp-map.md` para que el gate siga cerrándose sin él.
+5. **CI-safe.** Los MCP que requieren TTY o sesión interactiva van deshabilitados en CI; los gates
+   relevantes en CI se cubren por la alternativa de test/CLI.
+
+## Cómo adoptar un MCP en tu proyecto (checklist)
+
+1. Identifica el gate que quieres acelerar y comprueba que el MCP aplica a tu stack declarado.
+2. Declara el servidor MCP en **tu** `settings` (no en el arnés) y habilítalo en el entorno correcto.
+3. Anota la convención en `skills/building-a-slice/references/mcp-map.md`: fase, MCP, para qué, y la
+   alternativa sin MCP.
+4. Verifica que el gate **sigue pasando con y sin** el MCP (portabilidad).
+5. Confirma que no fluyen datos sensibles reales ni secretos hacia el MCP.
+
+## Diagramas y diseño (extensión opcional aparte)
+
+Para diagramas de arquitectura/flujo del slice, un ecosistema de diseño (p. ej. un MCP de Figma) es
+**otro ejemplo opt-in**: si está habilitado puede ayudar a documentar, pero es totalmente opcional y
+**no forma parte de ningún gate** del arnés.
+
+---
+
+**Fuente de verdad.** El mapa operativo por gate vive en
+`skills/building-a-slice/references/mcp-map.md`. Si algo aquí contradice la metodología Trycore
+(`METODOLOGIA.md`), **gana la metodología**.

package/docs/examples/reference/data-consistency.example.md

@@ -0,0 +1,61 @@
+# Ejemplo de dominio: consistencia de datos en KYC
+
+> Este archivo es un **ejemplo concreto** de cómo un consumidor del arnés (en este caso, un proyecto
+> KYC) instancia los invariantes-patrón definidos en `agents/build/data-consistency-checker.md`.
+> El agente es agnóstico; los valores concretos de abajo viven en el dominio del consumidor
+> (su PRD / su bloque de dominio en CLAUDE.md).
+
+## Mapeo invariante-patrón → instancia KYC
+
+| Invariante-patrón (agente) | Instancia concreta KYC |
+|---|---|
+| Servicio externo/IA de la frontera | Capa de extracción Gemini (Gemini 3.5 Flash, modo extract-only, vía `google-genai`) |
+| Salida del servicio = input no confiable, validar contra esquema | El JSON que devuelve Gemini se valida con **zod** antes de alimentar el motor |
+| Capa de decisión determinista del dominio | Motor de scoring determinista (sin IA) |
+| Decisiones de alto impacto del dominio | Banda ∈ {Aprobar, Escalar, Rechazar} |
+| Constantes desde config versionada | Pesos por factor y umbrales de banda versionados (no literales dispersos) |
+| Datos regulados/PII crudos | Cédula, nombre, extracto bancario |
+
+## Esquema de extracción (Gemini → JSON fijo), validado con zod
+
+Campos típicos del esquema fijo de extracción:
+
+- **Identidad**: nombre completo, número de cédula (documento normalizado), fecha de nacimiento.
+- **Ingresos declarados**: monto numérico.
+- **Movimientos/saldos**: lista de movimientos del extracto bancario, saldos por periodo.
+
+Reglas de validación concretas:
+
+1. La salida de Gemini valida contra el esquema zod (identidad, ingresos declarados,
+   movimientos/saldos). Si Gemini devuelve algo malformado, se **rechaza**, no se propaga al scoring.
+2. Tipos y unidades consistentes: montos numéricos, fechas en ISO, número de cédula normalizado.
+3. Campos faltantes se modelan como `null`/opcional, nunca con valores fantasma (p. ej. ingreso `0`
+   por defecto cuando en realidad falta el dato).
+
+## Motor de scoring determinista (sin IA)
+
+4. **Determinismo**: el mismo extracto + misma identidad → mismo score y misma banda, siempre.
+   Sin aleatoriedad ni llamada a IA dentro del motor.
+5. **Rango**: score acotado con base 100; banda ∈ {Aprobar, Escalar, Rechazar} según umbrales
+   versionados. Pesos y umbrales se leen de config versionada.
+6. **Explicabilidad**: la suma de los descuentos (drivers) por factor reconstruye el descuento total;
+   el score final cuadra con la base menos los drivers.
+7. **Identidad cruzada**: nombre, número de cédula y fecha de nacimiento se comparan entre documentos
+   (p. ej. cédula vs. extracto). Las discrepancias se atribuyen al documento correcto.
+8. **Sin PII cruda persistida** (cédula, nombre, extracto) como efecto colateral de los cálculos.
+
+## Casos borde / fixtures concretos del dominio KYC
+
+Los fixtures de test deben cubrir al menos:
+
+- **Extracto vacío**: el extracto bancario no trae movimientos.
+- **Saldos negativos**: saldos por debajo de cero en uno o más periodos.
+- **Nombres con tildes / typos**: variaciones ortográficas entre identidad declarada y documento.
+- **Ingresos en cero**: ingreso declarado `0` (distinguir de ingreso faltante = `null`).
+- **Discrepancia de identidad**: número de cédula que no coincide entre dos documentos.
+
+## Referencia de requisitos técnicos
+
+Los detalles de esquema, umbrales y stack concreto provienen de la sección de requisitos técnicos
+del PRD del consumidor (en este proyecto KYC: la sección §7 del PRD de validación documental, cuya
+ruta canónica se declara en `stack-allowlist.json#source`).

package/docs/examples/reference/security-foco.example.md

@@ -0,0 +1,39 @@
+# Ejemplo concreto: Foco de seguridad para un dominio KYC
+
+> Este archivo es un **ejemplo de dominio** (no forma parte del core agnóstico). Muestra cómo un
+> consumidor del arnés instancia las categorías genéricas del `security-reviewer` con los activos
+> concretos de su dominio. Un consumidor de KYC declararía esto en el bloque de dominio de su
+> `CLAUDE.md` o en la sección de requisitos técnicos de su PRD.
+
+## Mapeo de categorías genéricas → activos concretos del dominio KYC
+
+1. **Secretos de servicios externos server-side → `GEMINI_API_KEY`.**
+   La `GEMINI_API_KEY` debe vivir solo server-side. Jamás en cliente, en bundles, ni en logs.
+   Las llamadas a Gemini (Gemini 3.5 Flash, vía `google-genai`) ocurren en el servidor. Marca
+   cualquier fuga al browser.
+
+2. **Datos sensibles / PII regulados no persistidos crudos → cédula, nombre, extracto bancario.**
+   El prototipo NO debe guardar cédula/nombre/extracto crudos más allá de la demo
+   (ver `docs/01-prd/validacion-documental-kyc.md#7`). Verifica que no se escriben a
+   better-sqlite3/localStorage/logs sin necesidad.
+
+3. **Archivos / entrada cargada → documentos de identidad y extractos.**
+   Validar tipo/tamaño; no ejecutar ni renderizar contenido no confiable.
+
+4. **Salida de servicios externos/IA como input no confiable → JSON de Gemini.**
+   Tratar el JSON de Gemini (capa de extracción extract-only) como entrada no confiable →
+   validar con zod antes de alimentar el motor de scoring determinista.
+
+5. **Logs/telemetría → sin PII KYC.**
+   Sin cédula/nombre/extracto ni el contenido de documentos; redacción de campos sensibles.
+
+6. **Decisiones auditables sin sobre-exposición → Aprobar/Escalar/Rechazar.**
+   La evidencia mostrada al analista de KYC para soportar la decisión (Aprobar / Escalar /
+   Rechazar) no debe filtrar más PII de la necesaria.
+
+## Stack de referencia del ejemplo
+
+- Next.js / Tailwind / shadcn en el front.
+- better-sqlite3 como almacenamiento de la demo.
+- Gemini 3.5 Flash (`google-genai`) como capa de extracción extract-only.
+- Motor de scoring determinista para la tripleta Aprobar/Escalar/Rechazar.

package/docs/examples/reference/stack-allowlist.example.json

@@ -0,0 +1,61 @@
+{
+  "_comment": "Allowlist de dependencias derivada del PRD §7 (docs/01-prd/validacion-documental-kyc.md). Toda dependencia en package.json fuera de esta lista exige revisión manual de stack-guardian. Patrones soportan comodín de sufijo '*' para scopes. Editar SOLO si el PRD §7 cambia, y dejar nota en GOVERNANCE.md.",
+  "source": "docs/01-prd/validacion-documental-kyc.md#7-requisitos-tecnicos",
+  "version": "1.0",
+  "runtime": {
+    "node": ">=18.18",
+    "packageManager": "npm|pnpm"
+  },
+  "allow": [
+    "next",
+    "react",
+    "react-dom",
+    "typescript",
+    "tailwindcss",
+    "postcss",
+    "autoprefixer",
+    "@radix-ui/*",
+    "class-variance-authority",
+    "clsx",
+    "tailwind-merge",
+    "tailwindcss-animate",
+    "lucide-react",
+    "framer-motion",
+    "google-genai",
+    "@google/genai",
+    "@google/generative-ai",
+    "zod",
+    "better-sqlite3",
+    "@types/*",
+    "eslint",
+    "eslint-config-next",
+    "prettier",
+    "prettier-plugin-tailwindcss",
+    "vitest",
+    "@vitejs/plugin-react",
+    "jest",
+    "ts-jest",
+    "@testing-library/react",
+    "@testing-library/jest-dom",
+    "@testing-library/user-event",
+    "jsdom",
+    "newman",
+    "newman-reporter-htmlextra"
+  ],
+  "deny_examples": [
+    "express",
+    "axios",
+    "lodash",
+    "moment",
+    "openai",
+    "@anthropic-ai/sdk"
+  ],
+  "rationale": {
+    "frontend": "Next.js 14+ App Router + TypeScript + Tailwind + shadcn/ui (Radix + cva + lucide) + Framer Motion.",
+    "ai": "Extracción documental con Gemini 3.5 Flash vía google-genai. NO otros proveedores de IA (el scoring es determinista en TS, sin IA).",
+    "validation": "zod para validar el JSON de esquema fijo.",
+    "persistence": "Prototipo: better-sqlite3 o localStorage; sin PII cruda persistida.",
+    "testing": "vitest/jest + Testing Library (TDD); newman para contratos de endpoints.",
+    "deny_examples_reason": "Backend propio (express/axios), utilidades pesadas (lodash/moment) y otros SDK de IA contradicen el PRD §7."
+  }
+}