@trycore/spec-build-harness 0.8.3 → 0.8.5

package/docs/hooks.md

@@ -93,7 +93,7 @@ Cierra el **ciclo autocorrectivo**. Al terminar el turno, si en `history[]` hay
 
 ### 9. `design-source-guard.sh` — `PreToolUse` · Write/Edit/MultiEdit · **bloqueante** (desde v0.5.0)
 
-Refuerza el **seguro de fuente de diseño** (espejo de `scaffold-guard`, para slices con UI). Bloquea con `exit 2` la escritura de **código de un slice con UI** —cuando `active_slice.phase` ∈ `red`/`green`/`refactor`/`smoke`/`api`/`data` **y** `active_slice.gates.fidelity === false` (marcado UI-pendiente por la DoR)— mientras el proyecto tenga UI (`design_source.applies === true`) y `design_source.confirmed` no sea `true`. **Permite** todo lo demás: slices sin UI (`gates.fidelity === null` o ausente), proyectos sin UI (`applies !== true`), fases de planificación (`dor`/`change`), o fuente ya confirmada. El arnés **exige** la fuente de diseño pero **no genera** el prototipo; la confirmación es **explícita** (vía `building-a-slice` Fase 0-bis / `dor-dod-gatekeeper`), nunca auto-detectada. Guarda `python3` fail-closed dirigido. En la práctica, como `design_source` es gate de proyecto, solo muerde la **primera** construcción de UI sin fuente declarada.
+Refuerza el **seguro de fuente de diseño** (espejo de `scaffold-guard`, para slices con UI). Bloquea con `exit 2` la escritura de **código de un slice con UI** —cuando `active_slice.phase` ∈ `red`/`green`/`refactor`/`smoke`/`api`/`data` **y** `active_slice.gates.fidelity === false` (marcado UI-pendiente por la DoR)— mientras el proyecto tenga UI (`design_source.applies === true`) y `design_source.confirmed` no sea `true`. **Permite** todo lo demás: slices sin UI (`gates.fidelity === null` o ausente), proyectos sin UI (`applies !== true`), fases de planificación (`dor`/`change`), o fuente ya confirmada. El arnés **exige** la fuente de diseño y puede **generarla** vía `/build:prototype` (skill `prototyping-screens`; el mensaje de bloqueo lo sugiere); la confirmación sigue siendo **explícita y humana** (vía `building-a-slice` Fase 0-bis / `dor-dod-gatekeeper`), nunca auto-detectada. Guarda `python3` fail-closed dirigido. En la práctica, como `design_source` es gate de proyecto, solo muerde la **primera** construcción de UI sin fuente declarada.
 
 ### 10. `release-gate-nudge.sh` — `Stop` · no bloqueante (desde v0.7.0)
 

package/hooks/build/design-source-guard.sh

@@ -46,7 +46,7 @@ PY
 if [ "$VERDICT" = "BLOCK" ]; then
   echo "⛔ design-source-guard: el slice con UI está en fase de código pero la fuente de diseño NO está confirmada." >&2
   echo "   Declara y confirma primero el DESIGN_SOURCE del proyecto (ver building-a-slice Fase 0-bis / DoR)." >&2
-  echo "   El arnés NO genera el prototipo: declara la fuente (prototipo/export) y confírmala." >&2
+  echo "   Genera el prototipo con /build:prototype o declara una fuente existente (prototipo/export), y confírmala." >&2
   exit 2
 fi
 exit 0

package/package.json

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

package/scripts/tests/test-install.sh

@@ -86,4 +86,92 @@ check "hooks/build/reconcile-build-state.py"
 check "hooks/build/lib/state-io.sh"
 check "scripts/lib/front-plan.py"
 
