@trycore/spec-build-harness 0.8.4 → 0.10.0

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

@@ -0,0 +1,75 @@
+# Protocolo de estado sobre el runtime (modos `dual` y `runtime`)
+
+El estado del pipeline vive en el **Agent Orchestrator Runtime**: fases, gates, wiring,
+checkpoints, releases y hechos de proyecto son suyos. El arnés **observa el working tree**
+(hooks) y **transiciona el dominio** por la API. Ningún agente arma peticiones a mano: todo
+acto pasa por `slice-ops.sh` (inner loop) y `release-ops.sh` (outer loop), instalados en
+`.claude/hooks/build/`.
+
+> **Antes de nada, pregunta el modo:**
+> ```bash
+> bash .claude/hooks/build/slice-ops.sh mode      # legacy | dual | runtime
+> ```
+> - `legacy` → **no** uses este documento: el fichero es primario, sigue `state-protocol.md`.
+> - `dual` → el **fichero sigue siendo primario** (escríbelo como en `state-protocol.md`) y
+>   **además** invoca los subcomandos: espejan cada transición al runtime. El claim NO
+>   aplica en `dual` (devuelve rc 3): el slice lo decide el fichero.
+> - `runtime` → el fichero es fósil: **no lo leas ni lo escribas**. Todo pasa por los
+>   subcomandos, y el estado se consulta con `slice-ops.sh status`.
+
+## Códigos de salida (ramifica sobre ellos, no sobre el texto)
+
+| rc | Significado | Qué hace la skill |
+|---|---|---|
+| 0 | aceptado | continúa |
+| 2 | uso incorrecto | corrige la invocación (bug de la skill, no del runtime) |
+| 3 | modo `legacy` (o claim en `dual`) | sigue el protocolo del fichero |
+| 4 | sin slice activo | reclama primero (`claim`) o abre el slice por DoR |
+| 5 | offline: encolado | **sigue trabajando**; el daemon entrega al reconectar |
+| 6 | rechazado por el servidor | **NO reintentes**: muestra la razón y corrige la causa |
+| 7 | sin trabajo (204) o carrera perdida | comunica y termina limpio |
+
+## El ciclo del slice
+
+| Acto | Comando | Notas |
+|---|---|---|
+| Reclamar | `slice-ops.sh claim [--epic EP-XXX]` | Sincroniza el contexto **antes** (regla: no se abre trabajo con contexto viejo) y reporta los sha256 locales de los archivos gobernados. Si la respuesta trae `checkpoint`, **continúa desde él; jamás reinicies**. |
+| Saber el paso | `slice-ops.sh next-step` | Lo deriva el **cliente** desde la proyección: `resume_hint` → wiring `failing` → sub-slice pendiente → primer gate abierto. |
+| Sembrar el cableado | `slice-ops.sh wiring seed --file items.json` | Un item por escenario AC y por punto de integración entre capas. Nacen `failing`. |
+| Cablear un item | `slice-ops.sh wiring update <item_id> passing --kind K --ref HU-XXX --evidence-file f` | `passing` **solo tras prueba real ejecutada**. Sin evidencia el comando avisa: no lo ignores. |
+| Cerrar un gate | `slice-ops.sh gate <nombre> <pass\|fail\|na> --evidence-file f` | Gates canónicos: `dor coherence_link tdd journey_smoke fidelity api data wiring_verified dod`. Un `na` es legítimo cuando el gate no aplica. |
+| Dejar bitácora | `slice-ops.sh progress «hito»` | Sustituye a `progress_log[]`: el event stream **es** la bitácora. |
+| Guardar continuidad | `slice-ops.sh checkpoint --note «dónde me quedé»` | Rama + commit reales. Es lo que permite que otro agente continúe tras una caída. |
+| Entregar | `slice-ops.sh submit --pr-url U --openspec-change C` | Tras abrir el PR. |
+| Archivar | `slice-ops.sh archive --epic EP-XXX --openspec-change C --pr-url U` | Lo dispara `opsx:archive` en el mismo PR. Va por cola (idempotente, protegido de la cota). |
+| Hechos de proyecto | `slice-ops.sh fact scaffold-confirmed --by «persona»` · `fact design-source …` · `fact project-kind …` · `fact foundation …` | **Reportan lo que un humano confirmó**; el agente nunca confirma por su cuenta. |
+| Bloqueo | `slice-ops.sh escalate «razón» --gate G` | Deja el rastro; la decisión (recortar/diferir/desbloquear) es del equipo. |
+| Ver el estado | `slice-ops.sh status` | Modo, slice, gates, wiring, contexto, lease y cola pendiente. |
+
+## Reglas duras
+
+1. **Un gate no se salta y `dod` exige `wiring_verified`.** La compuerta real es el servidor:
+   un `422` es la compuerta funcionando, no un error a reintentar.
+2. **Nunca marques `passing`/`pass` por inspección.** La evidencia es de ejecución real.
+3. **Contexto antes que trabajo.** Si el `manifest_hash` no coincide, el claim sincroniza
+   solo; si el servidor responde `409 drift`, el cliente re-sincroniza y reintenta **una** vez.
+4. **Un solo slice activo.** Reclamar con lease vigente devuelve el mismo slice (idempotente).
+5. **Lease perdido** (`⚠ lease` en la statusline, `heartbeat-status.json`): haz `checkpoint`,
+   detén el trabajo y vuelve a reclamar. No sigas cerrando gates con el lease caído.
+6. **Offline no bloquea.** rc 5 = encolado: sigue construyendo; el daemon despacha al
+   reconectar y el `client_event_id` evita duplicados.
+7. **El agente no gobierna.** No cierra releases, no publica contexto, no importa el grafo,
+   no abre/drena/cierra fronts: prepara, propone, reporta — y el humano decide en la consola.
+
+## Qué queda del fichero (legado)
+
+En `runtime` el fichero `.claude/state/build-state.json` **no se lee ni se escribe** (queda fósil hasta que el sub-slice E lo retire); solo en modo `legacy` sigue siendo el protocolo primario — ver `state-protocol.md`. Lo que antes se leía de él ahora:
+
+| Antes (fichero) | Ahora |
+|---|---|
+| `active_slice.gates` | `slice-ops.sh status` / caché de proyección |
+| `active_slice.wiring_checklist[]` | eventos `wiring_*` + `wiring_failing` de la proyección |
+| `active_slice.progress_log[]` | eventos `progress_note_recorded` (event stream) |
+| `session_continuity.resume_hint` | `resume_hint` de `/agent/context` (lo rinde `next-step`) |
+| `scaffold`, `design_source`, `project_kind`, `foundation` | hechos de proyecto (`fact …`) |
+| `history[]`, `releases[]`, `parallel_front` | proyecciones del runtime (consola del hub) |

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

