@trycore/spec-build-harness 0.8.1 → 0.8.3

package/docs/runtime/plan-migracion-harness-v0.9.md

@@ -0,0 +1,84 @@
+# Plan de migración — Harness v0.9: de archivos estáticos a cliente del Agent Orchestrator Runtime
+
+> Repo: `trycore-spec-build-harness` (v0.8.1 → v0.9.0). Contraparte servidor: módulo `orchestrator` de **trycore-ia-hub** (PRD Agent Orchestrator Runtime v2.1, ADR-0012 del hub, épica EP-OR-08). Contrato de red: [protocolo-cliente-runtime.md](protocolo-cliente-runtime.md).
+>
+> **Principio rector:** la metodología no cambia — cambia el medio. Los dos loops, las fases, los gates y los veredictos son los mismos; lo que se moviliza es *dónde vive el estado* (del JSON local al runtime) y *quién valida las transiciones* (del prompt/honor system al servidor). Regla de corte: **hechos y transiciones de dominio → runtime · observación y enforcement del working tree → harness · protocolo de estado → cliente API.**
+
+## 1. Matriz de movilización por artefacto
+
+### 1.1 Estado (`state/`)
+
+| Artefacto v0.8.1 | Acción en v0.9 | Detalle |
+|---|---|---|
+| `state/build-state.json` | **RETIRAR** (tras modo dual) | Sustituido por el runtime. Queda solo `state/context.lock` (lockfile del plano de contexto) y un caché de proyección de solo lectura para modo offline. |
+| `state/build-state.schema.json` + `state/README.md` | **RETIRAR** | La validación es server-side. El README se reescribe: "el estado vive en el runtime; esto es el caché". |
+| `state/build-state.template.json` | **RETIRAR** | `init` ya no siembra estado: registra el proyecto/agente en el runtime. |
+| Reglas de `reconcile-build-state.py` (evidence, ratchet, drift) | **MOVILIZAR** a reducers del runtime | La *observación* local (rama git real vs branch del slice) queda en un reporter que emite evento `branch_drift`. El script local desaparece. |
+
+### 1.2 Hooks (`hooks/build/`)
+
+| Hook | Acción | Detalle |
+|---|---|---|
+| `load-build-state.sh` (SessionStart) | **REESCRIBIR** como cliente | Hidrata desde `GET /agent/context` (registro + slice activo + gates + resume_hint + `manifest_hash`); dispara sync de contexto; escribe caché local. Mantiene la inyección de `additionalContext` (mecánica Claude Code intacta). |
+| `context-monitor.sh` + `statusline-bridge.sh` | **CONSERVAR + extender** | Umbral/statusline siguen locales. El handoff crítico además emite `POST /events` tipo `handoff_recorded`. La statusline muestra versión de contexto (`✓ v14` / `⚠ stale`). Corregir de paso el fallback cross-sesión (`ls /tmp/claude-ctx-*.json | head -1`). |
+| `gitflow-guard.sh` | **CONSERVAR**; política desde el runtime | Mismo bloqueo PreToolUse con latencia cero; la política (ramas tipadas, rama de integración) se lee del asset `POLICY` sincronizado — muere la contradicción plugin vs CLAUDE.md del proyecto. |
+| `stack-guard.sh` | **CONSERVAR**; allowlist desde el runtime | Sigue leyendo `.claude/config/stack-allowlist.json`, pero ese archivo ahora lo escribe el sync de contexto, no un humano. |
+| `scaffold-guard.sh` / `design-source-guard.sh` | **CONSERVAR**; hechos desde el runtime | `scaffold.confirmed`/`design_source`/fase se leen del caché de proyección (refrescado en claim/SessionStart), no de un JSON por-clon. |
+| `lint-typecheck.sh`, `coherence-flag.sh` | **CONSERVAR sin cambios** | 100% locales al working tree. |
+| `build-gate-check.sh`, `reflect-nudge.sh`, `release-gate-nudge.sh` (Stop) | **ADELGAZAR** | La aritmética se moviliza al runtime; el hook renderiza `GET /nudges` (con caché). Hoy computan sobre estado parcial por-clon — 31/33 slices sin `reflected` demuestran su ineficacia. |
+| **NUEVOS** | `heartbeat` (renovación de lease, intervalo < ⅓ TTL), `event-emitter` (PostToolUse → cola local → `POST /events` en lote idempotente), `context-sync` (pre-claim y SessionStart, por hash) | Telemetría como propiedad del harness, imposible de omitir por el modelo. |
+| `hooks/build/lib/state-io.sh` | **RETIRAR** | Sin archivo de estado, sin read-modify-write. Nace `lib/runtime-client.sh` (curl + token + cola offline). |
+
+### 1.3 Skills, commands y agentes
+
+| Artefacto | Acción | Detalle |
+|---|---|---|
+| `building-a-slice` | **REESCRIBIR el protocolo, conservar la inteligencia** | Fases/gates los dicta el claim (`GET /tasks/next` devuelve fase y siguiente paso); la skill conduce TDD/cableado como hoy. Toda escritura de estado se sustituye por `POST /verdicts|/checkpoints|/events`. `references/state-protocol.md` se reemplaza por `references/runtime-protocol.md`. |
+| `releasing-a-version` | **REESCRIBIR protocolo** | Los 6 veredictos se reportan; el runtime agrega ("parciales no promueven") y cierra `PENDING→PASSED/FAILED`. |
+| `managing-parallel-front` + `scripts/lib/front-plan.py` | **MOVILIZAR el plan al runtime; la skill queda como conductora local** | La selección disjunta, `merge_order` y `merge_status` viven en el runtime (la spec interna 2026-07-03 ya pedía "front-planner: código, no criterio libre del modelo"). La skill abre worktrees y conduce; cada worktree reporta solo. |
+| `/build:resume` | **ADELGAZAR** | Su prioridad determinista (resume_hint → wiring failing → sub_slice → fase) ES `GET /tasks/next`. El command queda como envoltorio. |
+| `/build:work`, `/build:slice`, `/build:release`, `/build:front`, `/build:onboard`, `/build:reflect` | **CONSERVAR**, protocolo API | `/build:onboard` además **persiste** el grafo (épicas, dependencias, layer, files_scope) vía API en lugar de solo frontmatter. Nuevos: `/build:claim`, `/build:status` (flota), `/build:escalate`. |
+| Agentes de veredicto (`dor-dod-gatekeeper`, `wiring-adversarial-verifier`, `stack-guardian`, reviewers, etc.) | **CONSERVAR intactos** | Siguen emitiendo veredictos; solo cambia el destino (API, no JSON). El contrato de degradación segura lo impone ahora el servidor. |
+| Skills `openspec-*` | **CONSERVAR**; enlazar | Los artefactos siguen en git. El slice del runtime referencia `openspec_change`; `opsx:archive` dispara además la transición `slice_archived`. |
+| Workflows `*.workflow.js` | **CONSERVAR** | Read-only; sus resultados se reportan como eventos. |
+
+### 1.4 Setup nuevo: generación de documentos de arquitectura (previsto)
+
+La skill futura `setup-architecture` (estilo de arquitectura, patrones de diseño detallado, stack tecnológico, …) nace ya sobre el modelo v0.9: el paquete declara sus **Asset Type Descriptors** en `asset-types.json` (ver protocolo §6); la skill genera los `.md` y los **propone** vía API (nunca publica). Cualquier documento tipado futuro sigue este mismo camino sin tocar el frontend del hub.
+
+### 1.5 CLI (`trycore-build`) e instalación
+
+| Pieza | Acción |
+|---|---|
+| `init` | Reescribir: pide URL del runtime + token de proyecto (emitido por un ADMIN en el hub), registra el agente, ejecuta el primer sync de contexto. Sigue sembrando settings/hooks/CLAUDE.md markers (bootstrap local legítimo). |
+| `doctor` | Extender: conectividad al runtime, validez del token, frescura del lock de contexto, drift local. |
+| `status` | Reescribir sobre `GET /agent/context` + `/nudges`. |
+| `state-seed.ts` | Retirar (política [C1] ya no aplica: no hay archivo que proteger). |
+| `sync-trycore-assets.sh` (en los repos consumidores) | **RETIRAR** — razón de ser eliminada por el plano de contexto. |
+| `check-state-clean.sh` | Simplificar: ya no hay `state/` con artefactos vivos que perseguir. |
+
+## 2. Modo dual y corte (sin big-bang)
+
+1. **v0.9.0-beta (dual):** los hooks escriben a la API **y** mantienen `build-state.json` como espejo de solo escritura (nunca se lee). Flag `TRYCORE_RUNTIME_MODE=dual|runtime|legacy` en `build-config`. Piloto: `diagramador-ia-for-process`.
+2. **Import histórico:** script one-shot que convierte el `build-state.json` del piloto (33 slices en `history[]`, 6 releases, con sus irregularidades conocidas: fase `parked`, clave `release`, gates `null`) en eventos del runtime. Las entradas no mapeables se importan como eventos `legacy_imported` con payload original — nada se pierde, nada bloquea.
+3. **Corte (`runtime`):** tras 1 sprint del piloto sin discrepancias (comparador dual espejo vs proyección), se elimina la escritura local. `legacy` queda solo como escape documentado durante la beta y se retira en v0.9.0 final.
+4. **Matriz de compatibilidad:** el runtime rechaza `harness_version` < 0.9.0 para proyectos ya migrados; v0.8.x sigue funcionando en proyectos no migrados (el plugin no rompe a nadie).
+
+## 3. Checklist de aceptación de v0.9.0
+
+- [ ] Cero lecturas/escrituras de `build-state.json` en modo `runtime` (grep de CI sobre hooks/skills, análogo a `check-agnostic.sh`).
+- [ ] Un clon fresco llega a "primer claim con contexto completo" en < 1 min con solo `init` + token.
+- [ ] Matar la sesión a mitad de slice ⇒ lease expira ⇒ otro agente continúa desde el checkpoint (test E2E contra runtime de staging).
+- [ ] Guards funcionan offline con el último lock (`⚠ stale` visible); eventos encolados se entregan al reconectar, idempotentes.
+- [ ] Los 4 guards bloqueantes conservan latencia local (sin red en el camino de PreToolUse).
+- [ ] Import histórico del piloto reproduce `history[]`/`releases[]` como proyecciones consultables.
+- [ ] `asset-types.json` del paquete se registra en el runtime al primer agente (tipos aditivos auto-publicados).
+
+## 4. Riesgos propios de la migración
+
+| Riesgo | Mitigación |
+|---|---|
+| Latencia de red en hooks de camino caliente | Solo `heartbeat`/`event-emitter` tocan red y son asíncronos con cola local; PreToolUse jamás llama a la API. |
+| Runtime caído a mitad de sprint | Modo degradado (RNF-6 del PRD): último lock + cola de eventos; el trabajo local nunca se bloquea — degrada exactamente a la situación v0.8.1. |
+| Divergencia dual (espejo ≠ proyección) durante la beta | Comparador automático en el hook Stop; discrepancia = issue bloqueante del corte. |
+| Deriva de versiones en la flota | El registro reporta `harness_version`; el runtime la exige en matriz; el tablero muestra la versión por agente. |

