@trycore/spec-build-harness 0.2.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trycore/spec-build-harness",
-  "version": "0.2.0",
+  "version": "0.5.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": {
@@ -18,6 +18,7 @@
     "templates/",
     "internal/",
     "docs/",
+    "!docs/superpowers",
     "scripts/",
     "METODOLOGIA.md",
     "GOVERNANCE.md",

package/skills/building-a-micro-change/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: building-a-micro-change
+description: Use for genuine maintenance that is NOT new product capability — a typo, a copy/string tweak, a dependency version bump within the stack allowlist, an infra/config/docs change, or a small bug fix of a few lines that adds no new capability. Lightweight lane — branch fix/*|chore/* → change → regression test only if behavior changes → PR — WITHOUT opening active_slice, an epic (EP-XXX), or an OpenSpec change. HARD LIMITS: escalate to building-a-slice (a full epic) if the change adds a new dependency, creates a new public API/endpoint, or changes domain logic or the data model/invariants. The epic stays the unit for product construction; this lane is out-of-band maintenance only.
+---
+
+# Micro-change (mantenimiento) — carril ligero
+
+Carril para **mantenimiento que no es construcción de producto nueva**. Espeja la filosofía del
+arnés: la épica es la unidad de **construcción**, pero un typo o un bump de dependencia **no son
+construcción** — forzarlos por las 8 fases de `building-a-slice` es ceremonia desproporcionada. Este
+carril les da una vía corta **sin** diluir los guardarraíles deterministas.
+
+> **Si una regla aquí contradice la metodología Trycore (`METODOLOGIA.md`), gana la metodología.**
+
+## Paso 0 · Decision gate (obligatorio) — ¿es esto un micro-change?
+
+Un cambio califica como micro-change **solo si cumple TODO**:
+
+- **No añade capacidad de producto nueva.** Corrige, ajusta o mantiene algo que ya existe.
+- **Alcance acotado:** pocas líneas / una sola preocupación. No toca múltiples módulos a la vez.
+- **Proyecto en fase `active`** (el scaffold runnable ya existe y está confirmado). El carril **no**
+  es para arrancar proyectos (eso es la Fase 0 de `building-a-slice`).
+
+Ejemplos típicos (neutros): corregir un typo o un texto visible; ajustar un valor de configuración;
+actualizar la versión de una dependencia **ya presente en la allowlist**; cambios de docs; un fix de
+una a pocas líneas que repara un comportamiento sin introducir nada nuevo.
+
+### Límites DUROS — si el cambio cruza **cualquiera**, STOP: esto es una épica
+
+Escala a `building-a-slice` (abre una épica `EP-XXX` con su DoR) si el cambio:
+
+1. **Añade una dependencia nueva** (fuera de `stack-allowlist.json`). *Lo bloquea además
+   `stack-guard.sh` de forma determinista.*
+2. **Crea un endpoint o una API pública nueva.**
+3. **Cambia lógica de dominio** o el **modelo/invariantes de datos**.
+4. **Desborda el alcance acotado** (introduce capacidad, toca muchos archivos, mezcla preocupaciones).
+
+Ante la duda, **es una épica**. El carril micro-change nunca es un atajo para esquivar gates de
+producto.
+
+## Pipeline ligero
+
+1. **Rama tipada.** Crea `fix/<slug>` (corrección) o `chore/<slug>` (infra/config/docs/bump).
+   `gitflow-guard.sh` ya exige rama tipada y prohíbe commit/push directo a `main`.
+2. **Aplica el cambio acotado.** Mantente dentro de los límites duros. Si al implementar descubres
+   que cruzas uno, **detente y escala** a `building-a-slice`.
+3. **Test de regresión — solo si cambia comportamiento.** Si el micro-change repara un bug,
+   añade/ajusta un test que falle antes y pase después (red→green del fix, delega en
+   `superpowers:test-driven-development`). Para cambios **no conductuales** (typo en copy, docs,
+   config) **no** se exige test.
+4. **PR a `main`.** Abre el Pull Request (`gitflow-guard.sh` impide la integración por push directo).
+   En la descripción del PR indica que es un micro-change y por qué califica (qué límite NO cruza).
+
+## Qué se mantiene y qué se salta
+
+| Se mantiene (gratis, vía hooks deterministas) | Se salta (por diseño) |
+|---|---|
+| `gitflow-guard` (rama tipada + PR) | DoR formal (escenarios G/W/T, INVEST) |
+| `stack-guard` (no dependencia nueva) | OpenSpec change + bloque `## Trazabilidad` |
+| `lint-typecheck` (estilo + typecheck incremental) | `journey_smoke`, `api`, `data`, DoD reducido |
+| | Apertura de `active_slice` / decisión de Release Gate |
+
+`scaffold-guard` no aplica: no hay slice activo y el carril exige proyecto en fase `active` (scaffold
+ya confirmado).
+
+## Estado y trazabilidad
+
+El micro-change **no escribe** `build-state.json` — es mantenimiento fuera de banda, trazado por el
+historial de git y el PR. No entra a `history[]`, así que `reflect-nudge.sh` **no** sugiere
+reflexionar por él (no hay aprendizaje de épica que capturar en un typo).
+
+## Reglas duras
+
+- **El decision gate es obligatorio.** Si dudas si algo es micro-change o épica, **es épica**.
+- **Límites duros = STOP, no excepción.** Cruzar un límite obliga a escalar a `building-a-slice`;
+  jamás se "fuerza" un micro-change para evitar el DoR.
+- **Integración solo por PR** a `main` (lo respalda `gitflow-guard.sh`).
+- Si una regla aquí contradice `METODOLOGIA.md`, **gana la metodología**.

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

@@ -14,6 +14,12 @@ el avance en el estado.
 > rama = un PR. Las HU de la épica (que siguen viviendo en `docs/04-historias/`) son el **alcance
 > interno** del change y se listan en `active_slice.hus[]`. Construir por HU suelta es sobre-ingeniería.
 
+> **¿Mantenimiento, no producto nuevo?** Un typo, un bump de dependencia ya permitida, un ajuste de
+> copy/config/docs o un fix de pocas líneas **sin nueva capacidad** NO abren una épica: usa la skill
+> **`building-a-micro-change`** (carril ligero `fix/*`|`chore/*` → cambio → PR). Si ese micro-change
+> cruza un **límite duro** (dependencia nueva, API/endpoint nuevo, lógica de dominio o datos), escala
+> **aquí** y ábrelo como épica.
+
 ## Principio de operación
 - **Una sola fuente de verdad**: `.claude/state/build-state.json` (schema + protocolo en
   `.claude/state/README.md`). Lee antes de actuar; escribe una vez por transición.
@@ -50,6 +56,21 @@ camina* se construye **encima** del scaffold ya existente.
 3. El gate lo valida también el `dor-dod-gatekeeper` (criterio duro de DoR) y lo respalda el hook
    determinista `scaffold-guard.sh` (bloquea escribir código de slice sin scaffold confirmado).
 
+## Fase 0-bis · Fuente de diseño (seguro para slices con UI)
+
+Espejo de la Fase 0, para proyectos **con UI**. Antes de abrir el primer slice con UI:
+1. Lee `design_source` en `build-state.json`.
+   - `applies` indeterminado (ausente) → pregunta *"¿este proyecto tiene UI?"* y fija `applies`.
+   - `applies === false` → N/A, salta esta fase.
+   - `confirmed === true` → continúa.
+2. `applies===true && confirmed===false` → **pregunta explícita** (AskUserQuestion): *"¿Existe una
+   fuente de diseño declarada (prototipo/export) para la UI de este proyecto?"*
+   - **No** → **STOP**. Indica declararla (ruta/URL del prototipo o export). El arnés **NO la genera**.
+     No abras el slice con UI.
+   - **Sí** → registra `design_source.source`, `confirmed=true`, `confirmed_by`, `confirmed_at`, `notes`.
+3. Lo respalda el hook determinista `design-source-guard.sh` (bloquea código de slice UI sin fuente
+   confirmada) y lo valida el `dor-dod-gatekeeper` (criterio duro de DoR).
+
 ## Pipeline — inner loop (carga la referencia indicada en cada paso)
 
 | Fase | Acción | Delega en | Gate | Referencia |
@@ -57,7 +78,7 @@ camina* se construye **encima** del scaffold ya existente.
 | 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 | skill `verify` / `run` (+ MCP chrome-devtools) | `journey_smoke` | `mcp-map.md` |
+| 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` |
 | 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` |
 | 7 · pr | Abrir PR + archivar change en el mismo PR | `opsx:archive`, `opsx:sync` | — | `gitflow.md` |
@@ -67,6 +88,10 @@ 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.
+
 MCP/LSP por gate: ver `references/mcp-map.md`. Protocolo de estado: `references/state-protocol.md`.
 
 ## Fase 8 · ¿Release Gate ahora? (default computado, humano decide)

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

@@ -11,6 +11,10 @@ pesadas (seguridad, diseño, UX, coherencia triple, arquitectura, integración)
 - [ ] **`coherence_link`** — `change-epic-coherence` confirma el enlace change↔épica (bloque `## Trazabilidad`, `openspec validate` ok). Es el chequeo **barato**; la trazabilidad triple completa va al Release Gate.
 - [ ] **`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).
 - [ ] **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

@@ -6,12 +6,15 @@ la épica; lo de abajo aplica a la épica y a **cada HU** que cubre (`hus[]`). L
 - [ ] **Épica válida**: `EP-XXX` existe en `docs/03-backlog/epicas.md` con trazabilidad a objetivos del PRD.
 - [ ] **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: 3–5 escenarios, con **happy + error + edge** (regla dura Trycore).
+- [ ] **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.
 - [ ] **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
+  (el `DESIGN_SOURCE` del dominio) está declarada y confirmada (`design_source.confirmed`), y este
+  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` (`ux`/`api` en `null` si la épica no toca UI/endpoints).
+`phase: dor`, `gates.dor: true` y el resto en `false` (`fidelity`/`api` en `null` si la épica no toca UI/endpoints).
 **Si algo ✗** → no se abre el slice; se reporta qué falta y se vuelve a discovery (Trycore).

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

@@ -16,7 +16,9 @@ gh pr create --base main --head feature/<slug> --fill   # integración por PR
 
 ## Convenciones
 - **Rama**: `feature/<slug-kebab>` (nuevo valor), `fix/<slug>` (corrección), `chore/<slug>` (infra/docs).
-  Una rama por **épica** (= un slice): `feature/ep-003-pricing-engine`.
+  Una rama por **épica** (= un slice): `feature/ep-003-pricing-engine`. Las ramas `fix/*` y `chore/*`
+  son también el carril de la skill `building-a-micro-change` (mantenimiento que no es producto nuevo:
+  va a PR sin abrir épica ni `active_slice`; ver sus límites duros).
 - **Commits**: Conventional Commits (`feat:`, `fix:`, `test:`, `refactor:`, `chore:`, `docs:`).
 - **PR**: título claro, descripción enlazando la épica, sus HU (`hus[]`) y el OpenSpec change; checks
   (lint, types, tests, newman) en verde antes de merge; squash recomendado.

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

@@ -15,6 +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). |
 | `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. |

package/state/README.md

@@ -51,6 +51,26 @@ Arranca en `confirmed: false` y **solo** pasa a `true` por **confirmación expl
 restrictiva para abrir cualquier slice: el hook `scaffold-guard.sh` bloquea escribir código de
 slice (fases `red…data`) mientras `confirmed` no sea `true`. El arnés **no genera** el scaffold.
 
+### `design_source` (gate de proyecto, slices con UI)
+
+Espejo de `scaffold` para la UI: `applies` (¿el proyecto tiene UI?), `confirmed` (humano confirmó que
+existe una fuente de diseño declarada), `source` (puntero al prototipo/export). El arnés NO genera el
+prototipo. Lo respalda `design-source-guard.sh`.
+
+### gate `fidelity` (por-slice, inner loop)
+
+`true` = FIEL (o desviaciones justificadas); `false` = desviaciones sin justificar; `null` = slice sin
+UI. Lo computa `ux-fidelity-reviewer` en la fase `smoke` y lo escribe el `build-orchestrator`.
+
+### Reflexión post-slice (ciclo autocorrectivo)
+
+Tras archivar un slice, su entrada en `history[]` puede llevar `reflected` / `reflected_at`. El
+hook `reflect-nudge.sh` (evento `Stop`, **no bloqueante**) sugiere ejecutar `/build:reflect` mientras
+exista al menos una entrada con `reflected != true`. `/build:reflect` lo ejecuta el **modelo**:
+detecta convención nueva o error recurrente, **propone** un parche al bloque `trycore-build-learnings`
+de `CLAUDE.md` (se aplica **solo tras tu aprobación**) y estampa `reflected: true` → el nudge calla.
+El razonamiento vive en el modelo; el hook solo es un recordatorio determinista.
+
 ## Quién escribe qué
 
 | Campo / gate | Lo escribe | Cadencia |
@@ -62,4 +82,5 @@ slice (fases `red…data`) mientras `confirmed` no sea `true`. El arnés **no ge
 | `gates.api` | `api-contract-tester` | slice |
 | `gates.data` | `data-consistency-checker` | slice |
 | `releases[]` (`security`, `smell`, `ux`, `coherence`, `stack_arch`, `integration`, `status`) | `releasing-a-version` (delega en `security-reviewer`, `simple-design-reviewer`, `ux-krug-reviewer`, `coherence-three-way`, `stack-guardian`) | release |
+| `history[].reflected` · `history[].reflected_at` | `/build:reflect` | post-slice (tras archivar) |
 | `harness_phase` | `load-build-state.sh` (SessionStart) | — |

package/state/build-state.schema.json

@@ -14,6 +14,7 @@
       "description": "Señal INFORMATIVA auto-detectada: authoring = aún no hay package.json; active = scaffold de código presente. El gate de avance es `scaffold.confirmed`, NO esta señal."
     },
     "scaffold": { "$ref": "#/$defs/scaffold" },
+    "design_source": { "$ref": "#/$defs/design_source" },
     "active_slice": {
       "description": "El slice (épica) en construcción. null si no hay ninguno activo.",
       "oneOf": [
@@ -45,6 +46,20 @@
         "notes": { "type": "string", "description": "Evidencia libre (p.ej. 'build/dev arranca vacío sin error')." }
       }
     },
+    "design_source": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Gate de PROYECTO para slices con UI: existe una fuente de diseño declarada (prototipo/export). Espejo de scaffold: confirmed pasa a true SOLO por confirmación humana, nunca por auto-detección. El arnés NO genera el prototipo. applies=false apaga todo el mecanismo (proyecto sin UI).",
+      "required": ["applies", "confirmed"],
+      "properties": {
+        "applies": { "type": "boolean", "description": "¿el proyecto tiene UI / hay diseño que respetar? false → mecanismo N/A." },
+        "confirmed": { "type": "boolean", "description": "true solo tras confirmación humana de que existe una fuente de diseño declarada." },
+        "confirmed_by": { "type": ["string", "null"], "description": "Agente/skill que registró la confirmación." },
+        "confirmed_at": { "type": ["string", "null"], "format": "date-time" },
+        "source": { "type": "string", "description": "Puntero a la fuente: ruta/URL del prototipo o export (el DESIGN_SOURCE del dominio)." },
+        "notes": { "type": "string", "description": "Evidencia libre (p.ej. 'prototipo en docs/… revisado y vigente')." }
+      }
+    },
     "slice": {
       "type": "object",
       "additionalProperties": false,
@@ -75,6 +90,7 @@
             "journey_smoke": { "type": "boolean", "description": "El backbone-hasta-aquí camina end-to-end (verificado con la skill verify/run)." },
             "coherence_link": { "type": "boolean", "description": "Enlace change↔épica válido (change-epic-coherence, barato, por slice)." },
             "data": { "type": "boolean" },
+            "fidelity": { "type": ["boolean", "null"], "description": "Gate VIVO de inner loop (slices con UI): fidelidad visual a la fuente de diseño declarada, computado en fase smoke por ux-fidelity-reviewer. true = FIEL (o DESVIACIONES justificadas); false = DESVIACIONES sin justificar; null = N/A (slice sin UI). NO es legado (los legados viven en releases[])." },
             "api": { "type": ["boolean", "null"], "description": "null = N/A (slice sin endpoints)." },
             "ux": { "type": ["boolean", "null"], "description": "null = N/A (slice sin UI). Legado: hoy se audita en releases[]." },
             "stack": { "type": "boolean", "description": "Legado por-slice; deps las cubre el hook stack-guard.sh, la arquitectura se audita en releases[]." },
@@ -86,7 +102,9 @@
         },
         "updated_at": { "type": "string", "format": "date-time" },
         "updated_by": { "type": "string", "description": "Agente o hook que escribió el estado." },
-        "notes": { "type": "string", "description": "Nota libre opcional (p.ej. changes/branches adicionales de una épica construida en varios pasos)." }
+        "notes": { "type": "string", "description": "Nota libre opcional (p.ej. changes/branches adicionales de una épica construida en varios pasos)." },
+        "reflected": { "type": "boolean", "description": "True si /build:reflect ya capturó los aprendizajes de este slice archivado (ciclo autocorrectivo). Mientras sea false/ausente, reflect-nudge.sh sugiere reflexionar al cerrar sesión." },
+        "reflected_at": { "type": "string", "format": "date-time", "description": "Cuándo se reflexionó (ISO-8601 UTC). Lo escribe /build:reflect." }
       }
     },
     "release": {

package/state/build-state.template.json

@@ -7,6 +7,14 @@
     "confirmed_at": null,
     "notes": ""
   },
+  "design_source": {
+    "applies": false,
+    "confirmed": false,
+    "confirmed_by": null,
+    "confirmed_at": null,
+    "source": "",
+    "notes": ""
+  },
   "active_slice": null,
   "history": [],
   "releases": []

package/templates/CLAUDE.md.template

@@ -35,7 +35,7 @@ Outer loop (por release):       Release Gate (seguridad · diseño · UX · cohe
 ### Bloque de dominio (lo resuelve `/build:onboard`)
 
 Estos puntos de extensión los leen los agentes `security-reviewer`, `stack-guardian`,
-`data-consistency-checker`, `ux-krug-reviewer` y `simple-design-reviewer`:
+`data-consistency-checker`, `ux-krug-reviewer`, `simple-design-reviewer` y `ux-fidelity-reviewer`:
 
 - **PRD técnico (fuente del stack)**: {{PRD_TECH_PATH}}
 - **Capa de servicios externos / IA (frontera)**: {{EXTERNAL_SERVICE_LAYER}}
@@ -43,6 +43,7 @@ Estos puntos de extensión los leen los agentes `security-reviewer`, `stack-guar
 - **Categorías de datos sensibles / PII reguladas**: {{SENSITIVE_DATA_CATEGORIES}}
 - **Secretos server-side**: {{SERVER_SIDE_SECRETS}}
 - **Decisiones de alto impacto que exigen explicabilidad UX**: {{HIGH_STAKES_DECISIONS}}
+- **Fuente de diseño / referencia visual**: {{DESIGN_SOURCE}}
 
 (Si aparecen como `{{...}}`, ejecuta `/build:onboard` para parametrizarlos.)
 
@@ -54,4 +55,10 @@ Estos puntos de extensión los leen los agentes `security-reviewer`, `stack-guar
 
 <!-- END trycore-build-harness -->
 
+<!-- BEGIN trycore-build-learnings -->
+## Convenciones aprendidas (mantenido por /build:reflect)
+
+<!-- /build:reflect propone aquí viñetas concretas (convención nueva o error recurrente) tras cerrar un slice; se agregan SOLO con tu aprobación. Revísalas en PR como cualquier cambio de equipo. -->
+<!-- END trycore-build-learnings -->
+
 <!-- A partir de aquí, el equipo del proyecto puede agregar instrucciones específicas del cliente. -->

package/templates/settings-hooks.template.json

@@ -13,7 +13,7 @@
     ],
     "PreToolUse": [
       { "matcher": "Bash", "hooks": [ { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/gitflow-guard.sh\"" } ] },
-      { "matcher": "Write|Edit|MultiEdit", "hooks": [ { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/stack-guard.sh\"" }, { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/scaffold-guard.sh\"" } ] }
+      { "matcher": "Write|Edit|MultiEdit", "hooks": [ { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/stack-guard.sh\"" }, { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/scaffold-guard.sh\"" }, { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/design-source-guard.sh\"" } ] }
     ],
     "PostToolUse": [
       { "matcher": "Write|Edit|MultiEdit", "hooks": [ { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/lint-typecheck.sh\"" }, { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/coherence-flag.sh\"" } ] }

package/docs/superpowers/specs/2026-06-02-scaffold-gate-design.md

@@ -1,87 +0,0 @@
-# Diseño: Scaffold como Paso 1 fundamental (scaffold gate)
-
-Fecha: 2026-06-02 · Target: `@trycore/spec-build-harness` v0.2.0 · Estado: aprobado (diseño)
-
-## Contexto y problema
-
-Hoy el arnés es **permisivo** respecto al scaffold del proyecto (el esqueleto runnable: `package.json` + framework que arranca vacío). Lo trata como un evento implícito: `harness_phase` pasa de `authoring` a `active` cuando `load-build-state.sh` detecta `package.json`, y los gates de código "no se cierran" en `authoring`, pero nada **exige ni bloquea** explícitamente. La decisión del usuario:
-
-> Es requerido que exista un scaffold. **No lo forcemos** (el arnés NO lo genera — sigue agnóstico al stack), **pero nuestro setup debe ser restrictivo para avanzar**. Es el **Paso 1 fundamental**. Y debe **preguntarse explícitamente** (no inferirse en silencio de `package.json`).
-
-Objetivo: convertir "scaffold presente" en una **precondición explícita y restrictiva** — confirmada por el equipo, registrada en el estado, y respaldada por un bloqueo determinista — sin que el arnés genere el scaffold.
-
-## Decisiones tomadas (brainstorming)
-
-1. **Condición = confirmación explícita**, no inferencia silenciosa de `package.json`.
-2. **Enforcement = skill/agente (Fase 0 de DoR) + gate en estado + hook determinista de respaldo.**
-3. **Regla del hook = Enfoque A (por estado/fase):** bloquea solo cuando un slice está en fase de código sin el scaffold confirmado; permite crear el scaffold (fases `dor`/`change` o sin slice).
-4. **No se genera el scaffold.** El arnés exige, bloquea e instruye; el equipo lo crea (guiado por `stack-allowlist.json`/PRD).
-
-## Diseño
-
-### 1. Estado (`state/build-state.json` + `build-state.schema.json`)
-Nuevo gate **a nivel proyecto** (no por-slice), explícito, default cerrado:
-
-```jsonc
-"scaffold": {
-  "confirmed": false,
-  "confirmed_by": null,      // agente/skill que confirmó
-  "confirmed_at": null,      // ISO 8601 UTC
-  "notes": ""                // ej. "Next.js app arranca vacía; npm run dev ok"
-}
-```
-
-- Top-level, junto a `harness_phase`/`active_slice`/`history`/`releases`.
-- `harness_phase` (authoring/active) se mantiene como señal **informativa** auto-detectada; el **gate de avance** es `scaffold.confirmed`.
-- Solo pasa a `true` por **confirmación explícita** (nunca auto). Una transición = una escritura, con `confirmed_by`/`confirmed_at` (protocolo de `state/README.md`).
-- Schema: `scaffold` se añade a `properties` y a `required` del objeto raíz; `build-state.template.json` lo incluye con `confirmed:false`.
-
-### 2. Skill `building-a-slice` — Fase 0 (precondición de DoR)
-Antes de abrir cualquier slice:
-- Si `scaffold.confirmed` ya es `true` → continúa al DoR normal.
-- Si es `false` → **pregunta explícitamente** (AskUserQuestion): *"¿Existe un scaffold runnable del proyecto (arranca vacío: build/dev corre sin error)?"*
-  - **No** → **STOP**. Instruye crearlo según `stack-allowlist.json#source` (PRD) y el stack permitido; **no lo genera**. No abre el slice.
-  - **Sí** → registra `scaffold.confirmed=true` (con `confirmed_by`, `confirmed_at`, `notes`) y continúa.
-- Documenta la relación con el walking skeleton (ver §5).
-
-### 3. Agente `dor-dod-gatekeeper`
-Añade **"scaffold confirmado"** como criterio **duro** de DoR (primer ítem). No deja pasar a fases de código sin `scaffold.confirmed=true`. Es el dueño de escribir el gate cuando valida el DoR.
-
-### 4. Hook determinista `hooks/build/scaffold-guard.sh` (PreToolUse · Write|Edit) — Enfoque A
-Backstop ineludible si el agente se salta la Fase 0:
-- Resuelve `ROOT` por `git rev-parse --show-toplevel` (+ fallback `${CLAUDE_PROJECT_DIR}`); lee `$ROOT/.claude/state/build-state.json`.
-- Guarda python3 fail-closed dirigida (igual patrón que `stack-guard.sh`).
-- **Regla de bloqueo:** si `active_slice` existe y `active_slice.phase ∈ {red, green, refactor, smoke, api, data}` **y** `scaffold.confirmed != true` → **exit 2** con mensaje: *"⛔ scaffold-guard: confirma el scaffold (Paso 1) antes de escribir código de slice. Ver building-a-slice / DoR."* En cualquier otro caso (sin slice, o fase `dor`/`change`) → exit 0 (permite crear el scaffold y planificar).
-- Auto-arme: si no existe `build-state.json` → exit 0.
-
-### 5. Metodología (`METODOLOGIA.md`) — clarificación walking skeleton
-- **Paso 1 — Scaffold (precondición, NO generada por el arnés):** esqueleto runnable mínimo del proyecto (build/dev arranca vacío). El equipo lo crea, guiado por el stack del PRD/allowlist; el arnés lo **exige, lo pregunta explícitamente y lo bloquea** hasta confirmarlo.
-- **Primer slice — Walking skeleton:** sobre el scaffold confirmado, construye el journey end-to-end más delgado. El scaffold (shell vacío) precede al walking skeleton (primer journey real delgado).
-
-### 6. Wiring de canales y CLI
-- `src/lib/settings-merge.ts`: añade `scaffold-guard.sh` al `HOOK_SPECS` (PreToolUse · `Write|Edit|MultiEdit`), misma cadena única.
-- `hooks/build-harness.json`: añade la misma entrada (canal plugin).
-- `src/commands/doctor.ts` y `status.ts`: reportan `scaffold: ✓ confirmado / ✗ pendiente` leyendo el estado.
-- `state/README.md`: documenta el gate `scaffold` y su protocolo de confirmación.
-
-### 7. Versión
-`0.1.0 → 0.2.0` (feature). Sincronizar `VERSION` / `package.json` / `.claude-plugin/plugin.json`. Incluye el fix pendiente de `state/README.md` ("scaffold Next.js" → "scaffold de código del proyecto"). Entrada en `CHANGELOG.md`. Nota de cadencia/uso en `GOVERNANCE.md` si aplica.
-
-## Casos borde
-- **Scaffold ya existe al instalar** (proyecto brownfield): la Fase 0 pregunta igual; el usuario confirma `Sí` una vez y queda registrado. No se re-pregunta mientras `scaffold.confirmed=true`.
-- **El equipo crea el scaffold dentro de un slice ya abierto**: desaconsejado por diseño (scaffold es Paso 1, antes del primer slice); el hook bloquea fases de código hasta confirmar. La creación del scaffold debe ocurrir con `active_slice=null` o en `dor`/`change`.
-- **Regresión de scaffold** (alguien borra package.json): `harness_phase` volvería a `authoring` (informativo); `scaffold.confirmed` sigue `true` salvo que se resetee manualmente. Aceptable para v0.2.0; documentar que el gate es una confirmación, no un chequeo continuo.
-- **python3 ausente**: el hook bloquea dirigido (no puede leer el estado de forma fiable) con mensaje claro, consistente con los otros hooks.
-
-## Verificación (end-to-end)
-1. `tsc` build limpio; `check-version-sync` (0.2.0 en los 3) / `check-agnostic` / `check-state-clean` en verde.
-2. `build-state.template.json` incluye `scaffold.confirmed=false`; el schema valida.
-3. Instalación en repo temporal: `scaffold-guard.sh` instalado y ejecutable; `settings.json` y `build-harness.json` contienen su entrada con la cadena única (sin doble disparo).
-4. Test del hook por estado: con un `build-state.json` que tenga `active_slice.phase="green"` y `scaffold.confirmed=false`, un `Write` simulado → exit 2; con `scaffold.confirmed=true` → exit 0; con `active_slice=null` → exit 0.
-5. `doctor`/`status` reportan el estado del scaffold.
-6. Lectura de `building-a-slice`/`dor-dod-gatekeeper`: el ask de Fase 0 y el criterio duro están presentes y son agnósticos (pasa `check-agnostic`).
-
-## Fuera de alcance
-- Generar el scaffold (decisión explícita: no lo forzamos).
-- Chequeo continuo de salud del scaffold (es una confirmación puntual, no un monitor).
-- Cambiar el modelo `harness_phase` (se mantiene como señal informativa).