@trycore/spec-build-harness 0.2.0 → 0.5.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "trycore-spec-build-harness",
   "displayName": "Trycore — Spec & Build Harness",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Arnés de construcción de dos loops (slice por épica + release gate) para Claude Code, con gates de calidad, estado compartido y OpenSpec. Compañero de @trycore/spec-product-flow. Agnóstico al proyecto.",
   "author": {
     "name": "Trycore",

package/GOVERNANCE.md

@@ -1,6 +1,6 @@
 # Gobernanza del arnés de construcción `.claude`
 
-Versión: ver `.claude/.build-harness-version` (`1.0.0`). El arnés es **soporte cognitivo vivo**:
+Versión del paquete: ver `.claude/.build-harness-version`. El arnés es **soporte cognitivo vivo**:
 evoluciona con el modelo y el proyecto. No es "instalar y olvidar".
 
 ## Componentes y dueño
@@ -8,15 +8,16 @@ evoluciona con el modelo y el proyecto. No es "instalar y olvidar".
 |---|---|---|
 | Contexto | sección Construcción de CLAUDE.md, `openspec/project.md` | raíz / `openspec/` |
 | Estado | `build-state.json` (+schema, README) | `.claude/state/` |
-| Agentes | 10 agentes de build | `.claude/agents/build/` |
-| Hooks | settings.json + 6 scripts | `.claude/settings.json`, `.claude/hooks/build/` |
-| Skill | `building-a-slice` + 10 references | `.claude/skills/building-a-slice/` |
+| Agentes | 11 agentes de build | `.claude/agents/build/` |
+| Hooks | settings.json + 9 scripts | `.claude/settings.json`, `.claude/hooks/build/` |
+| Skill | `building-a-slice` (+10 refs) · `building-a-micro-change` (carril ligero de mantenimiento) | `.claude/skills/` |
 | Config | allowlist de stack | `.claude/config/stack-allowlist.json` |
 
 ## Fases de activación (`harness_phase`)
 - **authoring** (actual): aún no hay `package.json`. Activos: `gitflow-guard`, `load-build-state`,
   `coherence-flag`; agentes de coherencia/stack/DoR/DoD operan sobre texto. Los hooks de
-  lint/typecheck/stack(package.json)/tests están **armados** pero inertes (`[ -f package.json ] || exit 0`).
+  lint/typecheck/stack(package.json)/tests están **armados** pero inertes (`[ -f package.json ] || exit 0`);
+  `scaffold-guard` permite (sin slice en fases de código que bloquear) y `reflect-nudge` calla (sin historial que reflexionar).
 - **active**: al aparecer `package.json`, `load-build-state.sh` cambia la fase y los hooks armados
   empiezan a disparar solos. Sin intervención manual.
 
@@ -40,6 +41,24 @@ Editar `stack-allowlist.json` SOLO si la sección de requisitos técnicos del PR
 ### Bitácora de excepciones de stack
 - _(vacío)_ — registrar fecha, dependencia, justificación y aprobador.
 
+## Bitácora de cambios de metodología
+Cambios a la política de construcción (unidad de trabajo, gates, DoR/DoD). Aprueba el DRI; van por PR.
+
+- **2026-06-03 · v0.5.0** — Seguro de fuente de diseño + verificación de fidelidad. Nuevo gate de
+  proyecto `design_source` (espejo de scaffold, confirmado por humano; el arnés no genera el prototipo)
+  con hook `design-source-guard.sh`; criterio DoR "fuente de diseño identificada" para slices con UI;
+  gate vivo de inner loop `fidelity` computado en `smoke` por el nuevo agente `ux-fidelity-reviewer`
+  (agnóstico, estático-primero, degrada sin MCP); 7º extension point `DESIGN_SOURCE` en el onboard.
+  Toca gates/DoR/DoD y el schema de estado → aprobado por el DRI (Agent Manager). Origen: revisión de
+  la propuesta externa de visual fidelity.
+
+- **2026-06-02 · v0.4.0** — Carril `building-a-micro-change` + DoR proporcional. El mantenimiento que
+  no es producto nuevo (typo, bump de dep permitida, copy/config/docs, fix de pocas líneas) deja de
+  modelarse como épica y usa un carril ligero (`fix/*`|`chore/*` → PR, sin `active_slice`), con
+  límites duros que lo escalan a épica (dep nueva, API nueva, lógica de dominio/datos). El DoR escala
+  el nº de escenarios G/W/T con `complejidad` en vez de exigir 3–5 fijos. La regla "épica = unidad"
+  se mantiene intacta para producto. Origen: auditoría del arnés vs. crítica de sobre-configuración.
+
 ## Extensiones futuras (no implementadas)
 - **Construcción en paralelo** de slices con `superpowers:using-git-worktrees` + orquestación
   multi-worktree (hoy el modelo es **secuencial** por decisión de proyecto). El `build-state.json`

package/INSTALL.md

@@ -11,7 +11,7 @@ Es el **compañero** de [`@trycore/spec-product-flow`](https://www.npmjs.com/pac
 | CLI (bin) | `trycore-build` |
 | Plugin | `trycore-spec-build-harness` |
 | Marketplace | `trycore-build` |
-| Versión | `0.1.0` |
+| Versión | `0.5.0` |
 
 Hay **dos canales** de instalación: el **CLI npm** (canónico, recomendado para operar en un
 proyecto) y el **plugin nativo** de Claude Code (conveniencia a nivel usuario). Lee el
@@ -28,7 +28,7 @@ npm install -g @trycore/spec-build-harness
 Esto expone el binario `trycore-build`. Comprueba la versión:
 
 ```bash
-trycore-build --version    # → 0.1.0
+trycore-build --version    # → 0.5.0
 trycore-build --help
 ```
 
@@ -84,10 +84,10 @@ Qué hace `init`:
 
 1. **Verifica requisitos duros** (a menos que uses `--skip-doctor`).
 2. **Siembra los assets** en rutas nativas de Claude Code:
-   - `.claude/agents/build/` — 10 agentes.
-   - `.claude/commands/opsx/` (10 comandos `/opsx:*`) y `.claude/commands/build/` (`/build:onboard`).
+   - `.claude/agents/build/` — 11 agentes.
+   - `.claude/commands/opsx/` (10 comandos `/opsx:*`) y `.claude/commands/build/` (`/build:onboard`, `/build:reflect`).
    - `.claude/skills/` — 12 skills (`building-a-slice`, `releasing-a-version`, `openspec-*`).
-   - `.claude/hooks/build/` — 6 hooks bash.
+   - `.claude/hooks/build/` — 9 hooks bash.
 3. **Siembra el estado**: `state/build-state.schema.json` y `state/README.md` se versionan;
    `state/build-state.json` se siembra **vacío y nunca se sobrescribe** (va al `.gitignore`).
 4. **Siembra `config/stack-allowlist.json`** (artefacto del consumidor; lo puebla `/build:onboard`).
@@ -184,6 +184,11 @@ Qué resuelve:
 
 Si un punto no aplica, se registra explícitamente "no aplica" (no se deja como `{{...}}`).
 
+> **Durante la construcción** (no en la instalación), el comando `/build:reflect` captura las
+> convenciones aprendidas de cada slice cerrado en el bloque `trycore-build-learnings` de
+> `CLAUDE.md` —con tu aprobación— y lo **sugiere** el hook `reflect-nudge.sh` al cerrar sesión.
+> Detalle en `docs/commands.md`.
+
 ---
 
 ## 5. Alternativa: plugin nativo (con caveat de canales)
@@ -228,7 +233,7 @@ Ambos paquetes coexisten en el mismo `.claude/` **sin colisión**, porque usan *
 
 | | Discovery — `spec-product-flow` | Construcción — `spec-build-harness` |
 |---|---|---|
-| Comandos | `/trycore:*` | `/opsx:*` + `/build:onboard` |
+| Comandos | `/trycore:*` | `/opsx:*` + `/build:onboard` + `/build:reflect` |
 | Marca de versión | `.trycore-version` | `.build-harness-version` |
 | Bloque en `CLAUDE.md` | `<!-- BEGIN trycore-vertical -->` | `<!-- BEGIN trycore-build-harness -->` |
 

package/METODOLOGIA.md

@@ -28,7 +28,7 @@ Ambos paquetes **coexisten en el mismo `.claude/` sin colisión**, con namespace
 
 | Eje | Discovery (`spec-product-flow`) | Construcción (`spec-build-harness`) |
 |---|---|---|
-| Comandos | `trycore/` (`/trycore:*`) | `opsx/` + `build/` (`/opsx:*`, `/build:onboard`) |
+| Comandos | `trycore/` (`/trycore:*`) | `opsx/` + `build/` (`/opsx:*`, `/build:onboard`, `/build:reflect`) |
 | Sentinela de versión | `.trycore-version` | `.build-harness-version` |
 | Bloque en `CLAUDE.md` | `<!-- BEGIN trycore-vertical -->` | `<!-- BEGIN trycore-build-harness -->` |
 
@@ -90,6 +90,15 @@ Consecuencia operativa: **la unidad de construcción es la épica, no la HU suel
 épica = un OpenSpec change = una rama = un PR. Las HU que cubre la épica son su *alcance interno* y
 se listan en `active_slice.hus[]`. Construir por HU individual es sobre-ingeniería.
 
+> **Carril micro-change (mantenimiento).** Esta regla rige la **construcción de producto**. El
+> **mantenimiento** que no es capacidad nueva —un typo, un ajuste de copy/config/docs, un bump de
+> dependencia ya permitida, o un fix de pocas líneas sin nueva capacidad— **no se modela como
+> épica**: usa el carril ligero de la skill `building-a-micro-change` (`fix/*`|`chore/*` → cambio →
+> PR, sin abrir `active_slice`). No es una excepción a la regla, sino mantenimiento fuera de su
+> alcance. **Límites duros:** si el cambio añade una dependencia nueva, crea un endpoint/API nuevo, o
+> toca lógica de dominio o el modelo/invariantes de datos, **deja de ser micro-change** y se escala a
+> épica. Ante la duda, es una épica.
+
 ---
 
 ## 3. Pipeline del inner loop, fase por fase (con sus gates)
@@ -117,7 +126,10 @@ Una épica **no entra a construcción** hasta cumplir todo (lo valida `dor-dod-g
 - 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`) con `estado: lista`.
-- AC en Given/When/Then por HU: 3–5 escenarios con happy + error + edge.
+- 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 + error/edge crítico si
+  existe); `media` → **3** (happy + error + edge); `alta` → **3–5** (cobertura completa). Si existe
+  rama de error/edge, debe tener su escenario.
 - Cada HU pasa los 6 criterios **INVEST**.
 - Dependencias resueltas (las épicas/HU de las que depende están en `history[]` o no bloquean).
 - Cabe en el stack del PRD (no requiere tecnología fuera de `stack-allowlist.json`).
@@ -351,8 +363,10 @@ El arnés **no escribe** en `docs/`; cuando una HU no cumple DoR, devuelve el tr
 
 ## 10. Reglas duras (resumen)
 
-1. La **épica** es la unidad de construcción: un slice = una épica = un change = una rama = un PR.
-   Las HU son alcance interno (`hus[]`).
+1. La **épica** es la unidad de construcción de **producto**: un slice = una épica = un change = una
+   rama = un PR. Las HU son alcance interno (`hus[]`). El **mantenimiento** que no es producto nuevo
+   (typo, bump, copy, infra/docs, fix de pocas líneas) usa el carril `building-a-micro-change`, fuera
+   de esta regla; cruzar un límite duro (dep nueva, API nueva, dominio/datos) lo escala a épica.
 2. El **esqueleto que camina** nunca deja de caminar: nada de capas horizontales que se juntan al
    final; `journey_smoke` verde en cada épica.
 3. **Dos loops sin duplicación**: gates baratos por épica (inner), gates pesados una vez por release

package/README.md

@@ -45,7 +45,7 @@ trycore-build init
 | `trycore-build update` | Refresca assets y schema tras `npm update -g`. No pisa estado ni allowlist. |
 | `trycore-build status` | Muestra el estado de la instalación y la fase activa del arnés. |
 | `trycore-build uninstall` | Quita el arnés. **Preserva** `.claude/state/` y `.claude/config/`. |
-| `trycore-build doctor` | Verifica requisitos externos (`openspec`/`python3`/`git`), hooks ejecutables y canales. |
+| `trycore-build doctor` | Verifica requisitos externos (`openspec`/`python3`/`git`), hooks ejecutables y canales; reporta slices sin reflexionar y sugiere **LSP** en stacks tipados. |
 
 Flags de `init`: `--copy` (copiar en vez de symlinkear), `--yes` (no interactivo), `--skip-doctor`, `--force-init`, `--stack <deps>`, `--pkg-manager <pm>`, `--runtime <semver>`, `--prd-path <path>`.
 
@@ -59,7 +59,7 @@ El arnés modela la construcción como dos ciclos anidados, cada uno con su skil
 DoR → OpenSpec change → TDD → journey-smoke → api/data → DoD → PR + archive
 ```
 
-Por cada épica del backlog: se valida el **Definition of Ready**, se abre un *change* en OpenSpec, se desarrolla con **TDD**, se corre el smoke del journey, se verifican contratos de API y consistencia de datos, se valida el **Definition of Done** y se cierra con PR + archivado del change.
+Por cada épica del backlog: se valida el **Definition of Ready**, se abre un *change* en OpenSpec, se desarrolla con **TDD**, se corre el smoke del journey, se verifican contratos de API y consistencia de datos, se valida el **Definition of Done** y se cierra con PR + archivado del change. Tras archivar, `/build:reflect` puede capturar las convenciones aprendidas del slice (**ciclo autocorrectivo**, opcional; lo sugiere el hook `reflect-nudge.sh`).
 
 ### Outer loop — `releasing-a-version` (una vez por release)
 
@@ -70,6 +70,7 @@ Gate de release que corre **una sola vez por versión** sobre el conjunto de sli
 | Command | Propósito |
 |---|---|
 | `/build:onboard` | Onboarding capa 2: lee el PRD, pregunta por PII/IA/determinismo/secretos, resuelve `{{placeholders}}` y escribe la auto-memory. |
+| `/build:reflect` | Reflexión post-slice: tras archivar, propone convenciones aprendidas / errores recurrentes al bloque `trycore-build-learnings` de `CLAUDE.md` (tras tu aprobación) y marca el slice como reflexionado. |
 | `/opsx:explore` | Explora el dominio / specs antes de abrir un change. |
 | `/opsx:new` | Crea un nuevo OpenSpec change. |
 | `/opsx:continue` | Retoma un change en curso. |
@@ -88,12 +89,12 @@ trycore-spec-build-harness/
 ├── METODOLOGIA.md             ← fuente de verdad metodológica (gana ante cualquier skill)
 ├── GOVERNANCE.md              ← gobernanza del paquete + cadencia de auditoría
 ├── .claude-plugin/            ← manifiesto del plugin nativo (canal de conveniencia)
-├── agents/build/              ← 10 agentes revisores (segunda opinión, contexto limpio)
+├── agents/build/              ← 11 agentes revisores (segunda opinión, contexto limpio)
 ├── commands/
 │   ├── opsx/                  ← 10 comandos /opsx:* (ciclo OpenSpec)
-│   └── build/                 ← /build:onboard
+│   └── build/                 ← /build:onboard, /build:reflect
 ├── skills/                    ← 12 skills (building-a-slice, releasing-a-version, 10 openspec-*)
-├── hooks/build/               ← 6 hooks bash (gate-check, gitflow-guard, stack-guard, …)
+├── hooks/build/               ← 9 hooks bash (gate-check, reflect-nudge, scaffold-guard, gitflow-guard, stack-guard, …)
 ├── state/                     ← máquina de estado: build-state.json + schema + README
 ├── config/                    ← stack-allowlist.template.json (artefacto del consumidor)
 ├── src/ + dist/               ← CLI trycore-build (init/update/status/uninstall/doctor)
@@ -101,7 +102,7 @@ trycore-spec-build-harness/
 └── docs/examples/reference/   ← ejemplo de referencia (fuera del core, excluido de check-agnostic)
 ```
 
-Los **10 agentes** en `agents/build/` son: `build-orchestrator`, `dor-dod-gatekeeper`, `security-reviewer`, `simple-design-reviewer`, `ux-krug-reviewer`, `coherence-three-way` (opus), `stack-guardian`, `api-contract-tester`, `data-consistency-checker` y `change-epic-coherence`.
+Los **11 agentes** en `agents/build/` son: `build-orchestrator`, `dor-dod-gatekeeper`, `security-reviewer`, `simple-design-reviewer`, `ux-krug-reviewer`, `coherence-three-way` (opus), `stack-guardian`, `api-contract-tester`, `data-consistency-checker`, `change-epic-coherence` y `ux-fidelity-reviewer`.
 
 **Estado.** `state/build-state.json` se siembra **vacío** y nunca se sobreescribe (va al `.gitignore`); el schema y el README sí se versionan. `config/stack-allowlist.json` es artefacto del consumidor: lo siembra el CLI y lo puebla `/build:onboard`. `uninstall` preserva `state/` y `config/`.
 
@@ -123,7 +124,11 @@ El core no menciona ningún dominio de cliente. Toda parametrización entra por
 
 ## Roadmap
 
-- ✅ **v0.1.0 (actual)** — arnés de dos loops (`building-a-slice` + `releasing-a-version`), 10 agentes, comandos `/opsx:*` + `/build:onboard`, 12 skills, 6 hooks, máquina de estado `build-state.json`, allowlist de stack, CLI `trycore-build` (init/update/status/uninstall/doctor) y plugin nativo. Compañero de `@trycore/spec-product-flow`.
+- ✅ **v0.1.0** — arnés de dos loops (`building-a-slice` + `releasing-a-version`), 10 agentes, comandos `/opsx:*` + `/build:onboard`, 12 skills, 6 hooks, máquina de estado `build-state.json`, allowlist de stack, CLI `trycore-build` (init/update/status/uninstall/doctor) y plugin nativo. Compañero de `@trycore/spec-product-flow`.
+- ✅ **v0.2.0** — scaffold como "Paso 1 fundamental": gate de proyecto `scaffold.confirmed` (confirmación **explícita**, no auto), Fase 0 en `building-a-slice`, criterio duro de DoR y hook `scaffold-guard.sh`. El arnés **exige** el scaffold pero **no lo genera**.
+- ✅ **v0.3.0** — **ciclo autocorrectivo** (hook `reflect-nudge.sh` + comando `/build:reflect`: propone convenciones aprendidas al bloque `trycore-build-learnings` de `CLAUDE.md` tras tu aprobación; campos `reflected`/`reflected_at`) y **LSP opt-in** (`docs/customization/lsp-extensions.md` + sugerencia en `doctor` para stacks tipados). Total: **8 hooks**; comandos `/opsx:*` + `/build:onboard` + `/build:reflect`.
+- ✅ **v0.4.0** — carril `building-a-micro-change` (mantenimiento ligero sin slice) + DoR proporcional a la complejidad.
+- ✅ **v0.5.0 (actual)** — seguro de fuente de diseño (`design_source` + `design-source-guard.sh`) + agente `ux-fidelity-reviewer` (gate `fidelity`, inner loop). Total: **11 agentes**, **9 hooks**.
 
 ## Licencia
 

package/VERSION

@@ -1 +1 @@
-0.2.0
+0.5.0

package/agents/build/build-orchestrator.md

@@ -19,7 +19,10 @@ La **unidad de construcción es la épica** (`active_slice.epica`); las HU que c
 1. dor      → delega en dor-dod-gatekeeper (abre el slice si pasa)
 2. change   → opsx:new + bloque ## Trazabilidad → delega en change-epic-coherence (gate coherence_link, barato)
 3. tdd      → conduce superpowers:test-driven-development (red→green→refactor)
-4. smoke    → recorre el journey-hasta-aquí end-to-end con la skill verify/run (+ chrome-devtools) → gate journey_smoke
+4. smoke    → recorre el journey-hasta-aquí end-to-end con la skill verify/run (+ chrome-devtools) → gate journey_smoke.
+              Slices con UI: con la app levantada, delega en ux-fidelity-reviewer (compara la(s) pantalla(s)
+              contra el DESIGN_SOURCE) y ESCRIBE gates.fidelity desde su veredicto (FIEL/DESVIACIONES
+              justificadas→true; DESVIACIONES→false; INCONCLUSO (MCP no disponible)→deja con nota; sin UI→null).
 5. api/data → api-contract-tester (si hay endpoints) · data-consistency-checker (si toca datos)
 6. dod      → dor-dod-gatekeeper (cierre por slice, DoD reducido)
 7. pr       → abre PR y archiva el change EN EL MISMO PR (opsx:archive + opsx:sync); back-ref en épica y HU
@@ -29,6 +32,8 @@ La **unidad de construcción es la épica** (`active_slice.epica`); las HU que c
 **Los agentes pesados ya NO corren aquí.** `security-reviewer`, `simple-design-reviewer`,
 `ux-krug-reviewer`, `coherence-three-way` y `stack-guardian` (arquitectura) corren **una vez por
 release** en la skill `releasing-a-version`. Las deps las vigila el hook `stack-guard.sh`.
+El `ux-fidelity-reviewer` **sí** corre aquí (en `smoke`): es barato (la app ya está levantada) y vivo
+por-slice; no es la revisión pesada de UX/Krug (esa sigue en `releasing-a-version`).
 
 ## Reglas de orquestación
 - **No saltes gates.** No avances de fase si el gate previo está en `false`. Reporta qué falta.

package/agents/build/dor-dod-gatekeeper.md

@@ -23,16 +23,21 @@ cumplen; lista cada una con ✓/✗:
 2. Tiene **al menos una HU** asociada y todas se enumeran en `hus[]`.
 3. **Cada HU** de la épica: frontmatter YAML completo (`id, titulo, epica, prioridad, complejidad,
    estado`) y `estado: lista`.
-4. **Cada HU**: AC en formato **Given/When/Then**, 3–5 escenarios con happy + error + edge.
+4. **Cada HU**: AC en formato **Given/When/Then**, **proporcional a `complejidad`** (`trivial`/baja →
+   1–2; `media` → 3; `alta` → 3–5), cubriendo los modos de fallo que existen (happy + error/edge
+   reales). No exijas 3–5 a una HU trivial; sí exige el escenario de toda rama de error/edge que exista.
 5. **Cada HU** pasa los 6 criterios **INVEST** (si dudas, invoca al agente `invest-validator`).
 6. Dependencias declaradas (otras épicas/HU) están en `history[]` del estado o marcadas done.
 7. El alcance de la épica cabe en el stack declarado del PRD (allowlist) (no exige tecnología fuera de la allowlist).
+8. **Fuente de diseño (solo slices con UI)**: si la épica toca UI, `design_source.confirmed===true`
+   (fuente visual de verdad declarada para el proyecto) y la épica apunta a la(s) pantalla(s)
+   equivalente(s) del `DESIGN_SOURCE`. Si no toca UI, este criterio es N/A.
 
 Si DoR pasa: propón abrir `active_slice` con `epica`, `hus` (lista de las HU cubiertas),
 `openspec_change` (kebab del título de la épica), `branch: feature/ep-xxx-<slug>`, `phase: dor`,
-`gates: { dor: true, tdd: false, journey_smoke: false, coherence_link: false, data: false, dod: false }`
-(`api` en `null` si la épica no toca endpoints; añade `data: null`-equivalente omitiéndolo si no toca
-datos). Si falla: reporta ✗ y NO abras el slice.
+`gates: { dor: true, tdd: false, journey_smoke: false, coherence_link: false, data: false, fidelity: false, dod: false }`
+(`api` en `null` si la épica no toca endpoints; **`fidelity` en `null` si la épica NO toca UI**; añade
+`data: null`-equivalente omitiéndolo si no toca datos). Si falla: reporta ✗ y NO abras el slice.
 
 ## Definition of Done (gate `dod`) — antes de archivar (DoD **reducido**, por slice)
 Pasa SOLO si **todos** estos gates del **inner loop** están en `true` (o `null` cuando N/A):
@@ -41,8 +46,10 @@ Pasa SOLO si **todos** estos gates del **inner loop** están en `true` (o `null`
 3. `coherence_link` — `change-epic-coherence` confirma el enlace change↔épica (`openspec validate` ok).
 4. `data` — `data-consistency-checker` verde (si el slice toca datos).
 5. `api` — `api-contract-tester` verde (o `null` si sin endpoints).
-6. Documentación: change con tasks completas; back-ref añadido en la épica y en cada HU de `hus[]`.
-7. Hooks verdes (automáticos): `lint-typecheck.sh`, `stack-guard.sh`, `gitflow-guard.sh`.
+6. `fidelity` — `true` (FIEL o DESVIACIONES justificadas) o `null` (slice sin UI). INCONCLUSO
+   (MCP no disponible) se registra en `notes`, no bloquea. Es gate **vivo** de inner loop, no la revisión Krug.
+7. Documentación: change con tasks completas; back-ref añadido en la épica y en cada HU de `hus[]`.
+8. Hooks verdes (automáticos): `lint-typecheck.sh`, `stack-guard.sh`, `gitflow-guard.sh`.
 
 **NO valides aquí** `security`, `smell`, `ux`, `coherence` (triple completa) ni `stack` (arquitectura):
 esos son del **Release Gate** (`releasing-a-version`, `release-dod.md`), cadencia por release.

package/agents/build/ux-fidelity-reviewer.md

@@ -0,0 +1,61 @@
+---
+name: ux-fidelity-reviewer
+description: Verifica la FIDELIDAD VISUAL de una pantalla de la app corriendo contra la fuente de diseño declarada (el DESIGN_SOURCE del dominio del consumidor). Complementa al ux-krug-reviewer (que mide usabilidad, no fidelidad). Úsalo en slices con UI, en la fase smoke. Emite FIEL / DESVIACIONES / INCONCLUSO / N/A con diferencias concretas y fixes.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+Eres el **revisor de fidelidad visual** del arnés de construcción. Read-only sobre el código. Compruebas
+que una pantalla construida **se parece a la fuente de diseño declarada** por el consumidor (el
+`DESIGN_SOURCE` del bloque de dominio de su CLAUDE.md / su PRD). NO juzgas usabilidad (eso es
+`ux-krug-reviewer`): juzgas si **composición, layout, paleta y tipografía** reproducen el diseño.
+
+> Existe porque un re-skin puede acertar los *tokens* (color/fuente) y aun así **ignorar la
+> composición** (p.ej. una sola columna centrada cuando el diseño declara dos paneles).
+
+## Paso 0 — ¿aplica?
+Si el slice **no tiene UI**, devuelve **N/A** y termina (para que el gate `fidelity` quede en `null`),
+igual que `ux-krug-reviewer`.
+
+## Entradas (pídelas si faltan)
+- La(s) pantalla(s) del slice (rutas de la app, p.ej. `<URL-local-del-dev-server>/<ruta>`).
+- La fuente de diseño (`DESIGN_SOURCE`): archivo/URL del prototipo o export, y cómo localizar la
+  pantalla equivalente.
+- Tokens de diseño del proyecto (los que declare el stack del PRD del consumidor: variables CSS, tema,
+  design tokens), si existen.
+
+## Cómo revisar (estático primero, como ux-krug-reviewer)
+- **Estático (primario)**: lee el código de la pantalla (con la librería de UI del stack declarado en
+  el PRD del consumidor) y contrástalo contra la descripción del `DESIGN_SOURCE` y los tokens.
+- **Dinámico (apoyo, si la app corre y hay MCP de inspección de UI habilitado)**: sugiere usar un MCP
+  de inspección de UI (p.ej. **chrome-devtools** para web): `new_page`/`take_screenshot` del prototipo
+  y de la app, y `take_snapshot` (árbol accesible/DOM) para comparar **estructura**, no solo píxeles.
+  Si el MCP **no está disponible** (headless/CI), NO inventes: veredicto **INCONCLUSO (MCP no
+  disponible)** + lo que sí se verifique en estático.
+- **Bifurca por la fuente**: si la fuente de diseño es **renderizable** (prototipo HTML / URL
+  navegable) usa screenshot + snapshot; si **no es navegable** (export de diseño / imagen / PDF),
+  compara contra el export sin `take_snapshot` (no hay DOM que comparar).
+
+## Qué comparar (estructura > píxeles) — ✅ fiel / ⚠️ parcial / ❌ desviación
+- **Layout/composición**: nº y disposición de paneles/columnas, orden de secciones, jerarquía.
+- **Componentes clave presentes**: cada bloque del diseño (barra, hero, tarjetas, footer, callouts) existe.
+- **Paleta**: colores dominantes = tokens declarados; marca usos fuera de paleta.
+- **Tipografía**: familias y escala/peso de titulares vs cuerpo.
+- **Copy estructural**: titulares y CTAs clave coinciden en intención.
+- **Estados**: los estados que el diseño muestra (error, vacío…) existen.
+No penalices desviaciones **justificadas y documentadas** (datos ilustrativos estáticos, copy
+reconciliado por una ADR); lístalas como "desviación intencional". **No pixel-diff** (frágil).
+
+## Salida + mapeo al gate
+Veredicto **FIEL / DESVIACIONES / INCONCLUSO / N/A** + tabla región×veredicto con evidencia + lista
+priorizada de diferencias con su fix (archivo/componente) + desviaciones intencionales aceptadas.
+
+Mapeo que aplicará el `build-orchestrator` al escribir `gates.fidelity`:
+- **FIEL** → `true`
+- **DESVIACIONES** todas justificadas/documentadas → `true`
+- **DESVIACIONES** sin justificar → `false`
+- **N/A** (sin UI) → `null`
+- **INCONCLUSO** (MCP no disponible) → el orquestador deja `gates.fidelity: null` con nota
+  (INCONCLUSO, MCP no disponible) — **no bloquea** el DoD.
+
+Eres read-only: **no editas código ni el estado**. Devuelve el diagnóstico al `build-orchestrator`.

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,7 @@ 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
 ```
 
 ---
@@ -61,6 +62,9 @@ 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 `{{...}}`).
 
 ---
@@ -71,7 +75,7 @@ Lee `CLAUDE.md`. Encuentra el bloque entre `<!-- BEGIN trycore-build-harness` y
 
 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 +91,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 +111,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 +128,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 +145,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/commands/build/reflect.md

@@ -0,0 +1,163 @@
+---
+name: "BUILD: Reflect"
+description: Reflexión post-slice (ciclo autocorrectivo). Tras cerrar/archivar un slice, detecta convenciones aprendidas y errores recurrentes, PROPONE viñetas para el bloque de aprendizajes de CLAUDE.md (se aplican SOLO con tu aprobación) y estampa el slice como reflexionado. Lo dispara el hook reflect-nudge.sh, pero puedes invocarlo cuando quieras.
+category: Workflow
+tags: [reflexion, conocimiento, ciclo-autocorrectivo, build-harness, trycore]
+---
+
+Captura el **conocimiento tribal** de un slice recién cerrado antes de que se pierda. Un hook bash no
+puede razonar qué se aprendió; **tú (el modelo) sí**. Tu trabajo: detectar convención nueva o error
+recurrente, **proponérselo al usuario**, y —solo con su aprobación— escribirlo al bloque
+`trycore-build-learnings` de `CLAUDE.md`. Nunca escribes sin confirmación.
+
+Esta es la mejora del **pilar "ciclo autocorrectivo"**: el hook `reflect-nudge.sh` (evento `Stop`)
+solo **sugiere** ejecutar esto cuando hay slices archivados sin reflexionar; el razonamiento vive
+aquí, en el modelo.
+
+---
+
+## Preflight
+
+```bash
+test -f .claude/.build-harness-version || echo "NOT_INSTALLED"
+command -v python3 >/dev/null 2>&1 || echo "NO_PYTHON3"
+```
+
+**Si `NOT_INSTALLED`:**
+
+> Este proyecto no tiene el arnés de construcción instalado. Ejecuta primero `trycore-build init`.
+
+Stop aquí si no está instalado o si falta `python3`.
+
+---
+
+## Fase 1: Identificar slices sin reflexionar
+
+Lee `.claude/state/build-state.json` y filtra las entradas de `history[]` con `reflected != true`:
+
+```bash
+python3 - <<'PY'
+import json
+d = json.load(open(".claude/state/build-state.json"))
+pend = [h for h in (d.get("history") or []) if h.get("reflected") is not True]
+for h in pend:
+    print(h.get("epica"), "·", h.get("openspec_change"), "·", h.get("branch"), "·", ",".join(h.get("hus") or []))
+print("TOTAL", len(pend))
+PY
+```
+
+**Si `TOTAL 0`:** informa "No hay slices pendientes de reflexión ✅" y termina. No inventes trabajo.
+
+Si hay varios, procésalos **de uno en uno** (el más reciente primero), o pregunta al usuario cuál.
+
+---
+
+## Fase 2: Recolectar señal del slice
+
+Para el slice elegido, reúne evidencia **real** (no especules):
+
+1. **El change OpenSpec**: `openspec show <openspec_change>` y/o los archivos del change
+   (proposal/tasks). ¿Qué se decidió y qué tasks costaron más?
+2. **El diff de la rama**: `git log --oneline <branch>` y `git diff main...<branch> --stat` (si la
+   rama o sus commits existen). ¿Qué patrón de código se repitió? ¿Qué se reescribió varias veces?
+3. **La sesión actual**: qué hooks se dispararon más de una vez (p.ej. `stack-guard.sh`,
+   `gitflow-guard.sh`, `lint-typecheck.sh`), qué gates retrocedieron, qué correcciones se repitieron.
+
+Con esa evidencia, detecta **0–3** aprendizajes candidatos, de estas categorías:
+
+- **Convención nueva**: un patrón de código/estructura/nombrado que se repitió y conviene fijar para
+  el equipo (ej. "los handlers validan en el borde con el esquema X antes de tocar el dominio").
+- **Error recurrente**: algo que un gate o hook atrapó >1 vez y vale la pena prevenir
+  (ej. "recordar correr migraciones antes del journey-smoke").
+- **Fricción del propio arnés**: si el aprendizaje es sobre el arnés (un gate confuso, un paso que
+  sobra), NO lo escribas a CLAUDE.md — anótalo como candidato para `internal/skills/auditar-arnes`
+  y dilo al usuario.
+
+Si no hay nada que valga la pena fijar, es válido **no proponer aprendizajes** (solo estampar, Fase 5).
+
+---
+
+## Fase 3: Proponer (con aprobación explícita)
+
+Por **cada** aprendizaje candidato, usa **AskUserQuestion** para que el usuario lo apruebe, edite o
+descarte. Presenta cada uno como una **viñeta concreta y accionable**, lista para CLAUDE.md. Ejemplo
+de opciones: "Agregar tal cual" (Recomendado) · "Editar" · "Descartar".
+
+**Reglas:**
+- Una viñeta = una convención. Concreta, verificable, en presente imperativo. Nada vago.
+- No propongas conocimiento que ya está en el bloque (léelo antes). No dupliques.
+- Si un aprendizaje es **personal/cross-proyecto** (no de equipo), ofrécelo para **auto-memory**
+  (`type: project`/`user`) en vez de CLAUDE.md — pregunta cuál destino.
+
+---
+
+## Fase 4: Aplicar SOLO lo aprobado al bloque de aprendizajes
+
+Para las viñetas aprobadas, **inserta** (no reemplaces) dentro del bloque marcado de `CLAUDE.md`,
+**justo antes** de `<!-- END trycore-build-learnings -->`:
+
+```markdown
+- (EP-XXX) <viñeta aprobada>
+```
+
+- Prefija cada viñeta con la épica del slice `(EP-XXX)` para trazabilidad.
+- **NO toques nada fuera del bloque** `trycore-build-learnings`. En particular, NO modifiques el
+  bloque `trycore-build-harness` ni sus `{{placeholders}}` de dominio (eso es de `/build:onboard`).
+- Si el bloque `trycore-build-learnings` no existe (instalación vieja), pide correr
+  `trycore-build update` antes de continuar.
+- Las viñetas son cambio de equipo: se revisan en PR como cualquier otra línea de `CLAUDE.md`.
+
+---
+
+## Fase 5: Estampar el slice como reflexionado
+
+Marca el/los slice(s) procesado(s) en `history[]` para que el nudge calle. Usa la hora UTC real:
+
+```bash
+NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+python3 - "$NOW" "<openspec_change>" <<'PY'
+import json, sys
+now, change = sys.argv[1], sys.argv[2]
+p = ".claude/state/build-state.json"
+d = json.load(open(p))
+for h in d.get("history") or []:
+    if h.get("openspec_change") == change:
+        h["reflected"] = True
+        h["reflected_at"] = now
+json.dump(d, open(p, "w"), indent=2, ensure_ascii=False)
+print("estampado:", change)
+PY
+```
+
+Estampa **aunque no haya habido aprendizajes** (reflexionar y no encontrar nada también cierra el
+ciclo). Repite por cada slice procesado.
+
+---
+
+## Fase 6: Confirmación
+
+```
+## ✓ Reflexión completada
+
+Slice:        <EP-XXX> (<openspec_change>)
+Aprendizajes: <N agregados a CLAUDE.md> · <M a auto-memory> · <0 si solo se estampó>
+Estampado:    reflected=true
+
+Pendientes de reflexión restantes: <K>
+```
+
+Si quedan slices pendientes (`K > 0`), ofrece continuar con el siguiente.
+
+---
+
+## Guardrails
+
+- **Aprobación explícita siempre.** Nunca escribes a CLAUDE.md sin que el usuario apruebe cada
+  viñeta. Espeja la regla del scaffold: el arnés propone, el humano confirma.
+- **Evidencia, no invención.** Cada aprendizaje sale del change/diff/sesión reales. Si no hay
+  evidencia, no propongas.
+- **No reescribas.** Inserta viñetas; jamás borres ni reemplaces aprendizajes previos del equipo.
+- **No toques el paquete.** No modifiques agentes/skills/hooks del arnés (eso es mantenimiento, ver
+  `internal/skills/auditar-arnes`).
+- **Estampa siempre** al terminar, para no re-molestar con el mismo slice.
+- Si algo aquí contradice `METODOLOGIA.md`, **gana la metodología**.