@trycore/spec-build-harness 0.8.3 → 0.8.5

package/skills/prototyping-screens/references/self-check.md

@@ -0,0 +1,40 @@
+# Auto-verificación visual del prototipo (ambos modos)
+
+El prototipo no se da por bueno porque "se escribió bien": se **renderiza de verdad y se observa
+la salida real** antes de presentarlo al humano. Misma filosofía que el gate `fidelity`
+(verificación visual real, no best-effort), aplicada en dirección inversa: aquí lo verificado es
+el prototipo recién generado.
+
+## Protocolo por pantalla generada
+
+1. **Renderizar**: abrir el HTML vía `file://` con el MCP de inspección de UI (nueva página).
+   Si el archivo no renderiza limpio (recursos rotos, consola con errores), corregir antes de
+   comparar nada.
+2. **Capturar**: screenshot en **3 viewports** (desktop, tablet, mobile) + snapshot del árbol
+   accesible/DOM.
+3. **Comparar** según el modo:
+   - **Feature** — contra el paquete de extracción (`extraction.md`): ¿la tipografía computada
+     coincide token a token? ¿la paleta usada es la reconciliada, sin colores fuera? ¿la densidad
+     (spacing computado) y el patrón de layout replican los de las pantallas capturadas? ¿la
+     pantalla "parece una más" de la app?
+   - **Greenfield** — contra `DESIGN.md`/`tokens.css`: **cero valores visuales fuera de tokens**
+     (inspeccionar computed styles de los elementos clave); y **consistencia del lote**: mismas
+     resoluciones de componente (el mismo tipo de elemento se ve igual) entre las pantallas
+     generadas en esta tanda.
+4. **Corregir y re-renderizar** cada divergencia encontrada. **Máximo 3 iteraciones** por
+   pantalla; si a la tercera no converge, **parar y reportar al humano** el delta restante
+   (qué difiere, dónde, valor esperado vs observado) — nunca presentar como buena una pantalla
+   que no pasó su self-check.
+5. **Registrar**: anotar en `manifest.json` los `viewports_verificados` de la pantalla. El
+   `estado` sigue siendo `borrador`: el self-check **no aprueba** — aprobar es del humano.
+
+## Reglas
+
+- **Sin pixel-diff**: la comparación es estructural/semántica (composición, tokens computados,
+  densidad, jerarquía), igual que `ux-fidelity-reviewer`. El pixel-diff es frágil y no discrimina
+  desviaciones que importan de ruido de render.
+- **Estructura > píxeles**: una columna de más o un panel ausente pesa más que 2px de padding.
+- Las **variantes de estado** (`<slug>--<estado>.html`) pasan el mismo protocolo (suelen ser más
+  baratas: heredan la composición de la base).
+- El self-check corre **por lote** en greenfield (tras generar cada tanda) y **por pantalla** en
+  feature (pocas pantallas, más exigencia de encaje con la app).

package/state/README.md

@@ -56,8 +56,27 @@ slice (fases `red…data`) mientras `confirmed` no sea `true`. El arnés **no ge
 ### `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`.
+existe una fuente de diseño declarada), `source` (puntero al prototipo/export). El prototipo puede
+**generarse** con `/build:prototype` (skill `prototyping-screens`, salida en `docs/05-prototipo/`);
+`confirmed` sigue siendo exclusivamente humano. Lo respalda `design-source-guard.sh`.
+
+### `foundation` (gate de proyecto, solo greenfield) + `project_kind`
+
+`project_kind` (`greenfield` | `brownfield` | `null`) lo detecta `trycore-build init` con
+heurística conservadora (`project_kind_source: "auto"`); ante ambigüedad queda `null` y
+`/build:onboard` pregunta una vez (`"human"`). En **brownfield el mecanismo entero es N/A**: no
+se pregunta ni se exige nada.
+
+`foundation` es el contrato de la **épica caparazón** (app shell: navegación, layout, homepage,
+login, redirecciones — ids canónicos en
+`skills/building-a-slice/references/foundation-contract.md`): `{ required, epic, completed_at,
+checklist[] }`. En greenfield, el DoR (criterio 7-bis, **proactivo**) bloquea abrir épicas
+`layer: business` hasta que la épica caparazón (`foundation.epic`) esté **archivada con su
+checklist evidenciada** (`foundation.completed_at` estampado); otras épicas fundacionales abren
+libremente pero no satisfacen este gate. El DoD de la épica caparazón exige `evidence` de
+ejecución por cada ítem `applies: true` y al archivar se estampa `completed_at`. El arnés
+**propone** el borrador de la épica y solo lo escribe con aprobación humana explícita (carve-out
+METODOLOGIA §9.2).
 
 ### gate `fidelity` (por-slice, inner loop) — ESTRICTO para UI
 