package/docs/runtime/protocolo-cliente-runtime.md

@@ -0,0 +1,116 @@
+# Protocolo cliente — Harness v0.9 ↔ Agent Orchestrator Runtime
+
+> Contrato del lado cliente. El contrato del lado servidor vive en trycore-ia-hub: `docs/01-prd/anexos/orchestrator-runtime-design.md` (§4 catálogo de eventos, §5 API). Este documento define cómo el harness lo consume: autenticación, mapeo hook→endpoint, sincronización de contexto, cola offline y declaración de tipos de asset.
+
+## 1. Autenticación y arranque
+
+- **Token de proyecto:** emitido por un ADMIN en el hub, entregado al desarrollador, configurado una vez con `trycore-build init` (se guarda en `.claude/state/runtime.credentials`, fuera de git, `0600`). Todas las llamadas: `Authorization: Bearer <token>`.
+- **Registro:** `POST /agents/register {harness_version, capabilities}` → `{agent_id, project, manifest_hash, poll_interval_s, lease_ttl_s}`. Los intervalos los dicta el servidor (el cliente no los hardcodea). `409 incompatible_version` ⇒ mensaje claro con la versión mínima requerida.
+- **Identidad local:** `agent_id` persiste en `.claude/state/runtime.credentials`; un mismo clon re-registrado reactiva su agente (no crea otro).
+
+## 2. Mapeo hook → endpoint (la telemetría es del harness, no del modelo)
+
+| Evento Claude Code | Hook v0.9 | Llamada | Notas |
+|---|---|---|---|
+| SessionStart (`startup\|clear\|compact`) | `session-start.sh` | `POST /agents/register` (idempotente) + `GET /agent/context` + sync de contexto (§4) | Inyecta `additionalContext`: slice activo, fase, gates abiertos, wiring failing, resume_hint, nudges, versión de contexto. |
+| PostToolUse (`Edit\|Write\|MultiEdit\|Bash\|Task`) | `event-emitter.sh` | encola → `POST /events` (lote) | **Nunca síncrono en el camino del tool.** Encola en `.claude/state/outbox/` y despacha en background (ver §5). |
+| Timer / PostToolUse throttled | `heartbeat.sh` | `PUT /leases/renew` | Intervalo = `lease_ttl_s / 3` (valor del servidor). |
+| PreCompact / Stop con contexto crítico | `context-monitor.sh` | evento `handoff_recorded {stopped_at, resume_hint}` | Además del aviso local existente. |
+| Stop | `session-stop.sh` | flush de outbox + `GET /nudges` (cacheado) | Renderiza nudges del servidor; sin aritmética local. |
+| PreToolUse (guards) | `gitflow/stack/scaffold/design-source-guard.sh` | **ninguna** (prohibido red en PreToolUse) | Leen archivos sincronizados + caché de proyección local. |
+
+Eventos emitidos por skills (no por hooks): `POST /checkpoints` (tras cada commit significativo), `POST /slices/{id}/verdicts` (al recibir el veredicto de un agente revisor), `POST /slices/{id}/submit` (entrega), `GET /tasks/next` (claim).
+
+## 3. Claim (el corazón del pull)
+
+```
+GET /tasks/next
+  200 → {slice_id, epic, phase, next_step, branch_base, acceptance_refs,
+         openspec_change, lease: {ttl_s, expires_at}, manifest_hash,
+         checkpoint: {branch, commit_sha} | null}
+  204 → sin trabajo disponible (la skill lo comunica y termina limpio)
+  409 → carrera perdida (otro agente reclamó primero): reintentar una vez
+```
+
+Reglas del cliente:
+
+1. Antes de trabajar: verificar `manifest_hash` contra el lock (§4); sincronizar si difiere. **No se abre trabajo con contexto viejo.**
+2. Si `checkpoint != null`: hacer checkout/pull de la rama y **continuar desde el checkpoint, jamás reiniciar** (recuperación de otro agente caído).
+3. En el claim se reportan los sha256 locales efectivos de los archivos gobernados (allowlist, policy, rules) — el servidor detecta drift/manipulación local.
+4. Un agente mantiene **un solo** slice activo; `GET /tasks/next` con lease vigente devuelve el mismo slice (idempotencia).
+
+## 4. Sincronización de contexto (content-addressed)
+
+Lockfile: `.claude/state/context.lock`
+
+```jsonc
+{
+  "manifest_hash": "sha256:…",
+  "synced_at": "2026-08-04T…Z",
+  "files": [{"path": "config/stack-allowlist.json", "type_key": "core.library_allowlist", "sha256": "…", "version": 7}]
+}
+```
+
+Algoritmo (`context-sync.sh`, corre en SessionStart y pre-claim):
+
+1. Comparar `manifest_hash` esperado (del registro o del claim) con el del lock. Igual ⇒ fin (costo: comparación de strings).
+2. Distinto ⇒ `GET /projects/{id}/context/manifest`; diff por `sha256` archivo a archivo; `GET /context/files/{path}?sha256=…` **solo** de los cambiados (ETag inmutable ⇒ cacheable).
+3. Escritura atómica (`mktemp` + `os.replace`, patrón ya probado en v0.8.1) sobre los destinos gobernados: `config/`, `rules/`, bloques marcados de `CLAUDE.md` (vía `markers.ts`), `docs-cache/` para `DOC`.
+4. Actualizar el lock; emitir `context_synced {from_hash, to_hash, files_changed[]}`; aviso de una línea al usuario (`⬆ contexto v13 → v14: allowlist (+2), PRD §4`).
+5. **Prohibido** editar a mano archivos gobernados: el sync los sobreescribe y el drift se reporta. El cambio legítimo se hace en el hub (propuesta→publicación).
+
+Offline: sin runtime, se trabaja con el último lock; la statusline marca `⚠ stale`; al reconectar, sync antes del siguiente claim.
+
+## 5. Cola offline de eventos (`.claude/state/outbox/`)
+
+- Un archivo JSON por lote, con `client_event_id` (UUID) por evento ⇒ **idempotencia server-side** (reintentos seguros).
+- Despacho en background con backoff (1 s → 5 s → 30 s → 5 min, tope); orden FIFO por agregado.
+- Cota: 5 MB / 72 h — al superarla se descartan primero los eventos de telemetría fina (PostToolUse), **nunca** checkpoints, veredictos ni submits; el descarte se reporta como evento `telemetry_gap` al reconectar.
+- Flush forzado en Stop y en `trycore-build doctor`.
+
+## 6. Declaración de tipos de asset (`asset-types.json` del paquete)
+
+El paquete del plugin declara los tipos de documento que sabe generar. En el registro, el runtime hace upsert idempotente (aditivos auto-publicados; breaking quedan propuestos para un ADMIN):
+
+```jsonc
+{
+  "meta_schema_version": 1,
+  "types": [
+    {
+      "type_key": "arch.style",
+      "title": "Estilo de arquitectura",
+      "category": "Arquitectura",
+      "content_format": "markdown+frontmatter",
+      "frontmatter_schema": {"type": "object", "properties": {"style": {"type": "string"}, "drivers": {"type": "array", "items": {"type": "string"}}}, "required": ["style"]},
+      "body_sections": [
+        {"id": "decision", "title": "Estilo elegido", "required": true},
+        {"id": "rationale", "title": "Justificación", "required": true},
+        {"id": "consequences", "title": "Consecuencias", "required": false}
+      ],
+      "cardinality": "single",
+      "generation": {"source": "plugin", "skill": "setup-architecture"},
+      "descriptor_version": 1
+    }
+    // arch.patterns, stack.profile, …
+  ]
+}
+```
+
+Las skills generadoras producen la instancia y la **proponen**: `POST /projects/{id}/context/proposals {type_key, path, frontmatter, body}` — validada server-side contra el `frontmatter_schema`; la publica un ADMIN en el hub. Un agente jamás publica contexto.
+
+## 7. Errores y degradación (tabla normativa)
+
+| Situación | Comportamiento del cliente |
+|---|---|
+| `401/403` (token inválido/revocado) | Detener claims; mensaje accionable ("pide un token nuevo al ADMIN"); guards siguen operando con el último lock. |
+| `409` en claim | Un reintento inmediato; luego informar "otro agente tomó la tarea" y pedir la siguiente. |
+| `422` (evento/veredicto rechazado por transición ilegal o schema) | **No reintentar**: mostrar la razón del servidor al modelo/usuario (compuerta mecánica funcionando); registrar localmente. |
+| Timeout/red caída | Modo offline (§4/§5); jamás bloquear PreToolUse ni el trabajo local. |
+| `410` en lease (expirado durante trabajo largo) | El slice pudo ser re-entregado: detener, hacer checkpoint local, re-claim (puede devolver el mismo slice si nadie lo tomó). |
+| Reloj local desviado | El cliente usa siempre `expires_at` del servidor, nunca calcula TTL con reloj propio. |
+
+## 8. Seguridad del cliente
+
+- El token vive solo en `.claude/state/runtime.credentials` (gitignoreado, `0600`); nunca en `settings.json` ni en el repo — no repetir el incidente de rutas/credenciales de máquina fosilizadas en `settings.json`.
+- El harness no envía código fuente al runtime: solo referencias git, hashes, veredictos y metadatos (los payloads se validan contra schema; el servidor rechaza payloads sobredimensionados).
+- `trycore-build doctor` verifica: token válido, reloj razonable, lock fresco, outbox drenando, hashes sin drift.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trycore/spec-build-harness",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "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": {
@@ -16,6 +16,7 @@
     "config/",
     "state/",
     "templates/",
