@trycore/spec-build-harness 0.5.0 → 0.6.0

package/skills/building-a-slice/references/state-protocol.md

@@ -11,6 +11,19 @@ python3 -c 'import json;print(json.dumps(json.load(open(".claude/state/build-sta
 - `active_slice == null` → no hay slice; solo `dor` puede abrir uno.
 - Si no es null → identifica el **primer gate en `false`**: ahí se reanuda.
 
+## Refresh de contexto = estado por defecto (handoff en disco)
+Cada iteración nace **headless / contexto virgen** y reconstruye el estado **desde disco** (git history +
+este `build-state.json` + logs de build), **no** desde la conversación viva: alargar una sesión degrada
+el razonamiento (ruido acumulado → deriva). Para retomar sin "creer que ya está":
+- **`wiring_checklist[]`** — un item por escenario AC de cada HU y por **punto de integración entre capas**.
+  Nace `failing`; pasa a `passing` **SOLO tras prueba real ejecutada** (con `evidence`), nunca por inspección.
+  **Mientras quede un item `failing`, el slice NO está cableado** — no cierres `wiring_verified` ni `dod`.
+- **`progress_log[]`** — bitácora append-only (`{at, by, note}`) de qué se hizo / qué falta. Deja una nota
+  por hito para que la siguiente sesión retome el cableado.
+- **`sub_slices[]`** — si la épica superó el gate de tamaño (>3 HU ó ≥3 capas), se trocea aquí; cada
+  sub-slice se construye de a uno con su `journey_smoke` verde antes de pasar al siguiente.
+`load-build-state.sh` inyecta al arrancar los items `failing` y la última bitácora (JIT, solo lo pendiente).
+
 ## Escritura (una transición = una escritura)
 Patrón seguro (lee-modifica-escribe) con timestamp UTC:
 ```bash
@@ -27,16 +40,20 @@ PY
 ```
 
 ## Inner loop vs releases[]
-- **Inner loop (por slice)**: gates `dor`, `tdd`, `journey_smoke`, `coherence_link`, `data`, `api`,
-  `dod` en `active_slice.gates`. Los escribe el flujo de `building-a-slice` / `build-orchestrator`.
+- **Inner loop (por slice)**: gates `dor`, `tdd`, `journey_smoke`, `coherence_link`, `data`, `fidelity`,
+  `api`, `wiring_verified`, `dod` en `active_slice.gates`. Los escribe el flujo de `building-a-slice` /
+  `build-orchestrator`. **`wiring_verified` es prerequisito de `dod`** (lo cierra el verificador
+  adversarial independiente, no el mismo agente que construyó).
 - **Outer loop (por release)**: los gates pesados (`security`, `smell`, `ux`, `coherence`,
   `stack_arch`, `integration`) **no** viven en el slice — viven en una entrada de `releases[]` que
   escribe la skill `releasing-a-version`. Una release = una línea de release del Story Map.
 
 ## Reglas
-1. **No saltes gates**: no cierres `dod` con gates abiertos.
+1. **No saltes gates**: no cierres `dod` con gates abiertos; en particular `dod` exige `wiring_verified: true`.
 2. **Retroceso permitido**: si una revisión posterior falla, pon su gate en `false` y retrocede `phase`.
-3. **`ux`/`api` = `null`** cuando no aplican (no cuentan como abiertos para DoD).
+3. **`fidelity`/`api` = `null`** cuando no aplican (no cuentan como abiertos para DoD). `fidelity` NO puede
+   quedar `null` si el slice toca UI (`design_source.applies===true`): ahí debe llegar a `true` por
+   verificación visual real (MCP). `wiring_verified` aplica siempre (no admite `null`).
 4. **Archivar**: mueve `active_slice` a `history[]` con `phase:"archived"`, deja `active_slice:null`.
 5. **Valida tras escribir**:
    ```bash

package/state/README.md

@@ -24,7 +24,9 @@ Cada gate del pipeline transiciona el estado; el siguiente agente lo lee antes d
    correspondiente, `updated_at` (ISO 8601 UTC) y `updated_by` (su nombre). No tocar otros campos.
 3. **Gates monótonos hacia adelante.** Un gate solo pasa de `false`→`true` cuando su agente lo
    aprueba. Si una revisión posterior falla, se vuelve a `false` y `phase` retrocede.
-4. **`ux`/`api` admiten `null`** cuando el slice no tiene UI o endpoints (N/A, no bloquea DoD).
+4. **`fidelity`/`api` admiten `null`** cuando el slice no tiene UI o endpoints (N/A, no bloquea DoD).
+   `fidelity` **no** puede quedar `null` si el slice toca UI. `wiring_verified` aplica siempre (sin `null`)
+   y es **prerequisito de `dod`**.
 5. **Archivar**: al completar `opsx:archive`, mover el `active_slice` a `history[]` con
    `phase: "archived"` y dejar `active_slice: null`.
 6. **Dos loops**: el slice (inner loop) cierra gates baratos por épica; los gates pesados viven en
@@ -57,10 +59,25 @@ Espejo de `scaffold` para la UI: `applies` (¿el proyecto tiene UI?), `confirmed
 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)