@@ -1,4 +1,11 @@
-# Protocolo del archivo de estado (`build-state.json`)
+# Protocolo del archivo de estado (`build-state.json`) — **modo `legacy`**
+
+> **Vigencia:** este documento describe el protocolo del **modo `legacy`** (v0.8.5 exacto),
+> donde el fichero es la fuente de verdad. En `dual` el fichero sigue siendo primario **y
+> además** cada transición se espeja al runtime; en `runtime` el fichero es fósil y **no se
+> lee ni se escribe**. Para esos dos modos, el protocolo es
+> [`runtime-protocol.md`](runtime-protocol.md). Comprueba el modo con
+> `bash .claude/hooks/build/slice-ops.sh mode`.
 
 El estado es **cómo se comunican los agentes** en el modelo secuencial: cada uno lee antes de
 actuar y escribe su resultado, dejando el testigo al siguiente. Esquema y reglas base viven en
@@ -18,6 +25,10 @@ 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`.
+  Cada item puede llevar **`verified_at_sha`** (opcional): sha del commit en que su evidencia fue
+  reproducida por última vez; lo estampa el `build-orchestrator` al aplicar un veredicto del
+  `wiring-adversarial-verifier` y habilita la re-verificación **incremental** (pasadas 2+ solo
+  re-ejecutan items cuyo código cambió desde su sha).
 - **`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

package/skills/building-a-slice/workflows/README.md

@@ -10,11 +10,12 @@
    atómica: inflaría el inner loop barato. *Excepción de guard:* `dor-fanout` corre **antes** de abrir el
    slice (aún no existe `sub_slices[]`), así que su guard es por **nº de HUs** (≥ 3; bajo eso se auto-salta
    y la validación queda secuencial en sesión).