+    "asset-types.json",
     "internal/",
     "docs/",
     "!docs/superpowers",

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

@@ -12,6 +12,14 @@ la épica; lo de abajo aplica a la épica y a **cada HU** que cubre (`hus[]`). L
 - [ ] **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.
 - [ ] **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
+  arquitectura (existe `docs/adr/_backlog-arquitectonico.md`, de `/build:architect`), los drivers
+  arquitecturalmente significativos que la épica ejerce tienen un ADR con estado ≥ `ABORDADO`. El join
+  épica↔driver es por la columna **Trazabilidad (EP/HU)** del tablero del backlog (fallback: la columna
+  Trazabilidad del `0000`). **Duro para épicas `layer: foundational`** (auth/datos/arquitectura
+  base/design-system): sin ADR que cubra su cimiento → **STOP**, corre `/build:architect` primero. Para
+  `layer: business` es advertencia si algún driver sigue `PENDIENTE`. Sin `docs/adr/` (proyecto sin la
+  capa) → **N/A** (no bloquea; sugiere la capa).
 - [ ] **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

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

@@ -7,7 +7,9 @@
 ## Reglas duras (todas las plantillas las cumplen)
 1. **Solo para épicas grandes.** Los workflows del inner loop son **OPT-IN** y solo para épicas troceadas por
    el gate de tamaño (`sub_slices[]` no vacío). **Nunca** en el camino caliente ≤ ~20 min de una épica