+# project_kind: el TMP de init es un directorio vacío → greenfield detectado (auto)
+if python3 -c "
+import json,sys
+d=json.load(open('$TMP/.claude/state/build-state.json'))
+assert d.get('project_kind')=='greenfield', d.get('project_kind')
+assert d.get('project_kind_source')=='auto', d.get('project_kind_source')
+" 2>/dev/null; then
+  echo "OK install: project_kind=greenfield detectado (auto)"
+else
+  echo "FAIL install: project_kind no detectado como greenfield/auto"
+  fail=1
+fi
+
+# 5) Brownfield seguro: manifiesto + código + historial git que toca código.
+TMP_BF="$(mktemp -d)"
+echo '{}' > "$TMP_BF/package.json"
+mkdir -p "$TMP_BF/src"
+echo 'export const x = 1;' > "$TMP_BF/src/index.ts"
+(
+  cd "$TMP_BF" &&
+  git init -q &&
+  git add -A &&
+  git -c user.email=t@t -c user.name=t commit -qm x
+) >/dev/null 2>&1
+
+node "$ROOT/dist/cli.js" init "$TMP_BF" \
+  --copy \
+  --skip-doctor \
+  --yes \
+  --stack "" \
+  --pkg-manager npm \
+  --runtime ">=18.18" \
+  --prd-path "docs/01-prd/x.md#req" \
+  >"$TMP_BF/.init.log" 2>&1
+rc=$?
+if [ $rc -ne 0 ]; then
+  echo "FAIL install: \`trycore-build init\` (brownfield) salió con código $rc"
+  cat "$TMP_BF/.init.log"
+  fail=1
+fi
+
+if python3 -c "
+import json,sys
+d=json.load(open('$TMP_BF/.claude/state/build-state.json'))
+assert d.get('project_kind')=='brownfield', d.get('project_kind')
+assert d.get('project_kind_source')=='auto', d.get('project_kind_source')
+" 2>/dev/null; then
+  echo "OK install: project_kind=brownfield con historial git"
+else
+  echo "FAIL install: project_kind no detectado como brownfield con historial git"
+  fail=1
+fi
+rm -rf "$TMP_BF"
+
+# 6) Ambiguo: manifiesto + código pero SIN repo git (sin historial) → project_kind null.
+TMP_AMB="$(mktemp -d)"
+echo '{}' > "$TMP_AMB/package.json"
+mkdir -p "$TMP_AMB/src"
+echo 'export const x = 1;' > "$TMP_AMB/src/index.ts"
+
+node "$ROOT/dist/cli.js" init "$TMP_AMB" \
+  --copy \
+  --skip-doctor \
+  --yes \
+  --stack "" \
+  --pkg-manager npm \
+  --runtime ">=18.18" \
+  --prd-path "docs/01-prd/x.md#req" \
+  >"$TMP_AMB/.init.log" 2>&1
+rc=$?
+if [ $rc -ne 0 ]; then
+  echo "FAIL install: \`trycore-build init\` (ambiguo) salió con código $rc"
+  cat "$TMP_AMB/.init.log"
+  fail=1
+fi
+
+if python3 -c "
+import json,sys
+d=json.load(open('$TMP_AMB/.claude/state/build-state.json'))
+assert d.get('project_kind') is None, d.get('project_kind')
+" 2>/dev/null; then
+  echo "OK install: project_kind=null (ambiguo sin historial git)"
+else
+  echo "FAIL install: project_kind no quedó null en caso ambiguo"
+  fail=1
+fi
+rm -rf "$TMP_AMB"
+
 exit $fail

package/scripts/tests/test-schema.sh

@@ -43,8 +43,29 @@ cat > "$TMP/bad-layer.json" <<'JSON'
    "layer":"WRONG","gates":{"dor":true,"tdd":false,"dod":false},"updated_at":"2026-07-03T00:00:00Z","updated_by":"t"},
  "history":[],"releases":[]}
 JSON
+cat > "$TMP/valid-foundation.json" <<'JSON'
+{"version":"1.0","harness_phase":"authoring","scaffold":{"confirmed":false},
+ "project_kind":"greenfield","project_kind_source":"auto",
+ "foundation":{"required":true,"epic":"EP-001","completed_at":null,
+   "checklist":[{"item":"navegacion-menus","applies":true,"evidence":""},
+                {"item":"login-authn","applies":true,"evidence":"smoke login OK"}]},
+ "active_slice":null,"history":[],"releases":[]}
+JSON
+cat > "$TMP/bad-project-kind.json" <<'JSON'
+{"version":"1.0","harness_phase":"authoring","scaffold":{"confirmed":false},
+ "project_kind":"unknown","active_slice":null,"history":[],"releases":[]}
+JSON
+cat > "$TMP/bad-foundation-item.json" <<'JSON'
+{"version":"1.0","harness_phase":"authoring","scaffold":{"confirmed":false},
+ "foundation":{"required":true,"epic":null,"completed_at":null,
+   "checklist":[{"applies":true}]},
+ "active_slice":null,"history":[],"releases":[]}
+JSON
 check "estado válido con campos nuevos" pass "$TMP/valid.json"
 check "layer inválido rechazado" fail "$TMP/bad-layer.json"