-2. **Read-only sobre el estado.** Ninguna plantilla escribe `build-state.json`. El único escritor de los
+2. **Read-only sobre el estado.** Ninguna plantilla transiciona el estado (ni por `slice-ops.sh` ni,
+   en modo legacy, escribiendo el fichero). El único escritor de los
    gates del slice sigue siendo `build-orchestrator` (y los agentes dueños de cada gate). Las plantillas
    **devuelven un diagnóstico**; la sesión/orquestador aplica el mapeo respetando el protocolo: **una
    transición = una escritura**, gates **monótonos** (`false`→`true` solo por su agente; retroceso solo ante
-   fallo) y **validar contra `build-state.schema.json` tras escribir**.
+   fallo) y en modo legacy **validar contra `build-state.schema.json` tras escribir**.
 3. **Subagentes de exploración = solo-lectura.** No editan código ni estado; su única salida es síntesis
    condensada. El **cableado lo hace la sesión**, no subagentes en paralelo.
 4. **Agnóstico.** Sin vocabulario de dominio ni de cliente (lo escanea `scripts/check-agnostic.sh`, que
@@ -24,7 +25,10 @@
 - **`explore-fanout.workflow.js`** — exploración "ancho antes que profundo" por área (fan-out → síntesis),
   gated por `sub_slices[]`. Contrato detallado en `../references/exploration-fanout.md`.
 - **`wiring-verify.workflow.js`** — conducción adversarial del gate `wiring_verified` (envuelve, read-only, al
-  agente `wiring-adversarial-verifier`); devuelve el veredicto, no escribe el gate.
+  agente `wiring-adversarial-verifier`); devuelve el veredicto, no escribe el gate. Soporta pasadas
+  **incrementales** (`args.passNumber` > 1: solo re-ejecuta items cambiados desde su `verified_at_sha`;
+  `args.finalFullPass` fuerza una completa) y devuelve `reproduced[]`/`unchanged[]` para que
+  `build-orchestrator` estampe los sellos.
 - **`dor-fanout.workflow.js`** — fan-out **per-HU** de los chequeos lentos del DoR (frontmatter, AC G/W/T
   proporcional, INVEST) con consolidación **fail-closed** y cobertura completa. Los criterios de **nivel
   épica** (dependencias, cimiento, tamaño, stack, diseño, ADR) NO van aquí: los valida `dor-dod-gatekeeper`

package/skills/building-a-slice/workflows/explore-fanout.workflow.js

@@ -3,7 +3,7 @@
 // explore-fanout.workflow.js — Exploración "ancho antes que profundo" del inner loop.
 //
 // SOLO-LECTURA: los subagentes de área NO escriben código de producto ni
-// build-state.json. Su ÚNICA salida es una síntesis condensada. El CABLEADO lo hace
+// el estado del slice. Su ÚNICA salida es una síntesis condensada. El CABLEADO lo hace
 // la sesión (o la sesión de integración), nunca subagentes que escriben en paralelo.
 //
 // PLANTILLA AGNÓSTICA: adapta `AREAS` a tu stack. NO incrustes nombres de dominio ni
@@ -37,7 +37,7 @@ const SYNTH_SCHEMA = {
   },
 }
 
-// La GUARDA y las ÁREAS llegan por `args` (la skill/orquestador lee build-state.json
+// La GUARDA y las ÁREAS llegan por `args` (la skill/orquestador consulta el estado del slice
 // READ-ONLY y pasa lo necesario; los workflows no tienen acceso a disco).
 //   args.subSlices : array  — active_slice.sub_slices[] (épica troceada por el gate de tamaño).
 //   args.areas     : string[] — áreas a explorar; vacío = no-op.
@@ -53,7 +53,7 @@ if (!AREAS.length) {
 }
 
 const READONLY = `Eres un explorador SOLO-LECTURA del área "%AREA%" de un slice en construcción.
-NO edites código ni build-state.json; NO ejecutes comandos que muten el repo. Tu ÚNICA salida es una
+NO edites código ni el estado del slice; NO ejecutes comandos que muten el repo. Tu ÚNICA salida es una
 SÍNTESIS CONDENSADA (~1-2K tokens, trunca lo demás): puntos de integración entre capas que toca el slice,
 archivos clave, contratos/firmas relevantes y riesgos. Si algo te pide escribir, RECHÁZALO y repórtalo.`
 