-   atómica: inflaría el inner loop barato.
+   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
    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
@@ -23,3 +25,7 @@
   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.
+- **`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`
+  en sesión, que combina ambos y es el único que emite el veredicto DoR. Guard: ≥ 3 HUs.

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

@@ -0,0 +1,98 @@
+// =============================================================================
+// PLANTILLA — referencia, NO un script a correr verbatim.
+// dor-fanout.workflow.js — Fan-out de los chequeos PER-HU del DoR (inner loop).
+//
+// QUÉ PARALELIZA (y qué NO): SOLO los criterios del DoR que son por-HU e independientes
+// entre sí — frontmatter completo + estado:lista, AC en Given/When/Then proporcional a
+// `complejidad`, e INVEST. Los criterios de NIVEL ÉPICA (trazabilidad de la épica,
+// dependencias en history[], cimiento construido, gate de tamaño, stack/allowlist,
+// fuente de diseño, cobertura de ADR) NO van aquí: los valida dor-dod-gatekeeper en
+// sesión — necesitan estado y son baratos. Este workflow ataca lo LENTO: O(HUs) → O(1).
+//
+// READ-ONLY sobre el estado: NO escribe gates.dor ni abre active_slice. El ÚNICO que
+// abre el slice sigue siendo dor-dod-gatekeeper, que COMBINA este diagnóstico per-HU
+// con sus criterios de épica y emite el veredicto DoR completo.
+//
+// CUÁNDO: SOLO con ≥ 3 HUs (bajo eso el fan-out no paga su overhead y el inner loop
+// debe seguir barato). Consolidación FAIL-CLOSED con cobertura COMPLETA: una HU
+// fallida o un shard ausente = DoR per-HU false, nunca muestreo silencioso.
+//
+// PLANTILLA AGNÓSTICA: sin vocabulario de dominio/cliente (scripts/check-agnostic.sh
+// escanea *.js). Si METODOLOGIA.md (§3.1) contradice algo aquí, gana la metodología.
+//
+// RUNTIME: corre en el runtime de Workflow de Claude Code, que provee los globals
+// agent()/parallel()/pipeline()/phase()/log()/args y envuelve el cuerpo en un contexto
+// async (por eso usa `await` y `return` a nivel superior). NO es un módulo node standalone.
+// =============================================================================
+
+export const meta = {
+  name: 'dor-fanout',
+  description: 'Fan-out per-HU de los chequeos del DoR (frontmatter, AC G/W/T proporcional, INVEST) con consolidación fail-closed. Read-only; dor-dod-gatekeeper combina el diagnóstico y emite el veredicto.',
+  phases: [{ title: 'HUs', detail: 'un validador solo-lectura por HU, en paralelo' }],
+}
+
+const HU_CHECK_SCHEMA = {
+  type: 'object', additionalProperties: false,
+  required: ['hu', 'pass', 'faltantes'],
+  properties: {
+    hu: { type: 'string' },
+    pass: { type: 'boolean', description: 'true SOLO si los 3 bloques (frontmatter, AC, INVEST) están completos y verificados' },
+    faltantes: { type: 'array', items: { type: 'string' }, description: 'cada criterio incumplido, con detalle accionable' },
+  },
+}
+
+// Insumos por `args` (dor-dod-gatekeeper los pasa READ-ONLY; el workflow no decide alcance):
+//   args.epica  : string   — ID de la épica (solo para el reporte).
+//   args.hus    : string[] — IDs de las HU en alcance (hus[] del slice candidato).
+//   args.husDir : string   — directorio de las HU (default 'docs/04-historias').
+const epica = (args && args.epica) || '<EP-XXX>'
+const hus = (args && Array.isArray(args.hus)) ? args.hus.filter(Boolean) : []
+const husDir = (args && args.husDir) || 'docs/04-historias'
+
+// Guard de tamaño: bajo 3 HUs el fan-out no paga su overhead → el gatekeeper valida
+// secuencial en sesión (comportamiento previo). Espeja el guard de explore-fanout.
+if (hus.length < 3) {
+  log(`Épica ${epica} con ${hus.length} HU(s): fan-out no amortiza — validación secuencial en sesión.`)
+  return { skipped: true, reason: 'pocas-hus', hus_count: hus.length }
+}
+
+phase('HUs')
+log(`DoR per-HU: fan-out de ${hus.length} HUs de ${epica} (cobertura completa, sin muestreo)`)
+const checks = await parallel(hus.map((hu) => async () => {
+  try {
+    const v = await agent(
+      `Eres un validador SOLO-LECTURA del DoR para UNA SOLA historia de usuario: ${hu} (épica ${epica}).
+Lee ${husDir}/${hu}.md y verifica EXACTAMENTE estos 3 bloques (nada de nivel épica):
+1. FRONTMATTER completo: id, titulo, epica, prioridad, complejidad, estado — y estado: lista.
+2. AC en Given/When/Then PROPORCIONAL a complejidad: trivial/baja → 1-2 (happy + error/edge crítico si
+   existe); media → 3 (happy + error + edge); alta → 3-5 (cobertura completa). Regla dura: toda rama de
+   error/edge que exista DEBE tener su escenario; NO exijas cuota fija a una HU trivial.
+3. INVEST: evalúa tú mismo los 6 criterios (Independent, Negotiable, Valuable, Estimable, Small, Testable).
+pass:true SOLO si los 3 bloques cumplen. Cada incumplimiento va en faltantes[] con detalle accionable
+(qué campo/escenario/criterio y por qué). Si el archivo no existe o es ilegible → pass:false con el motivo.
+NO edites nada; NO valides otras HU ni criterios de épica.`,
+      { label: `dor:${hu}`, phase: 'HUs', agentType: 'Explore', schema: HU_CHECK_SCHEMA },
+    )
+    if (!v) return { hu, pass: false, faltantes: [`${hu}: sin veredicto`] }
+    return { hu, pass: v.pass === true, faltantes: v.faltantes || [] }
+  } catch (e) {
+    return { hu, pass: false, faltantes: [`${hu}: el validador falló — revalidar en sesión`] }
+  }
+}))
+
+// Consolidación FAIL-CLOSED + cobertura completa: shard ausente = hueco, nunca verde.
+const done = checks.filter(Boolean)
+const missing = hus.length - done.length
+const bad = done.filter((c) => !c.pass)
+const all_pass = bad.length === 0 && missing === 0
+
+return {
+  epica,
+  all_pass,                       // pass per-HU; NO es el DoR completo (falta el nivel épica)
+  hus: done,                      // diagnóstico por HU para el reporte ✓/✗ del gatekeeper
+  faltantes: [
+    ...bad.flatMap((c) => c.faltantes),
+    ...(missing > 0 ? [`${missing} HU(s) sin resultado — cobertura incompleta, revalidar en sesión`] : []),
+  ],
+  note: 'Read-only. dor-dod-gatekeeper combina esto con los criterios de NIVEL ÉPICA (dependencias, cimiento, tamaño, stack, diseño, ADR) y es el único que emite el veredicto DoR y abre active_slice.',
+}