+check "foundation + project_kind válidos" pass "$TMP/valid-foundation.json"
+check "project_kind inválido rechazado" fail "$TMP/bad-project-kind.json"
+check "checklist item sin 'item' rechazado" fail "$TMP/bad-foundation-item.json"
 
 CFG="$ROOT/config/build-config.template.json"
 if [ -f "$CFG" ] && python3 -c "import json,sys; d=json.load(open('$CFG'))['context']; assert d['warning_pct']==35 and d['critical_pct']==25 and d['auto_checkpoint'] is False" 2>/dev/null; then

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

@@ -105,8 +105,9 @@ Espejo de la Fase 0, para proyectos **con UI**. Antes de abrir el primer slice c
    - `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.
+   - **No** → **STOP**. Ofrece dos salidas: **generarla con `/build:prototype`** (skill
+     `prototyping-screens`; la confirmación sigue siendo humana) o declarar una fuente externa
+     (ruta/URL del prototipo o export). No abras el slice con UI sin fuente confirmada.
    - **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).

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

@@ -10,6 +10,16 @@ la épica; lo de abajo aplica a la épica y a **cada HU** que cubre (`hus[]`). L
 - [ ] **INVEST** por HU: pasa los 6 criterios (Independent, Negotiable, Valuable, Estimable, Small, Testable).
 - [ ] **Dependencias resueltas**: las épicas/HU de las que depende están archivadas (`history[]`) o explícitamente no bloquean. **Excepción dura — cimiento:** si la dependencia es **infraestructura fundacional** (autenticación, acceso a datos, arquitectura base, design-system/componentes base), la cláusula "explícitamente no bloquean" **NO aplica**: debe estar **construida y archivada** antes (ver criterio "Cimiento construido").
 - [ ] **Cimiento construido (épicas de negocio)**: si esta épica es `layer: business`, todo el cimiento que arrastra (auth, acceso a datos, arquitectura base, design-system/componentes base) ya existe como épica(s) `layer: foundational` **archivada(s)** en `history[]`. Si arrastra cimiento no construido → **STOP**: extráelo a una épica fundacional previa y constrúyela primero. Las épicas fundacionales se priorizan **antes** que las de negocio.
+- [ ] **Caparazón construido (solo greenfield — gate PROACTIVO)**: si `project_kind === "greenfield"`
+  y `foundation.required === true` en `build-state.json`, ninguna épica `layer: business` entra a
+  construcción mientras la épica caparazón (`foundation.epic`) no esté **archivada con su checklist
+  evidenciada** (`foundation.completed_at` estampado). Las épicas `layer: foundational` (la
+  caparazón `foundation.epic` u otras fundacionales) sí pueden abrir. A diferencia de "Cimiento
+  construido" (reactivo: bloquea si *detecta* arrastre), este criterio bloquea **siempre** en
+  greenfield hasta que el cimiento exista archivado — no depende de detectar nada. Si
+  `foundation.epic` es `null` (no existe la épica caparazón aún) → **STOP**: se define en
+  `/build:onboard` Fase 2c o en discovery. Brownfield / `foundation.required: false` → **N/A** (no
+  bloquea). Contrato: `references/foundation-contract.md`.
 - [ ] **Tamaño acotado (gate de descomposición)**: si la épica supera el umbral —heurística por defecto **> 3 HU** ó **≥ 3 capas tocadas** (configurable por proyecto)— **no entra como slice único**: se descompone en `sub_slices[]` verificables construidos de a uno, con `journey_smoke` verde entre cada uno. El umbral es proporcional (no cuota rígida): una épica de 1 capa y pocas HU entra directa.
 - [ ] **Cabe en el stack** del PRD §7 (no requiere tecnología fuera de `stack-allowlist.json`).
 - [ ] **Cobertura arquitectónica (ADR)** *(opt-in, retrocompatible)*: si el proyecto adoptó la capa de
@@ -23,7 +33,10 @@ la épica; lo de abajo aplica a la épica y a **cada HU** que cubre (`hus[]`). L
 - [ ] **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.
+  slice apunta a la(s) pantalla(s) equivalente(s). Si la fuente es un prototipo generado
+  (`docs/05-prototipo/`), esas pantallas existen en `manifest.json` con `estado: "aprobada"`
+  (un `borrador` no satisface el criterio; genera/aprueba primero con `/build:prototype`).
+  No se construye UI fuera de la fuente declarada.
 - [ ] **Clasificación `layer`**: `foundational` (auth/datos/design-system/arquitectura base) | `business`. Se escribe en `active_slice.layer`. Gatea el front paralelo (foundational nunca en paralelo).
 - [ ] **`files_scope`**: globs de los archivos que la épica tocará (p.ej. `src/reports/**`). Fuente de la disjunción inter-épica. Se escribe en `active_slice.files_scope`.
 

package/skills/building-a-slice/references/foundation-contract.md

@@ -0,0 +1,44 @@
+# Contrato del caparazón (épica fundacional de app shell) — solo greenfield
+
+El **caparazón** es el shell con contenido donde aterrizan las features: navegación, layout,
+homepage, login y redirecciones. No es el *scaffold* (shell vacío que arranca — gate
+`scaffold.confirmed`) ni el *walking skeleton* (primer journey de negocio más delgado): es la
+infraestructura de UI/entrada fundacional que, si no existe primero, cada épica de negocio
+improvisa a pedazos y acumula deuda estructural.
+
+**Aplica si y solo si `project_kind === "greenfield"`.** En brownfield el mecanismo entero es
+N/A y el arnés no pregunta ni exige nada (`foundation.required: false`).
+
+## Checklist base (ids canónicos)
+
+| id | Qué cubre | Poda típica |
+|---|---|---|
+| `navegacion-menus` | Menús / estructura de navegación principal | API sin UI |
+| `layout-panel-central` | Layout base + panel/área central de contenido | API sin UI |
+| `homepage` | Página de inicio real (no placeholder del scaffold) | API sin UI |
+| `login-authn` | Login + autenticación cableada end-to-end | app pública sin cuentas |
+| `redirecciones-guards` | Redirecciones y guards de ruta (authed/anon, 404, deep-links) | API sin UI |
+
+- La **poda** se decide una vez, en `/build:onboard` Fase 2c, con el humano (ítem podado =
+  `applies: false`; queda en la checklist como decisión trazable, no se borra).
+- El proyecto puede **añadir** ítems propios (id kebab-case) si su caparazón exige más.
+
+## Ciclo de vida
+
+1. **Onboard (Fase 2c)** — se poda la checklist, se persiste en `foundation.checklist[]` y se
+   identifica (o redacta en borrador híbrido) la épica caparazón → `foundation.epic`.
+2. **DoR (gate proactivo)** — mientras la épica caparazón no esté **archivada**, ninguna épica
+   `layer: business` abre slice (solo fundacionales). Ver `dor.md`.
+3. **DoD de la épica caparazón** — cada ítem `applies: true` exige `evidence` de ejecución real
+   (test, comando, screenshot MCP), patrón `wiring_checklist`. Sin evidencia completa no se
+   archiva.
+4. **Cierre** — al archivar con la checklist evidenciada se estampa `foundation.completed_at` y
+   las épicas de negocio quedan desbloqueadas.
+
+## Reglas duras
+
+- El arnés **propone** el borrador de la épica caparazón; **solo** lo escribe en
+  `docs/03-backlog/epicas.md` con aprobación humana explícita (carve-out acotado, ver
+  METODOLOGIA §9.2). Si el humano rechaza, STOP: la épica se crea en discovery (`/trycore:*`).
+- La evidencia es de **ejecución**, nunca de inspección.
+- Si contradice `METODOLOGIA.md`, gana la metodología.

package/skills/prototyping-screens/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: prototyping-screens
+description: Use when generating or extending the HTML reference prototype (the DESIGN_SOURCE) — the visual source of truth screens are built against. Two modes — greenfield (full initial prototype from discovery docs + human-chosen aesthetic direction) and feature (new-epic screens extracted live from the already-implemented UI so they look native to the app). Self-verifies visually; human approval gates everything.
+---
+
+# Prototipar pantallas de referencia (outer-loop)
+
+Genera el **prototipo HTML de referencia** del consumidor: la fuente de verdad visual
+(`DESIGN_SOURCE`) contra la que después se construyen y verifican los slices con UI
+(gate `fidelity`, `ux-fidelity-reviewer`). Si algo aquí contradice `METODOLOGIA.md`,
+**gana la metodología**.
+
+**Invariantes:**
+- La skill **genera**; el humano **aprueba**. `design_source.confirmed` y el `estado: "aprobada"`
+  del manifest son **siempre** decisiones humanas — esta skill jamás los auto-marca.
+- Es **outer-loop**: se corre antes de abrir slices (como `/build:architect`), nunca dentro del
+  inner loop de una épica.
+- Escribe **solo** en `docs/05-prototipo/` (carve-out §9.2 de METODOLOGIA) y, con aprobación
+  humana, en `design_source` de `build-state.json` (protocolo de `state/README.md`).
+
+## Artefactos que produce (repo del consumidor)
+
+```
+docs/05-prototipo/
+├── DESIGN.md          ← tokens + reglas visuales en prosa (assets/DESIGN.md.template)
+├── tokens.css         ← los mismos tokens como CSS custom properties (fuente única)
+├── manifest.json      ← pantalla ↔ épica/HU ↔ archivo ↔ estado (assets/manifest.schema.json)
+└── pantallas/
+    └── <slug>.html    ← un HTML autocontenido por pantalla (assets/screen.template.html)
+```
+
+**Reglas duras del artefacto:**
+- HTML **autocontenido**: cero dependencias externas (sin CDNs, frameworks, fetch ni JS); única
+  importación permitida: `tokens.css`; renderiza en `file://` indefinidamente; datos ilustrativos
+  estáticos.
+- Cero valores visuales fuera de tokens (color/fuente/spacing/radio/sombra → `var(--token)`).
+- Estados relevantes (vacío, error, cargando…) que la HU exija → **variantes de pantalla**
+  (`<slug>--<estado>.html`, campo `variante_de` en el manifest), no interacciones.
+- Solo pantallas `estado: "aprobada"` son fuente de verdad (las lee `ux-fidelity-reviewer`); el
+  resto son `borrador`.
+
+## Detección de modo
+
+1. No existe `docs/05-prototipo/` ni hay `design_source.confirmed` → **greenfield**.
+2. Se pide pantallas para una épica y existe app implementada (o prototipo previo) → **feature**.
+3. Ambigüedad → pregunta al humano antes de tocar nada.
+
+## Modo greenfield — prototipo inicial completo
+
+1. **Inventario de pantallas**: lee PRD, user story map/flows e historias de discovery; deriva la
+   lista pantalla ↔ épica/HU (esqueleto del `manifest.json`) y **preséntala para confirmación
+   humana** antes de generar nada.
+2. **Dirección estética**: sigue `references/aesthetic-directions.md` (¿manual de marca? → destilar
+   tokens; si no → 2-3 direcciones visuales de una pantalla clave, elección humana en navegador).
+   Salida: `DESIGN.md` + `tokens.css`.
+3. **Generación por lotes**: pantallas en orden de flow, cada una desde su HU + tokens, sobre
+   `assets/screen.template.html`. Tras cada lote: auto-verificación (`references/self-check.md`)
+   y **pausa** para revisión humana en navegador. Registra cada pantalla en el manifest como
+   `borrador`.
+
+## Modo feature — pantallas de una épica nueva (el caso brownfield)
+
+1. **Precondición dura**: la app implementada **corriendo** + un MCP de inspección de UI habilitado
+   (p.ej. chrome-devtools para web). Si falta cualquiera → **STOP** con instrucciones (levantar la
+   app / habilitar el MCP). **Sin degradación a extracción estática**: el CSS computado real es el
+   factor decisivo de fidelidad (misma postura que el gate `fidelity`, donde INCONCLUSO bloquea).
+2. **Extracción viva**: sigue `references/extraction.md` (CSS computado + screenshots en 3 viewports
+   + árbol de componentes de 2-3 pantallas representativas; reconciliación de `tokens.css`: la app
+   real gana, las divergencias se reportan como drift).
+3. **Generación**: las pantallas nuevas de la épica usan los tokens reconciliados y los screenshots
+   de la app como referencia de composición. Criterio de éxito: la pantalla nueva parece
+   **"una pantalla más"** de la app existente.
+4. **Registro**: entradas nuevas en `manifest.json` como `borrador` (con `epica`/`historias`).
+
+## Auto-verificación (ambos modos)
+
+Sigue `references/self-check.md`: renderizado real de cada HTML (`file://`), screenshot en
+3 viewports + snapshot estructural, comparación (feature → contra lo extraído de la app;
+greenfield → contra tokens + consistencia del lote), corrección y re-render con **máximo
+3 iteraciones**; si no converge, reporte al humano con el delta. Sin pixel-diff.
+
+## Aprobación humana → estado
+
+1. Abre las pantallas en el navegador del usuario y pide aprobación explícita (por pantalla o por
+   lote). Aprobada → `manifest.json` pasa esa entrada a `"aprobada"`.
+2. **Greenfield** con ≥1 pantalla aprobada: ofrece registrar la fuente en `build-state.json` —
+   `design_source.source: "docs/05-prototipo/"`, `confirmed: true`, `confirmed_by`, `confirmed_at`,
+   `notes` — siguiendo el protocolo de escritura de `state/README.md`. Solo con el **sí** explícito
+   del humano.
+3. **Feature**: `design_source` ya está confirmado; solo se amplía el manifest.
+
+## Qué NO hace esta skill
+
+- **No** hace pixel-diff (comparación estructural/semántica, como el resto del arnés).
+- **No** genera código de producción: eso es el slice normal (`building-a-slice`) con su gate
+  `fidelity`; el prototipo es su entrada, no su salida.
+- **No** prototipa interacciones/animaciones (HTML estático; estados como variantes).
+- **No** integra plataformas de diseño externas (exports no navegables ya tienen su rama en
+  `ux-fidelity-reviewer`).
+- **No** escribe en `docs/01-…04-…` ni toca otros campos del estado.

package/skills/prototyping-screens/assets/DESIGN.md.template

@@ -0,0 +1,55 @@
+# DESIGN.md — reglas visuales del producto
+
+> Fuente de verdad **en prosa** de la identidad visual. Los mismos valores viven como CSS custom
+> properties en `tokens.css` (fuente única que importan todos los prototipos). Si este archivo y
+> `tokens.css` divergen, gana `tokens.css` y la divergencia se reporta como drift.
+
+## Identidad
+
+{{DIRECCION_ELEGIDA}} — dirección visual elegida y por qué (elección humana, ver Procedencia).
+
+## Paleta
+
+| Token | Valor | Uso |
+|---|---|---|
+| `--color-primary` | {{HEX}} | {{USO}} |
+| `--color-surface` | {{HEX}} | {{USO}} |
+| `--color-text` | {{HEX}} | {{USO}} |
+| … | … | … |
+
+## Tipografía
+
+- **Familias**: {{FAMILIA_TITULARES}} (titulares) · {{FAMILIA_CUERPO}} (cuerpo).
+- **Escala**: {{ESCALA}} (p.ej. 12/14/16/20/24/32).
+- **Pesos**: {{PESOS}} y dónde se usa cada uno.
+
+## Espaciado y radios
+
+- **Spacing scale**: {{SPACING_SCALE}} (todos los márgenes/paddings son múltiplos de la escala).
+- **Radios**: {{RADIOS}} por tipo de componente.
+
+## Sombras
+
+| Token | Valor | Uso |
+|---|---|---|
+| `--shadow-1` | {{VALOR}} | {{USO}} |
+
+## Componentes
+
+Reglas por componente (densidad, alineación, jerarquía) que los prototipos deben respetar:
+
+- {{COMPONENTE}}: {{REGLA}}
+
+## Don'ts (lista explícita)
+
+- No inventar colores, fuentes, spacing ni radios fuera de los tokens.
+- No introducir dependencias externas en los prototipos (CDNs, frameworks, fuentes remotas).
+- No "interpretar" el diseño al construir: copiar valores exactos.
+- {{DONT_ESPECIFICO_DEL_PRODUCTO}}
+
+## Procedencia
+
+- **Origen de los tokens**: {{ORIGEN}} (manual de marca / extracción viva de la app / dirección
+  elegida por el humano entre variantes).
+- **Fecha**: {{FECHA_ISO}}.
+- **Reconciliaciones**: {{NOTAS_DE_DRIFT}} (cuándo la app real corrigió lo declarado).

package/skills/prototyping-screens/assets/manifest.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "trycore-build/prototype-manifest",
+  "title": "Manifest del prototipo de referencia (docs/05-prototipo/manifest.json)",
+  "description": "Mapa determinista pantalla ↔ épica/HU ↔ archivo HTML ↔ estado. Solo las pantallas con estado 'aprobada' son fuente de verdad visual (las lee ux-fidelity-reviewer y resuelven el puntero por-slice de la DoR).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "pantallas"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "description": "Versión del formato del manifest (hoy: 1)."
+    },
+    "pantallas": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/pantalla" }
+    }
+  },
+  "$defs": {
+    "pantalla": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slug", "archivo", "estado"],
+      "properties": {
+        "slug": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*(--[a-z0-9]+(-[a-z0-9]+)*)?$",
+          "description": "Identificador kebab-case de la pantalla. Las variantes de estado usan sufijo doble guion (p.ej. <slug>--vacio)."
+        },
+        "archivo": {
+          "type": "string",
+          "description": "Ruta relativa al directorio del prototipo (p.ej. pantallas/<slug>.html)."
+        },
+        "epica": {
+          "type": "string",
+          "pattern": "^EP-[0-9]{3}$",
+          "description": "Épica a la que pertenece la pantalla (puntero por-slice de la DoR)."
+        },
+        "historias": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^HU-[0-9]{3}$" },
+          "description": "Historias de usuario que la pantalla cubre."
+        },
+        "estado": {
+          "type": "string",
+          "enum": ["borrador", "aprobada"],
+          "description": "borrador = generada, pendiente de aprobación humana; aprobada = fuente de verdad visual (la aprobación es SIEMPRE humana)."
+        },
+        "generada_en": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Cuándo se generó/regeneró (ISO-8601 UTC)."
+        },
+        "viewports_verificados": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["desktop", "tablet", "mobile"] },
+          "description": "Viewports en los que el self-check renderizó y verificó la pantalla."
+        },
+        "variante_de": {
+          "type": "string",
+          "description": "Slug de la pantalla base si esta entrada es una variante de estado (vacío, error, cargando…)."
+        },
+        "notas": {
+          "type": "string",
+          "description": "Nota libre (p.ej. desviaciones intencionales aceptadas por el humano)."
+        }
+      }
+    }
+  }
+}

package/skills/prototyping-screens/assets/screen.template.html

@@ -0,0 +1,34 @@
+<!doctype html>
+<!--
+  Prototipo de referencia — pantalla {{SLUG}}
+  Reglas duras del artefacto (NO negociables):
+  - AUTOCONTENIDO: cero dependencias externas (sin CDNs, sin frameworks, sin fetch, sin JS).
+    Única importación permitida: ../tokens.css. Debe renderizar en file:// indefinidamente.
+  - TOKENS: todo color, fuente, spacing, radio y sombra sale de las custom properties de
+    ../tokens.css. Cero valores mágicos fuera de tokens.
+  - DATOS ILUSTRATIVOS ESTÁTICOS: contenido de ejemplo neutro, embebido en el HTML.
+  - ESTADOS: los estados relevantes (vacío, error, cargando) que la HU exija son VARIANTES
+    de pantalla en archivos propios ({{SLUG}}--<estado>.html), no interacciones.
+  Trazabilidad: épica {{EPICA}} · historias {{HISTORIAS}} · registrada en ../manifest.json
+-->
+<html lang="es">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{{TITULO_PANTALLA}} — prototipo</title>
+  <link rel="stylesheet" href="../tokens.css">
+  <style>
+    /* Estilos propios de esta pantalla: SOLO composición/layout.
+       Valores visuales (color, fuente, spacing, radio, sombra) → var(--token). */
+  </style>
+</head>
+<body>
+  <!-- región: navegación / cabecera -->
+
+  <!-- región: contenido principal (composición según la HU y el patrón de layout del sistema) -->
+
+  <!-- región: paneles secundarios / laterales (si el diseño los declara) -->
+
+  <!-- región: pie / acciones globales (si el diseño lo declara) -->
+</body>
+</html>