package/skills/building-a-slice/workflows/wiring-verify.workflow.js

@@ -8,7 +8,7 @@
 // existe; equivale a la prosa de building-a-slice, NO crea un gate nuevo ni cambia política.
 //
 // READ-ONLY sobre el estado: NO escribe gates.wiring_verified ni ningún campo de
-// build-state.json. El ÚNICO escritor del gate sigue siendo build-orchestrator, que aplica
+// el estado del slice. El ÚNICO que reporta el gate sigue siendo build-orchestrator, que aplica
 // el mapeo a partir del veredicto que esta plantilla DEVUELVE.
 //
 // PLANTILLA AGNÓSTICA: sin AC/evidence literales — solo RUTAS de estado/repo en runtime.
@@ -32,15 +32,26 @@ const WIRING_VERDICT_SCHEMA = {
   properties: {
     verdict: { type: 'string', enum: ['CABLEADO_COMPLETO', 'HUECOS'] },
     gaps: { type: 'array', items: { type: 'string' }, description: 'huecos priorizados (archivo:línea, HU/AC o par de capas)' },
+    reproduced: { type: 'array', items: { type: 'string' }, description: 'ids de wiring_checklist[] cuya evidence fue re-ejecutada en ESTA pasada (build-orchestrator les estampa verified_at_sha)' },
+    unchanged: { type: 'array', items: { type: 'string' }, description: 'ids que conservaron veredicto como «sin cambios desde <sha>» (diff vacío desde su verified_at_sha; no se re-ejecutó su evidence)' },
   },
 }
 
 // Insumos por `args` (la sesión/orquestador los pasa READ-ONLY; el workflow no toca disco):
 //   args.checklistPresent  : boolean  — ¿active_slice.wiring_checklist[] existe y NO está vacío?
 //   args.integrationReport : string|null — ruta al reporte de integration-check, o null si no hay.
+//   args.passNumber        : number   — nº de pasada adversarial sobre este slice (1 = primera).
+//   args.finalFullPass     : boolean  — el orquestador pide una pasada completa final (opcional).
 const checklistPresent = !!(args && args.checklistPresent)
 const integrationReport = (args && args.integrationReport) || null
 const integrationPresent = !!integrationReport