@@ -102,3 +121,8 @@ El razonamiento vive en el modelo; el hook solo es un recordatorio determinista.
 | `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) | — |
+| `project_kind` · `project_kind_source` | `trycore-build init` (auto) · `/build:onboard` (human, solo ambiguo) | una vez |
+| `foundation` (`required`, `checklist[]`, `epic`) | `/build:onboard` Fase 2c | una vez (greenfield) |
+| `foundation.checklist[].evidence` | `build-orchestrator` (durante la construcción de la caparazón) | al construir la caparazón |
+| `foundation.completed_at` | `dor-dod-gatekeeper` (al cerrar el DoD de la épica caparazón) | al archivar la caparazón |
+| `design_source` (`source`, `confirmed`, `confirmed_by/at`, `notes`) | `building-a-slice` Fase 0-bis · `/build:onboard` Fase 3c · `prototyping-screens` (greenfield, solo tras aprobación humana de ≥1 pantalla; `confirmed` humano siempre) | una vez (proyecto) |

package/state/build-state.schema.json

@@ -35,7 +35,18 @@
     "parallel_front": {
       "description": "Coordinación outer-loop de worktrees inter-épica (C). null = modo secuencial normal.",
       "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/parallel_front" } ]
-    }
+    },
+    "project_kind": {
+      "type": ["string", "null"],
+      "enum": ["greenfield", "brownfield", null],
+      "description": "Tipo de proyecto. brownfield = ya construido (el requisito de épica caparazón NO aplica y no se pregunta); greenfield = app nueva (activa el gate foundation); null = indeterminado (lo resuelve /build:onboard con el humano). Detección automática en trycore-build init."
+    },
+    "project_kind_source": {
+      "type": ["string", "null"],
+      "enum": ["auto", "human", null],
+      "description": "Quién fijó project_kind: auto (heurística del CLI, solo con certeza) | human (confirmado en onboard ante ambigüedad)."
+    },
+    "foundation": { "$ref": "#/$defs/foundation" }
   },
   "$defs": {
     "scaffold": {
@@ -53,7 +64,7 @@
     "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).",
+      "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 prototipo puede generarse con /build:prototype (skill prototyping-screens); confirmed sigue siendo exclusivamente humano. 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." },
@@ -64,6 +75,34 @@
         "notes": { "type": "string", "description": "Evidencia libre (p.ej. 'prototipo en docs/… revisado y vigente')." }
       }
     },
+    "foundation": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Gate de PROYECTO (solo greenfield): la épica caparazón — navegación/menús, layout/panel central, homepage, login/authN, redirecciones/guards — debe construirse y archivarse ANTES que cualquier épica business. El contrato es la checklist (podada por el humano en /build:onboard según el tipo de app); cada ítem applies=true exige evidence en el DoD (patrón wiring_checklist, nada de palabra de honor). El arnés propone el borrador de la épica pero solo lo escribe con aprobación humana explícita.",
+      "required": ["required"],
+      "properties": {
+        "required": { "type": "boolean", "description": "true solo en greenfield con contrato confirmado en onboard. false = N/A (brownfield o proyecto sin caparazón exigible)." },
+        "epic": {
+          "oneOf": [ { "type": "null" }, { "type": "string", "pattern": "^EP-[0-9]{3}$" } ],
+          "description": "La épica caparazón del backlog. null mientras no exista (el gate del DoR bloquea business igual)."
+        },
+        "completed_at": { "type": ["string", "null"], "format": "date-time", "description": "Cuándo se archivó la épica caparazón con toda la checklist evidenciada. null = pendiente." },
+        "checklist": {
+          "type": "array",
+          "description": "Contrato del caparazón. Ids canónicos: navegacion-menus, layout-panel-central, homepage, login-authn, redirecciones-guards (podables; extensible por proyecto).",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["item", "applies"],
+            "properties": {
+              "item": { "type": "string", "description": "Id kebab-case del ítem del contrato." },
+              "applies": { "type": "boolean", "description": "false = podado en onboard (p.ej. homepage en una API sin UI)." },
+              "evidence": { "type": "string", "description": "Evidencia de ejecución que demuestra el ítem construido (test/comando/screenshot). Vacío mientras pendiente." }
+            }
+          }
+        }
+      }
+    },
     "slice": {
       "type": "object",
       "additionalProperties": false,

package/state/build-state.template.json

@@ -15,6 +15,14 @@
     "source": "",
     "notes": ""
   },
+  "project_kind": null,
+  "project_kind_source": null,
+  "foundation": {
+    "required": false,
+    "epic": null,
+    "completed_at": null,
+    "checklist": []
+  },
   "active_slice": null,
   "history": [],
   "releases": []

package/templates/CLAUDE.md.template

@@ -37,7 +37,7 @@ Outer loop (por release):       Release Gate (seguridad · diseño · UX · cohe
 5. **Producto completo, no MVP.** El alcance acordado se construye **entero**. **Recortar o diferir es bloqueante explícito** que requiere acuerdo del equipo — **nunca** una decisión del modelo. No se "deja para después" ni se deriva en lo complejo. La verificación es **ejecutada, no por inspección** (correr la suite, cargar la página, leer la consola).
 6. **Cierre verificado, no declarado.** `dod` exige el gate `wiring_verified`: un subagente **adversarial independiente** (`wiring-adversarial-verifier`, contexto virgen) intenta refutar el slice (stubs, rutas sin cablear, AC sin test) antes de cerrar. El estado del cableado vive en disco (`wiring_checklist[]` + `progress_log[]`) para que una sesión fresca retome sin "creer que ya está".
 7. **Fidelidad por verificación visual real.** Para slices con UI, el gate `fidelity` solo cierra observando la salida real vía MCP de devtools de navegador (screenshot app vs prototipo); sin verificación visual queda `false` (no "INCONCLUSO pasa").
-8. **Cimiento antes que negocio y unidades pequeñas.** Las épicas de cimiento (auth, datos, arquitectura base, design-system) se construyen antes que las de negocio; una épica grande (>3 HU ó ≥3 capas) se descompone en sub-slices construidos de a uno.
+8. **Cimiento antes que negocio y unidades pequeñas.** Las épicas de cimiento (auth, datos, arquitectura base, design-system) se construyen antes que las de negocio; una épica grande (>3 HU ó ≥3 capas) se descompone en sub-slices construidos de a uno. En proyectos **nuevos** (`project_kind: greenfield`), la **épica caparazón** (app shell: navegación, layout, homepage, login, redirecciones — gate de proyecto `foundation`) se construye y archiva **con evidencia** antes que cualquier épica de negocio; en brownfield el mecanismo es N/A.
 9. Si una regla del arnés contradice la metodología Trycore (`METODOLOGIA.md`), **gana la metodología**.
 
 ### Bloque de dominio (lo resuelve `/build:onboard`)
@@ -51,7 +51,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}}
+- **Fuente de diseño / referencia visual**: {{DESIGN_SOURCE}} (si no existe fuente aún, `/build:prototype` puede generarla en `docs/05-prototipo/`; la confirmación sigue siendo humana)
 
 (Si aparecen como `{{...}}`, ejecuta `/build:onboard` para parametrizarlos.)