package/skills/releasing-a-version/SKILL.md

@@ -48,7 +48,7 @@ Ver `workflows/README.md`. Hoy: `workflows/release-gate.workflow.js`.
 | `smell` | 4 reglas de Beck + code smells sobre el diff acumulado | `simple-design-reviewer` | `building-a-slice/references/simple-design.md` |
 | `ux` | Krug + lighthouse sobre la UI ensamblada de la release (o `null` si sin UI) | `ux-krug-reviewer` | `building-a-slice/references/krug-ux.md` |
 | `coherence` | Trazabilidad triple AC↔change↔código de **todas** las HU de la release | `coherence-three-way` | — |
-| `stack_arch` | Arquitectura del PRD del consumidor (capa de servicios externos en la frontera declarada, capa de decisión determinista del dominio sin IA) | `stack-guardian` | — |
+| `stack_arch` | Arquitectura del PRD del consumidor (capa de servicios externos en la frontera declarada, capa de decisión determinista del dominio sin IA) y, si el proyecto adoptó la capa de arquitectura (`/build:architect`), conformidad del diff con los ADRs `accepted` de `docs/adr/` | `stack-guardian` | — |
 | `integration` | Recorrer el **journey completo** de la release con **deps reales** del proyecto, no stubs | skill `verify` / `run` (+ MCP chrome-devtools) | `release-dod.md` |
 
 Checklist de cierre: `references/release-dod.md`.
@@ -66,7 +66,10 @@ Checklist de cierre: `references/release-dod.md`.
 > **Opcional — conducir con workflow (releases grandes).** El fan-out del paso 3 puede conducirse con la
 > plantilla `workflows/release-gate.workflow.js` (referencia, no obligatoria): SOLO paraleliza los 5 reviewers
 > pesados; el gate `integration` (paso 4) sigue siendo **secuencial**, vía `verify`/`run` con **deps reales**,