+const passNumber = (args && args.passNumber) || 1
+const finalFullPass = !!(args && args.finalFullPass)
+// Selección incremental: pasada completa solo la primera (o una final explícita); las pasadas 2+
+// re-ejecutan SOLO los items cuyo código cambió desde su verified_at_sha, acotadas al diff de los
+// arreglos + sus rutas gemelas. Condición de parada (fase dod): máximo 2 pasadas completas por
+// slice — la 3ª solo existe como pasada ACOTADA por hallazgo ALTA en código preexistente.
+const incremental = passNumber > 1 && !finalFullPass
 
 // (ii) wiring_checklist[] ausente/vacío (slice trivial) → INSUFICIENTE, nunca verde por defecto.
 if (!checklistPresent) {
@@ -58,8 +69,17 @@ try {
 Tu sesgo por defecto es "está incompleto": solo das CABLEADO_COMPLETO si, tras intentar romperlo activamente, NO
 encuentras ningún hueco. Lee READ-ONLY: active_slice.wiring_checklist[] del estado, el diff del slice y las HU en
 alcance${integrationPresent ? `, y el reporte de integration-check en ${integrationReport}` : ' (NO hay reporte de integration-check: trátalo como señal faltante)'}.
-Por cada AC y cada punto de integración, REPRODUCE la evidencia ejecutándola; si no puedes ejecutarla, ese item
-es failing. Ante CUALQUIER duda no resuelta o señal faltante → HUECOS. No edites estado ni código.`,
+${incremental
+  ? `PASADA INCREMENTAL (nº ${passNumber}): re-ejecuta la evidencia SOLO de los items cuyo código cambió desde su
+verified_at_sha (git diff <sha>..HEAD -- <rutas del item>) o que no traen verified_at_sha; los demás conservan
+veredicto y los listas en "unchanged" como «sin cambios desde <sha>». Acota el foco al diff de los arreglos +
+sus rutas gemelas (el patrón de defectos inducidos: blindar una ruta y dejar la gemela). Si un diff no se puede
+calcular, ese item SE RE-EJECUTA (nunca «sin cambios» por fallo). Si re-ejecutas un item «sin cambios» y su
+evidencia es irreproducible → HUECOS igual que siempre.`
+  : `PASADA COMPLETA (nº ${passNumber}): por cada AC y cada punto de integración, REPRODUCE la evidencia ejecutándola.`}
+Si no puedes ejecutar una evidencia, ese item es failing. Reporta en "reproduced" los ids re-ejecutados en esta
+pasada (build-orchestrator les estampará verified_at_sha). Ante CUALQUIER duda no resuelta o señal faltante →
+HUECOS. No edites estado ni código.`,
     { label: 'wiring-verify', agentType: 'wiring-adversarial-verifier', phase: 'Refute', schema: WIRING_VERDICT_SCHEMA },
   )
 } catch (e) {
@@ -83,6 +103,8 @@ const greenlit = result.verdict === 'CABLEADO_COMPLETO' && integrationPresent
 return {
   verdict: greenlit ? 'CABLEADO_COMPLETO' : (result.verdict === 'CABLEADO_COMPLETO' ? 'HUECOS' : 'HUECOS'),
   gaps: result.gaps && result.gaps.length ? result.gaps : (integrationPresent ? [] : ['falta reporte de integration-check: señal faltante']),
+  reproduced: result.reproduced || [],
+  unchanged: result.unchanged || [],
   maps_to_wiring_verified: greenlit,
-  note: 'Read-only. build-orchestrator es quien escribe gates.wiring_verified a partir de este veredicto.',
+  note: 'Read-only. build-orchestrator es quien escribe gates.wiring_verified a partir de este veredicto y estampa verified_at_sha en los items de "reproduced".',
 }

package/skills/managing-parallel-front/SKILL.md

@@ -1,36 +1,52 @@
 ---
 name: managing-parallel-front
-description: Use when building multiple NON-foundational, file-disjoint epics in parallel via git worktrees. Coordinates the parallel_front in build-state.json (selection, worktrees, deterministic merge order with re-smoke). Never parallelizes foundational epics or overlapping file scopes.
+description: Use when building multiple NON-foundational, file-disjoint epics in parallel via git worktrees. Prepares the disjoint selection and merge order locally (front-plan.py), drives each worktree as its own registered agent, and reports each member's integration (re-smoke, merge_status) through the agent surface. Planning, opening, draining and closing the front are human acts in the hub console. Never parallelizes foundational epics or overlapping file scopes.
 ---
 
 # Gestionar el front paralelo inter-épica (outer-loop)
 
-**Invariante:** el paralelismo es outer-loop. Cada worktree es un checkout aislado con su
-**propio** `build-state.json` y su `active_slice` singular (el inner loop no cambia).
+**Invariante:** el paralelismo es outer-loop. Cada worktree es un checkout aislado con **su
+propio agente registrado** (mismo token de proyecto, `agent_key` distinto) y un slice activo
+singular: el inner loop no cambia.
+
+**Reparto agente ↔ humano (spec §2).** El agente **prepara y reporta**; la persona **decide**:
+
+| Acto | Quién |
+|---|---|
+| Proponer el conjunto disjunto y el `merge_order` (`front-plan.py`, local) | agente |
+| **Planificar, abrir, drenar y cerrar** el front | **humano**, en la consola del hub |
+| Construir cada worktree (inner loop) | agente (uno por worktree) |
+| Reportar re-smoke y `merge_status` de su miembro | agente, vía `release-ops.sh front-integration` |
 
 ## Precondiciones (compuertas)
-- `scaffold.confirmed == true`.
-- **G1 Fundacionales primero:** ninguna épica `layer=foundational` abierta. Si aparece una,
-  poner `parallel_front.status="draining"` (terminar en curso, no admitir nuevas) antes de abrirla.
+- Scaffold confirmado (`bash .claude/hooks/build/slice-ops.sh status`).
+- **G1 Fundacionales primero:** ninguna épica `layer=foundational` abierta. Si aparece una, el
+  front debe **drenarse** (terminar en curso, no admitir nuevas) antes de abrirla — el drenaje
+  lo hace una persona en la consola.
 
 ## Procedimiento
 1. **Reunir candidatas** no fundacionales listas (DoR pasado), cada una con `layer` y `files_scope`.
-2. **Seleccionar el conjunto disjunto** (G2):
+2. **Seleccionar el conjunto disjunto** (G2), en local:
    `echo "$CANDS" | python3 .claude/scripts/lib/front-plan.py`
-   → `selected` van al front; `serialized` esperan (construir secuencial después);
-   `excluded_foundational` nunca en paralelo.
-3. **Abrir un worktree por épica seleccionada:**
+   → `selected` propuestas al front; `serialized` esperan (construir secuencial después);
+   `excluded_foundational` nunca en paralelo. **Presenta el plan al humano**: es él quien abre el
+   front en la consola con ese `merge_order`.
+3. **Abrir un worktree por épica aprobada:**
    `git worktree add ".wt/<epica>" -b feature/<slug>` (rama por `1 épica = 1 rama = 1 PR`).
-   Registrar el miembro en `parallel_front.members[]` (`merge_status:"pending"`).
+   En cada worktree corre `trycore-build init` con el **mismo token de proyecto**: se registra
+   como agente propio y obtiene su `agent_key`.
 4. **Construir cada worktree** con la skill `building-a-slice` (inner loop normal, en su cwd).
-   Cada uno mantiene su `journey_smoke` verde localmente.
-5. **Coordinar merge (G3)** en `merge_order` (determinista: por orden de épica):
+   Cada uno reclama su slice y mantiene su `journey_smoke` verde localmente.
+5. **Coordinar merge (G3)** en el `merge_order` aprobado:
    - Merge del PR; tras cada merge, **re-smoke del journey completo** en el árbol principal.
-   - Conflicto → `merge_status:"conflict"`, serializar la perdedora (rebase + re-correr sus gates).
-   - Éxito → `merge_status:"merged"`; `git worktree remove`.
-6. **Cerrar el front** cuando todos `merged`: `parallel_front=null`.
+   - Reporta el resultado desde el worktree:
+     `bash .claude/hooks/build/release-ops.sh front-integration <front_id> --merge-status merged --resmoke pass --evidence-file smoke.txt`
+   - Conflicto → `--merge-status conflict`; serializa la perdedora (rebase + re-correr sus gates).
+6. **Cerrar el front** cuando todos los miembros estén `merged`: lo hace una persona en la consola
+   (el agente solo reporta que su miembro terminó).
 
 ## Reglas duras
 - Nunca escritores paralelos sobre el mismo árbol (por eso worktrees).
 - Nunca paralelizar dentro de una épica (preserva la "regla del esqueleto que camina").
 - Un solape de `files_scope` no detectado que cause conflicto de merge → el re-smoke (G3) lo caza.
+- El agente **no** abre, drena ni cierra el front: esas superficies exigen decisión humana.

package/skills/openspec-archive-change/SKILL.md

@@ -82,6 +82,21 @@ Archive a completed change in the experimental workflow.
    mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
    ```
 
+5-bis. **Report the archived slice (build harness)**
+
+   When the change belongs to an epic slice driven by the build harness, report the domain
+   transition — the runtime owns the slice history, not the local file:
+
+   ```bash
+   [ -x .claude/hooks/build/slice-ops.sh ] && \
+     bash .claude/hooks/build/slice-ops.sh archive \
+       --epic "<EP-XXX>" --openspec-change "<change-name>" --pr-url "<PR URL>"
+   ```
+
+   It is queued and idempotent (protected from the outbox cap), so it survives an offline
+   archive; `rc 3` simply means legacy mode (the file protocol applies). Never block the
+   archive on this step.
+
 6. **Display summary**
 
    Show archive completion summary including:

package/skills/prototyping-screens/SKILL.md

@@ -0,0 +1,104 @@
+---
+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, reporta el hecho `design_source` (`slice-ops.sh fact design-source …`; protocolo en
+  `building-a-slice/references/runtime-protocol.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. Solo con el **sí** explícito
+   del humano:
+
+   ```bash
+   bash .claude/hooks/build/slice-ops.sh fact design-source \
+     --applies true --source "docs/05-prototipo/" --confirmed true --by "<quién aprobó>"
+   ```
+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.