package/skills/prototyping-screens/references/aesthetic-directions.md

@@ -0,0 +1,42 @@
+# Dirección estética (modo greenfield)
+
+Protocolo para fijar la identidad visual **antes** de generar pantallas, cuando discovery solo
+entrega docs de texto. La decisión estética es **humana**; la skill produce opciones y destila.
+
+## 1. ¿Hay manual de marca?
+
+Pregunta primero si el consumidor tiene manual de marca / brand guidelines / design system previo.
+
+- **Sí** → destila los tokens directamente de ese insumo (paleta exacta, tipografías, reglas de
+  uso) a `DESIGN.md` + `tokens.css`, con **Procedencia: manual de marca**. **No** generes
+  variantes: la identidad ya está decidida. Salta al paso 4.
+- **No** → continúa con variantes (pasos 2-3).
+
+## 2. Elegir la pantalla clave
+
+Una sola pantalla para el ejercicio: la más **representativa del journey** (la que un usuario ve
+más tiempo o la que concentra más componentes distintos — típicamente la pantalla principal de
+trabajo tras entrar). Evita pantallas triviales: no discriminan entre direcciones.
+
+## 3. Generar 2-3 direcciones y someterlas a elección humana
+
+1. Genera la pantalla clave en **2-3 direcciones visuales genuinamente distintas** — que difieran
+   en paleta, tipografía y densidad/tono (p.ej. sobria-densa · aireada-amable · contrastada-enérgica),
+   no tres matices del mismo gris. Cada dirección respeta el mismo contenido y la misma HU.
+2. Móntalas **lado a lado en un único HTML comparador** autocontenido (una columna por dirección,
+   con nombre y rasgos clave de cada una) y ábrelo en el navegador del usuario.
+3. El humano elige. Se permite **mezclar** ("la paleta de A con la tipografía de B") si lo pide.
+4. El comparador es un artefacto de trabajo: puede guardarse en `docs/05-prototipo/` como
+   `_direcciones.html` para la trazabilidad de la decisión, pero **no** entra al manifest.
+
+## 4. Destilar `DESIGN.md` + `tokens.css`
+
+De la dirección elegida (o del manual de marca):
+- `tokens.css` — custom properties: paleta completa (con variantes de énfasis/estado), familias y
+  escala tipográfica, spacing scale, radios, sombras.
+- `DESIGN.md` (`assets/DESIGN.md.template`) — la prosa: identidad y por qué se eligió, tablas de
+  tokens con uso, reglas de componentes, **Don'ts** explícitos y **Procedencia** (dirección elegida
+  + fecha).
+
+A partir de aquí, **toda** pantalla del prototipo importa `tokens.css` y no introduce valores
+fuera de tokens; el self-check (`self-check.md`) lo verifica.