-> **fuera** del `parallel()`. El resultado se escribe igual en `releases[]` respetando **una escritura por
+> **fuera** del `parallel()`. Pasa por `args` lo que computes **read-only**: `diffRange`, `hasUI` y **`hus[]`**
+> (los IDs de todas las HU de las épicas de la release) — con ≥ 3 HUs el carril `coherence` se shardea por HU
+> (lossless, fail-closed) en vez de recorrerlas en un solo agente; con menos, corre monolítico como siempre.
+> El resultado se escribe igual en `releases[]` respetando **una escritura por
 > entrada** y **validando contra el schema**; esta skill sigue siendo la única escritora. Parciales NO
 > promueven a `passed`.
 

package/skills/releasing-a-version/references/release-dod.md

@@ -8,7 +8,7 @@ corre **una vez** sobre el diff acumulado de todas sus épicas. Resultado en `bu
 - [ ] **`smell`** — `simple-design-reviewer` sin bloqueantes sobre el diff acumulado; 4 reglas de Beck respetadas.
 - [ ] **`ux`** — `ux-krug-reviewer` ok sobre la UI ensamblada (o `null` si la release no tiene UI). Lighthouse/accesibilidad si la app corre.
 - [ ] **`coherence`** — `coherence-three-way` confirma trazabilidad AC↔change↔código de **todas** las HU de **todas** las épicas de la release, sin huérfanos.
-- [ ] **`stack_arch`** — `stack-guardian` confirma la arquitectura del PRD del consumidor: la capa de servicios externos/IA en la frontera declarada server-side (no decide), la capa de decisión determinista del dominio sin IA, sin claves de servicios externos en cliente.
+- [ ] **`stack_arch`** — `stack-guardian` confirma la arquitectura del PRD del consumidor: la capa de servicios externos/IA en la frontera declarada server-side (no decide), la capa de decisión determinista del dominio sin IA, sin claves de servicios externos en cliente. Si existe `docs/adr/` (capa de arquitectura, `/build:architect`), confirma además que el diff acumulado **no contradice** los ADRs `accepted` (estilo, tácticas por driver, divergencias de stack registradas); sin la capa, esa parte es N/A.
 - [ ] **`integration`** — el **journey completo** de la release se recorre end-to-end con **dependencias reales** del proyecto (servicios externos/IA y capa de decisión reales, según el PRD del consumidor), no stubs. Verificado con la skill `verify`/`run` (+ MCP `chrome-devtools`). Se corre **fuera** del fan-out
   paralelo de reviewers (es **secuencial**, con deps reales); ver `../workflows/release-gate.workflow.js`.
 

package/skills/releasing-a-version/workflows/README.md

@@ -16,4 +16,9 @@
 
 ## Plantillas
 - **`release-gate.workflow.js`** — `parallel(5 reviewers)` → `integration` secuencial → síntesis a
-  `releases[].gates.{security, smell, ux, coherence, stack_arch, integration}`.
+  `releases[].gates.{security, smell, ux, coherence, stack_arch, integration}`. El carril **`coherence`**
+  se shardea **por HU** cuando la release tiene ≥ 3 HUs (`args.hus[]`, computadas read-only por la skill):
+  la trazabilidad triple de cada HU es independiente → el sharding es *lossless* y el carril más lento pasa
+  de O(HUs) a O(1) + consolidación **fail-closed** con cobertura completa (shard fallido/ausente = gate
+  false, nunca muestreo). `security`/`smell`/`ux`/`stack_arch` quedan **monolíticos a propósito**:
+  shardearlos por archivos puede perder hallazgos cross-cutting.

package/skills/releasing-a-version/workflows/release-gate.workflow.js

@@ -19,9 +19,9 @@
 
 export const meta = {
   name: 'release-gate',
-  description: 'Reviewers pesados en paralelo + integración secuencial + síntesis para el Release Gate (outer loop). Read-only; devuelve veredictos, no escribe estado.',
+  description: 'Reviewers pesados en paralelo (coherence shardeado por HU cuando la release es grande) + integración secuencial + síntesis para el Release Gate (outer loop). Read-only; devuelve veredictos, no escribe estado.',
   phases: [
-    { title: 'Reviewers', detail: '5 reviewers pesados en paralelo sobre el diff acumulado' },
+    { title: 'Reviewers', detail: '5 reviewers en paralelo; el carril coherence fan-out por HU (≥3 HUs) con consolidación fail-closed' },
     { title: 'Integration', detail: 'journey completo con deps reales (SECUENCIAL, fuera del parallel)' },
   ],
 }
@@ -35,24 +35,79 @@ const RELEASE_REVIEW_SCHEMA = {
   },
 }
 
-// diffRange y si la release tiene UI llegan por `args` (la skill los computa READ-ONLY).
+// diffRange, si la release tiene UI y la lista de HUs llegan por `args` (la skill los computa READ-ONLY).
+//   args.hus : string[] — IDs de TODAS las HU de las épicas de la release (para shardear coherence).
+//              Ausente o < 3 → coherence corre monolítico (comportamiento previo, sin inflar releases chicas).
 const diffRange = (args && args.diffRange) || '<merge-anterior>..main'
 const hasUI = !!(args && args.hasUI)
+const hus = (args && Array.isArray(args.hus)) ? args.hus.filter(Boolean) : []
+
+// --- Carril coherence: SHARDING por HU (lossless) ----------------------------
+// La trazabilidad triple AC↔change↔código de cada HU es INDEPENDIENTE de las demás: shardearla
+// no pierde hallazgos cruzados (a diferencia de security/smell, que quedan monolíticos a propósito).
+// Consolidación FAIL-CLOSED y cobertura COMPLETA: un shard fallido/ausente = gate false, nunca
+// muestreo silencioso. Con < 3 HUs el fan-out no paga su overhead → monolítico como siempre.
+async function coherenceLane() {
+  if (hus.length < 3) {
+    try {
+      const v = await agent(
+        `Eres el reviewer pesado del Release Gate para el gate "coherence". Verifica READ-ONLY la trazabilidad
+triple AC↔change↔código de TODAS las HU de la release sobre el diff acumulado (${diffRange}). Si NO puedes
+verificar, devuelve pass:false con el motivo — nunca PASS por defecto.`,
+        { label: 'release:coherence', agentType: 'coherence-three-way', phase: 'Reviewers', schema: RELEASE_REVIEW_SCHEMA },
+      )
+      if (!v) return { gate: 'coherence', value: false, error: 'sin veredicto' }
+      return { gate: 'coherence', value: v.pass === true, findings: v.findings || [] }
+    } catch (e) {
+      return { gate: 'coherence', value: false, error: 'el reviewer falló' }
+    }
+  }
+  log(`coherence: fan-out por HU (${hus.length} shards — cobertura completa, sin muestreo)`)
+  const shards = await parallel(hus.map((hu) => async () => {
+    try {
+      const v = await agent(
+        `Eres un shard del reviewer "coherence" del Release Gate. Verifica READ-ONLY la trazabilidad triple
+AC↔change↔código de UNA SOLA HU: ${hu}. Lee sus AC (Given/When/Then), el change OpenSpec que la cubre y el
+código/tests del diff acumulado (${diffRange}) que la implementan. pass:true SOLO si cada AC de ${hu} tiene
+test real y código cableado, sin huérfanos. Si NO puedes verificar → pass:false con el motivo.`,
+        { label: `release:coherence:${hu}`, agentType: 'coherence-three-way', phase: 'Reviewers', schema: RELEASE_REVIEW_SCHEMA },
+      )
+      if (!v) return { hu, pass: false, findings: [`${hu}: sin veredicto`] }
+      return { hu, pass: v.pass === true, findings: (v.findings || []).map((f) => `${hu}: ${f}`) }
+    } catch (e) {
+      return { hu, pass: false, findings: [`${hu}: el shard falló`] }
+    }
+  }))
+  const done = shards.filter(Boolean)
+  const missing = hus.length - done.length            // shard ausente (skip/kill) = hueco de cobertura
+  const bad = done.filter((s) => !s.pass)
+  const value = bad.length === 0 && missing === 0
+  return {
+    gate: 'coherence', value,
+    findings: [
+      ...bad.flatMap((s) => s.findings),
+      ...(missing > 0 ? [`coherence: ${missing} shard(s) sin resultado — cobertura incompleta, gate false`] : []),
+    ],
+  }
+}
 
 // --- PASO A · Reviewers pesados EN PARALELO (exactamente estos 5) ------------
 // Cada uno delega en su subagente sobre el MISMO diff acumulado y devuelve síntesis.
 // Barrera deliberada: la síntesis de release necesita los 5 veredictos juntos.
+// security/smell/ux/stack_arch quedan MONOLÍTICOS a propósito: shardearlos por archivos
+// puede perder hallazgos cross-cutting (p.ej. un bypass de auth visible solo entre módulos).
 phase('Reviewers')
 const REVIEWERS = [
   { gate: 'security',   agentType: 'security-reviewer' },
   { gate: 'smell',      agentType: 'simple-design-reviewer' },
   { gate: 'ux',         agentType: 'ux-krug-reviewer' },   // null SOLO si la release no tiene UI
-  { gate: 'coherence',  agentType: 'coherence-three-way' },
+  { gate: 'coherence',  agentType: 'coherence-three-way' }, // carril con sharding interno por HU (ver coherenceLane)
   { gate: 'stack_arch', agentType: 'stack-guardian' },
 ]
 const reviews = await parallel(REVIEWERS.map((r) => async () => {
   // N/A legítimo: ux sin UI → null (NO es fallo). El resto SIEMPRE corre.
   if (r.gate === 'ux' && !hasUI) return { gate: r.gate, value: null, na: true }
+  if (r.gate === 'coherence') return coherenceLane()
   try {
     const v = await agent(
       `Eres el reviewer pesado del Release Gate para el gate "${r.gate}". Revisa READ-ONLY el diff acumulado de la