+### gate `fidelity` (por-slice, inner loop) — ESTRICTO para UI
 
-`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`.
+`true` = FIEL (o desviaciones justificadas, **vía verificación visual real**); `false` = desviaciones
+sin justificar **o** verificación visual no realizada; `null` = slice sin UI. Lo computa
+`ux-fidelity-reviewer` en la fase `smoke` y lo escribe el `build-orchestrator`. Para slices con UI
+(`design_source.applies===true`) solo cierra con **MCP chrome-devtools** (screenshot app vs prototipo):
+INCONCLUSO ya **no** pasa (queda `false` → el `dod` no cierra hasta correrlo donde haya MCP).
+
+### Handoff fino del cableado (`wiring_checklist[]`, `progress_log[]`, `sub_slices[]`) + gate `wiring_verified`
+
+Campos por-slice que hacen el **refresh de contexto el estado por defecto** (una sesión fresca retoma
+desde disco, no desde la conversación):
+- **`wiring_checklist[]`** — un item por escenario AC y por punto de integración entre capas; nace
+  `failing`, pasa a `passing` **solo tras prueba real ejecutada** (con `evidence`).
+- **`progress_log[]`** — bitácora append-only (`{at, by, note}`) que sobrevive al reset.
+- **`sub_slices[]`** — descomposición de una épica que superó el gate de tamaño (>3 HU ó ≥3 capas).
+- **gate `wiring_verified`** — lo cierra el `wiring-adversarial-verifier` (subagente **independiente**,
+  contexto virgen, que intenta **refutar** el slice). `dod` no puede ser `true` sin él. Lo inicializa
+  el `dor-dod-gatekeeper` en `false` durante el DoR.
 
 ### Reflexión post-slice (ciclo autocorrectivo)
 
@@ -78,9 +95,10 @@ El razonamiento vive en el modelo; el hook solo es un recordatorio determinista.
 | `active_slice` (alta) · `gates.dor` · `gates.dod` | `dor-dod-gatekeeper` | slice |
 | `gates.coherence_link` | `change-epic-coherence` | slice |
 | `gates.tdd` | flujo `superpowers:test-driven-development` (vía `build-orchestrator`) | slice |
-| `gates.journey_smoke` · `phase` (transiciones) · `history[]` (archivado) | `build-orchestrator` | slice |
+| `gates.journey_smoke` · `gates.fidelity` · `phase` (transiciones) · `history[]` (archivado) · `wiring_checklist[]` · `progress_log[]` · `sub_slices[]` | `build-orchestrator` (fidelity desde `ux-fidelity-reviewer`) | slice |
 | `gates.api` | `api-contract-tester` | slice |
 | `gates.data` | `data-consistency-checker` | slice |