package/skills/prototyping-screens/references/extraction.md

@@ -0,0 +1,57 @@
+# Extracción viva del UX/UI implementado (modo feature)
+
+Protocolo para capturar el **contexto rico real** de la app implementada antes de generar
+pantallas nuevas. La lección de fondo: la fidelidad no sale de "mirar un screenshot", sale de
+**CSS computado real + capturas multi-viewport + estructura**. Todo esto exige la app corriendo
+y un MCP de inspección de UI habilitado (p.ej. chrome-devtools para web); sin ellos, la skill
+ya hizo STOP antes de llegar aquí.
+
+## 1. Elegir pantallas representativas (2-3)
+
+Criterio: cubrir los patrones que la pantalla nueva va a necesitar —
+- la pantalla de **navegación/layout principal** (caparazón: menús, cabecera, panel central);
+- una pantalla del **mismo tipo** que la que se va a generar (listado si va a haber listado,
+  formulario si va a haber formulario, detalle si detalle);
+- si existe, una pantalla ya validada como fiel (`gates.fidelity: true` en `history[]`).
+
+## 2. Capturar por cada pantalla
+
+1. **Screenshots en 3 viewports** — desktop, tablet y mobile (redimensionar la página antes de
+   cada captura). Guardan la referencia de composición y densidad.
+2. **CSS computado de elementos clave** — vía el MCP (evaluar `getComputedStyle` sobre):
+   - tipografía real: `font-family`, `font-size`, `font-weight`, `line-height` de titular
+     principal, titular secundario, cuerpo y etiquetas;
+   - color real: `color`, `background-color`, `border-color` de superficie, texto, acción
+     primaria, acción secundaria y estados de énfasis;
+   - espaciado real: `padding`/`margin`/`gap` de los contenedores estructurales y de los
+     componentes repetidos (tarjetas, filas, campos);
+   - `border-radius` y `box-shadow` de los componentes elevados.
+3. **Árbol estructural** — snapshot del árbol accesible/DOM de la pantalla: número y disposición
+   de paneles, orden de secciones, jerarquía. Es la referencia de **composición** (estructura >
+   píxeles).
+
+## 3. Destilar y reconciliar tokens
+
+1. Consolida lo capturado en un conjunto de tokens (paleta, tipografía, spacing scale, radios,
+   sombras). Los valores repetidos entre pantallas son los tokens; los valores únicos son ruido.
+2. **Si `docs/05-prototipo/tokens.css` ya existe → reconciliar**:
+   - **La app real gana** sobre lo declarado: si el token declarado dice un valor y el CSS
+     computado dice otro de forma consistente, actualiza el token al valor real.
+   - Cada divergencia se **reporta al humano como drift** (tabla token → declarado → real →
+     pantallas donde se observó). El drift es señal de que prototipo viejo y app se separaron:
+     el humano decide si además hay que corregir la app (fuera del alcance de esta skill).
+3. Si no existe `tokens.css`, créalo desde lo extraído y genera/actualiza `DESIGN.md`
+   (`assets/DESIGN.md.template`) con **Procedencia: extracción viva** y la fecha.
+
+## 4. Empaquetar el contexto para la generación
+
+Antes de generar, deja explícito el paquete de referencia que usará la pantalla nueva:
+- `tokens.css` reconciliado;
+- screenshots de referencia (composición/densidad) de las pantallas capturadas;
+- el árbol estructural del layout principal (dónde vive el contenido en el caparazón);
+- las reglas de componentes observadas (densidad de tablas, anatomía de formularios, etc.),
+  anotadas en `DESIGN.md` si no estaban.
+
+La generación no "interpreta" este paquete: **copia valores exactos**. Toda desviación deliberada
+se anota como desviación intencional en `notas` del manifest para que `ux-fidelity-reviewer` no
+la penalice después.