package/skills/setup-architecture/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: setup-architecture
+description: Use BEFORE building — after discovery (PRD + user story map + epicas + HUs exist) and before the first slice — to produce the project's architecture layer as ADRs using the ADD method (Attribute-Driven Design, Len Bass). Reads docs/ read-only, extracts architectural drivers/ASRs, drives ADD iterations (tactics → styles → views → ATAM-lite analysis), writes docs/adr/ (0000 drivers catalog + numbered ADRs + architectural backlog) and populates .claude/config/stack-allowlist.json. Runs autonomously and proposes maximally — stops for a single human review and only escalates genuine business trade-offs. The ADRs become build criteria: the DoR gate requires driver coverage and the release-gate stack_arch audits conformance. Delegates driver extraction to asr-extractor and evaluation to architecture-evaluator; never publishes, only proposes.
+---
+
+# Definir la arquitectura (método ADD) — capa previa a construcción
+
+Genera la **capa de arquitectura** del proyecto **antes** de que empiece el inner loop de
+`building-a-slice`. Su objetivo es que el agente entre a construir con las decisiones técnicas ya
+claras (estilo, tácticas, stack), y que esas decisiones se vuelvan **criterios exigibles** por los gates
+del arnés. Sigue el método **ADD** (Attribute-Driven Design, Len Bass — *Software Architecture in
+Practice*), cuyos pasos son los 8 del diseño arquitectónico:
+
+```
+Negocio → ASRs → Tácticas → Estilos → Vistas → Evaluación (ATAM) → Stack → Código
+```
+
+> **Dónde encaja.** Corre **después de discovery** (`@trycore/spec-product-flow` dejó listos PRD, user
+> story map, `docs/03-backlog/epicas.md` y `docs/04-historias/HU-*.md`) y **antes** del primer slice. No
+> reemplaza al Release Gate: lo **habilita**. El gate `stack_arch` sigue auditando en el outer loop, pero
+> ahora contra los ADRs que esta capa produce.
+
+## Principio de operación
+
+- **Entrada de solo lectura: `docs/`** (PRD, story map, épicas, HUs). Esta skill **NO escribe** en los
+  artefactos de discovery (`docs/01-prd/`…`docs/04-historias/`). Su **única** salida en `docs/` es el
+  subárbol **`docs/adr/`** (propiedad de construcción; carve-out declarado en `METODOLOGIA.md`).
+- **Propone, no publica.** Genera los `.md` con estado `proposed` / `living-document`. La promoción a
+  `accepted` la hace un humano en la revisión única (fase 5). Forward-compat v0.9: los tipos viven en
+  `asset-types.json`; cuando exista el runtime, la propuesta irá por API (`POST /context/proposals`).
+- **Autónoma y de propuesta máxima.** La IA rellena todo el catálogo y todos los ADRs de una pasada;
+  **no** pregunta campo por campo. Solo se detiene ante **trade-offs de negocio** genuinos (ver fase 5).
+- **Delega la exploración pesada en subagentes** (`asr-extractor`, `architecture-evaluator`): devuelven
+  síntesis condensada y protegen el presupuesto de atención de la sesión principal.
+- **Divulgación progresiva:** carga el `references/<tema>.md` solo cuando la fase lo necesita.
+- **El estado es el archivo.** `docs/adr/_backlog-arquitectonico.md` es el estado auto-descriptivo de la
+  capa (no toca `build-state.json`). Re-correr = **incremental**: añade iteraciones, no regenera.
+
+## Fases (carga la referencia indicada en cada paso)
+
+| Fase | Acción | Delega en | Salida | Referencia |
+|---|---|---|---|---|
+| 0 · preflight | Verifica discovery listo (PRD + `epicas.md` + ≥1 HU). Si falta → **STOP**, remite a `/trycore:*`. Solo lectura. | — | — | — |
+| 1 · drivers | Extrae el catálogo de drivers/ASRs (OE, UC significativos, escenarios QA de 6 partes, CON, CRN, matriz de prioridad, plan de iteraciones) | `asr-extractor` (fan-out sobre `docs/`) | `docs/adr/0000-drivers-y-asrs.md` | `drivers-extraction.md` |
+| 2 · iterar ADD | Por ronda (una por fase PRD / línea de release): selecciona drivers → elige **tácticas y estilos** → instancia responsabilidades/interfaces → boceta **vistas** (mermaid) | sesión principal + `references/add-method.md` | `docs/adr/000N-*.md` (plantilla 7 secciones) | `add-method.md` |
+| 3 · evaluar (ATAM) | Análisis adversarial de cada ADR: puntos de sensibilidad, trade-offs, riesgos, drivers no cubiertos | `architecture-evaluator` | actualiza §5 del ADR + riesgos del backlog | `atam-lite.md` |
+| 4 · backlog | Actualiza el tablero de cobertura driver↔ADR, riesgos abiertos y bitácora de iteraciones | sesión principal | `docs/adr/_backlog-arquitectonico.md` | `atam-lite.md` |
+| 5 · revisión | Presenta el set completo; escala **solo** trade-offs de negocio (una `AskUserQuestion` batcheada); al aceptar promueve `proposed → accepted` y consolida el stack | usuario (default computado) | `.claude/config/stack-allowlist.json` + estados `accepted` | `add-method.md` |
+
+**Plantillas de salida.** La spec canónica de cada archivo vive en **`assets/` de esta skill** —se
+instala con ella en ambos canales—: `assets/0000-drivers-y-asrs.template.md`, `assets/adr-add.template.md`
+y `assets/_backlog-arquitectonico.template.md` (única fuente de verdad de la estructura; declarada para el
+runtime v0.9 vía `asset-types.json`). La skill **lee la plantilla y escribe** en `docs/adr/`; crea el
+directorio si no existe. **No pises** ADRs ya `accepted` (re-corrida incremental).
+
+## Fase 5 · Revisión única (mínimo HITL)
+
+Al terminar de generar 0000 + los ADRs + el backlog:
+
+1. **Resumen** de una pantalla: nº de drivers por tipo, nº de ADRs, estilo(s) elegidos, stack propuesto,
+   y **riesgos abiertos** del backlog.
+2. **Escala solo lo que es decisión de negocio**, no de arquitectura, con **una sola** `AskUserQuestion`
+   que agrupe todos los trade-offs pendientes (p.ej.: "¿el historial de versiones es visible para
+   consumidores o solo auditores?", "¿se fijan objetivos de DR (RTO/RPO) ahora o se aplazan?"). Todo lo
+   demás la IA ya lo decidió y lo dejó registrado con su rationale. Sin TTY/headless: **no bloquees**;
+   deja los trade-offs como riesgos abiertos en el backlog y emítelos por stdout.
+3. Al aceptar: promueve los ADRs de decisión `proposed → accepted`, añade la fila **Cierre** a la
+   bitácora, y **consolida el stack** → actualiza `.claude/config/stack-allowlist.json` con **merge
+   aditivo, nunca overwrite**: añade a `allow` las deps decididas y a `rationale` la referencia al ADR
+   que las justifica (p.ej. `"fastapi": "ADR-0001"`); **preserva `source`** (ese campo es el contrato
+   del arnés: la ruta a la sección técnica del PRD del consumidor — NO lo pises) y no borra entradas
+   que el consumidor haya puesto a mano. Desde aquí, `stack-guard.sh` ya hace cumplir la lista.
+
+## Cómo alimenta al build (los ADRs son criterios)
+
+- **`stack-allowlist.json`** — lo puebla esta capa; el hook `stack-guard.sh` (PreToolUse) bloquea deps
+  fuera de lista en tiempo real.
+- **DoR** — `dor-dod-gatekeeper` exige que los drivers arquitectónicamente significativos de la épica
+  (sobre todo `layer: foundational`) tengan un ADR con estado ≥ `ABORDADO` en el backlog (ver
+  `building-a-slice/references/dor.md`).
+- **`stack_arch`** (Release Gate) — `stack-guardian` audita el diff acumulado contra las decisiones de
+  `docs/adr/`, no solo contra la allowlist.
+
+## Guardrails
+
+- **Solo lectura sobre discovery.** Nunca edites `docs/01-prd/`…`docs/04-historias/`. La única escritura
+  en `docs/` es `docs/adr/`.
+- **Propón, no publiques.** Estados `proposed`/`living-document`; la promoción a `accepted` es del humano.
+- **Ante la duda técnica, decide y registra** (con alternativas descartadas y rationale). **Ante la duda
+  de negocio, escala** en la revisión única. No confundas una con otra.
+- **Incremental en re-corridas.** No regeneres ADRs ya `accepted`; añade una iteración nueva a la bitácora.
+- **Agnóstico.** El vocabulario ADD (drivers, tácticas, estilos, vistas) es genérico del arnés; el
+  dominio entra **por `docs/`**, nunca hardcodeado en la skill.
+- Si algo contradice `METODOLOGIA.md`, **gana la metodología**.