+| `gates.wiring_verified` | `wiring-adversarial-verifier` (independiente, contexto virgen) | slice (antes de `dod`) |
 | `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

@@ -82,15 +82,16 @@
         "gates": {
           "type": "object",
           "additionalProperties": false,
-          "description": "Inner loop (por slice): dor, tdd, journey_smoke, data, api(null), coherence_link, dod. Los gates pesados (stack, security, smell, ux, coherence) se cerraron por slice en la era anterior y hoy viven en releases[]; se mantienen como propiedades opcionales para validar historial.",
+          "description": "Inner loop (por slice): dor, tdd, journey_smoke, coherence_link, data, fidelity, api(null), wiring_verified, dod. Los gates pesados (stack, security, smell, ux, coherence) se cerraron por slice en la era anterior y hoy viven en releases[]; se mantienen como propiedades opcionales para validar historial.",
           "required": ["dor", "tdd", "dod"],
           "properties": {
             "dor": { "type": "boolean" },
             "tdd": { "type": "boolean" },
-            "journey_smoke": { "type": "boolean", "description": "El backbone-hasta-aquí camina end-to-end (verificado con la skill verify/run)." },
+            "journey_smoke": { "type": "boolean", "description": "El backbone-hasta-aquí camina end-to-end (verificado con la skill verify/run + runner fuera-de-chat integration-check)." },
             "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[])." },
+            "fidelity": { "type": ["boolean", "null"], "description": "Gate VIVO de inner loop, computado en fase smoke por ux-fidelity-reviewer. Aplica cuando el slice toca UI (en un proyecto con design_source.applies===true); si el slice NO toca UI, es null aunque el proyecto tenga UI. ESTRICTO para UI: solo cierra con VERIFICACIÓN VISUAL REAL vía MCP de devtools de navegador (screenshot app vs prototipo). true = FIEL (o DESVIACIONES justificadas, vía MCP); false = DESVIACIONES sin justificar O verificación visual no realizada (INCONCLUSO ya NO pasa para UI); null = N/A (slice sin UI). NO es legado (los legados viven en releases[])." },
+            "wiring_verified": { "type": "boolean", "description": "Gate de cierre del inner loop (A4): un subagente adversarial INDEPENDIENTE de contexto virgen (wiring-adversarial-verifier) intentó refutar el slice (stubs, rutas sin cablear, AC sin test, items de wiring_checklist[] aún failing) y NO encontró huecos. dod NO puede ser true hasta que wiring_verified sea true. Lo inicializa el gatekeeper en false en el DoR." },
             "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[]." },
@@ -104,7 +105,53 @@
         "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)." },
         "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." }
+        "reflected_at": { "type": "string", "format": "date-time", "description": "Cuándo se reflexionó (ISO-8601 UTC). Lo escribe /build:reflect." },
+        "wiring_checklist": {
+          "type": "array",
+          "description": "Handoff FINO del cableado (A1): un item por escenario AC de cada HU y por punto de integración entre capas (SPA↔gateway↔core↔worker↔persistencia). Nace failing; pasa a passing SOLO tras prueba real ejecutada (con evidence), nunca por inspección. Sobrevive al reset de contexto: una sesión fresca lee los failing de disco y NO declara 'hecho' si quedan. El wiring-adversarial-verifier audita estos items antes de cerrar wiring_verified. Ausente/vacío en slices triviales.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "kind", "ref", "status"],
+            "properties": {
+              "id": { "type": "string", "description": "Identificador estable del item (p.ej. HU-003-AC2 o INT-spa-gateway)." },
+              "kind": { "type": "string", "enum": ["hu_ac", "integration_point"], "description": "hu_ac = escenario Given/When/Then de una HU; integration_point = cableado entre dos capas." },
+              "ref": { "type": "string", "description": "A qué apunta: el AC (HU-XXX#escenario) o el par de capas (capaA→capaB)." },
+              "status": { "type": "string", "enum": ["failing", "passing"], "description": "failing al nacer; passing SOLO tras prueba real ejecutada." },
+              "evidence": { "type": "string", "description": "Evidencia de ejecución que justificó passing (test, comando, salida). Vacío mientras failing." }
+            }
+          }
+        },
+        "progress_log": {
+          "type": "array",
+          "description": "Bitácora de progreso que sobrevive al reset de contexto (A1): permite a una sesión fresca/headless retomar el cableado sin 'creer que ya está'. Append-only; complementa a git history y los logs de build.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["at", "by", "note"],
+            "properties": {
+              "at": { "type": "string", "format": "date-time" },
+              "by": { "type": "string", "description": "Agente/sesión que dejó la nota." },
+              "note": { "type": "string", "description": "Qué se hizo / qué falta (hito conciso)." }
+            }
+          }
+        },
+        "sub_slices": {
+          "type": "array",
+          "description": "Descomposición de una épica grande (A3): si supera el umbral del gate de tamaño (>3 HU ó ≥3 capas tocadas), se trocea en sub-slices verificables construidos DE A UNO, con journey_smoke verde entre cada uno. Ausente/vacío = épica atómica (no superó el umbral). Acota además el tamaño de wiring_checklist[] por paso.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "title", "status"],
+            "properties": {
+              "id": { "type": "string", "description": "Identificador del sub-slice (p.ej. EP-003-a)." },
+              "title": { "type": "string" },
+              "hus": { "type": "array", "items": { "type": "string", "pattern": "^HU-[0-9]{3}$" }, "description": "Subconjunto de hus[] cubierto por este sub-slice." },
+              "status": { "type": "string", "enum": ["pending", "done"], "description": "done SOLO con su journey_smoke verde." },
+              "journey_smoke": { "type": "boolean", "description": "El backbone-hasta-este-sub-slice camina end-to-end." }
+            }
+          }
+        }
       }
     },
     "release": {

package/templates/CLAUDE.md.template

@@ -7,7 +7,7 @@ Este proyecto usa el arnés `@trycore/spec-build-harness` para **construir** sob
 (compañero de `@trycore/spec-product-flow`: Discovery → Construcción). Modelo de **dos loops**:
 
 ```
-Inner loop (por épica EP-XXX):  DoR → OpenSpec change → TDD → journey-smoke → api/data → DoD → PR + archive
+Inner loop (por épica EP-XXX):  DoR → OpenSpec change → TDD → journey-smoke → api/data → verificación adversarial → DoD → PR + archive
 Outer loop (por release):       Release Gate (seguridad · diseño · UX · coherencia triple · arquitectura · integración)
 ```
 
@@ -30,7 +30,11 @@ Outer loop (por release):       Release Gate (seguridad · diseño · UX · cohe
 2. El enlace change↔épica va en el bloque `## Trazabilidad` del `proposal.md`, **nunca** en frontmatter YAML (rompe `openspec validate`).
 3. Las dependencias se vigilan contra `.claude/config/stack-allowlist.json` (hook `stack-guard.sh`), derivado de la sección de requisitos técnicos del PRD.
 4. Las revisiones pesadas (seguridad/diseño/UX/coherencia triple/arquitectura/integración) corren **una vez por release** (outer loop), no por épica.
-5. Si una regla del arnés contradice la metodología Trycore (`METODOLOGIA.md`), **gana la metodología**.
+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.
+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`)
 

package/templates/integration-check.sh.template

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# integration-check.sh — runner determinista FUERA DE CHAT para cerrar `journey_smoke` (inner loop).
+#
+# Qué es: un gate determinista que ejecuta build + suite completa + un journey-smoke end-to-end y
+# emite un REPORTE de integración a disco, con salida 0 (verde) / ≠0 (rojo). Está pensado para correr
+# en una **sesión/contexto virgen** distinta de la que escribió el código (el agente que cableó no es
+# juez de su propio cableado), y para el **fix-loop** (lo corres, lees el reporte, arreglas, repites).
+#
+# Por qué un script y no un agente: el cableado end-to-end no se acredita "por inspección" sino
+# EJECUTANDO. Mantenerlo fuera del chat lo hace reproducible y barato en contexto.
+#
+# AGNÓSTICO: este es un TEMPLATE. El arnés no asume tu stack. Ajusta los comandos marcados con
+# «# ADAPTA» a tu proyecto (lenguaje, package manager, comando de e2e). Cópialo a tu repo
+# (p.ej. tools/loop/integration-check.sh) y hazlo ejecutable.
+#
+# NO crea ningún gate nuevo en build-state.json: alimenta el gate EXISTENTE `journey_smoke` del slice.
+# El gate `integration` con dependencias reales sigue siendo del Release Gate (outer loop), no de aquí.
+set -uo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$(pwd)}")"
+REPORT_DIR="$ROOT/.claude/state"
+REPORT="$REPORT_DIR/integration-report.txt"
+mkdir -p "$REPORT_DIR"
+
+# Detecta el package manager si hay package.json (Node). ADAPTA para otros stacks.
+PM="npm"
+if [ -f "$ROOT/pnpm-lock.yaml" ]; then PM="pnpm";
+elif [ -f "$ROOT/yarn.lock" ]; then PM="yarn"; fi
+
+fail=0
+log() { printf '%s\n' "$*" | tee -a "$REPORT"; }
+
+: > "$REPORT"
+log "== integration-check =="
+log "root: $ROOT"
+log "pm:   $PM"
+log "ts:   (sin timestamp determinista; lo estampa quien invoca)"
+log ""
+
+run() { # run <etiqueta> <comando...>
+  local label="$1"; shift
+  log "▶ $label: $*"
+  if "$@" >>"$REPORT" 2>&1; then
+    log "  ✓ $label OK"
+  else
+    log "  ✗ $label FALLÓ"
+    fail=1
+  fi
+  log ""
+}
+
+# --- Fases del runner (ADAPTA los comandos a tu stack) ---
+# 1) Build: el proyecto compila/construye sin error.
+run "build"  $PM run build          # ADAPTA (p.ej. cargo build, ./gradlew build, make)
+# 2) Suite completa: todos los tests, no un subconjunto.
+run "tests"  $PM test               # ADAPTA (p.ej. pytest, go test ./..., cargo test)
+# 3) Journey-smoke end-to-end: recorre el backbone-hasta-aquí. ADAPTA al e2e de tu proyecto.
+#    Si tu e2e necesita la app levantada, levántala aquí (y bájala al salir).
+# run "e2e"  $PM run test:e2e        # ADAPTA / descomenta
+
+log "== resultado: $([ "$fail" -eq 0 ] && echo VERDE || echo ROJO) =="
+log "Reporte: $REPORT"
+
+# Salida determinista: 0 verde, 1 rojo. El gate journey_smoke solo se marca true con salida 0.
+exit "$fail"