@trycore/spec-build-harness 0.8.1 → 0.8.2

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.2",
   "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/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`.

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/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**.

package/skills/setup-architecture/assets/0000-drivers-y-asrs.template.md

@@ -0,0 +1,101 @@
+---
+id: 0000
+title: "Catálogo de Drivers Arquitectónicos y ASRs (entrada del método ADD)"
+date: YYYY-MM-DD
+status: living-document
+authors:
+  - <Equipo Arquitectura>
+tags:
+  - add
+  - drivers
+  - asr
+  - quality-attributes
+---
+
+# ADR 0000 — Drivers Arquitectónicos y ASRs
+
+> **Naturaleza:** No es un ADR de decisión, sino la **entrada de diseño** (Paso 1 del método ADD de Len
+> Bass). Consolida propósito, requisitos funcionales primarios, escenarios de atributos de calidad
+> priorizados, restricciones y concerns. Toda decisión en un ADR (0001+) debe trazar a uno o más drivers
+> de este catálogo, y todo driver debe estar cubierto por al menos un ADR (ver
+> [_backlog-arquitectonico.md](_backlog-arquitectonico.md)).
+>
+> **Cómo se genera:** la skill `setup-architecture` (`/build:architect`) lo **propone** leyendo `docs/`
+> (PRD + user story map + `03-backlog/epicas.md` + `04-historias/HU-*.md`) — de solo lectura. Este es un
+> **documento vivo**: cada re-corrida añade drivers nuevos que surjan de HUs/épicas nuevas.
+
+## Cómo se usa este documento en ADD
+
+ADD diseña por **rondas e iteraciones** de 7 pasos. Este catálogo alimenta los pasos 1 y 2:
+
+- **Paso 1 — Review Inputs:** todo lo de este documento.
+- **Paso 2 — Establish Iteration Goal:** cada iteración selecciona un subconjunto priorizado de estos
+  drivers (ver §6 Plan de iteraciones).
+
+## Propósito de diseño
+
+<Greenfield / brownfield; una línea sobre qué es el sistema y su enfoque de diseño (top-down desde el
+sistema completo, o refinamiento de elementos internos).>
+
+Fuente: [docs/01-prd/<prd>.md](../01-prd/<prd>.md) §<x>.
+
+## 1. Objetivos de negocio (OE)
+
+| ID | Objetivo | Métrica / Meta |
+|----|----------|----------------|
+| OE-01 | … | … |
+
+## 2. Requisitos funcionales primarios (UC) — arquitecturalmente significativos
+
+> Solo los casos de uso que **moldean** la arquitectura. No es el backlog completo.
+
+| UC | Descripción | Trazabilidad |
+|----|-------------|--------------|
+| UC-1 | … | OE-…, HU-… |
+
+## 3. Escenarios de atributos de calidad (QA) — formato de 6 partes
+
+> Formato Bass: **Fuente del estímulo · Estímulo · Artefacto · Entorno · Respuesta · Medida de respuesta.**
+> Cada escenario lleva prioridad `(Importancia de negocio, Impacto/Dificultad arquitectónica)` en escala
+> {A=Alta, M=Media, B=Baja}. La **medida de respuesta** debe ser cuantificable (es lo que convierte un
+> deseo en un ASR verificable).
+
+### QA-1 — <Atributo> · prioridad (A, M)
+- **Fuente:** …
+- **Estímulo:** …
+- **Artefacto:** …
+- **Entorno:** …
+- **Respuesta:** …
+- **Medida:** … (traza a HU/AC/PRD)
+
+## 4. Restricciones (CON)
+
+| ID | Restricción | Origen |
+|----|-------------|--------|
+| CON-1 | … | … |
+
+## 5. Concerns / preocupaciones del proyecto (CRN)
+
+| ID | Concern | Implicación de diseño |
+|----|---------|-----------------------|
+| CRN-1 | … | … |
+
+## 6. Plan de iteraciones (rondas ADD ↔ fases del PRD / líneas de release)
+
+> Estrategia: iterar en el orden de las fases del PRD (o las líneas de release del Story Map). Cada
+> iteración ejecuta los Pasos 2–7 de ADD sobre el subconjunto de drivers indicado.
+
+| Iteración | Fase PRD / Release | Drivers seleccionados (Paso 2) | Elementos a refinar (Paso 3) | ADRs |
+|-----------|--------------------|--------------------------------|------------------------------|------|
+| **1** | … | … | … | … |
+
+## 7. Matriz de priorización (Importancia de negocio × Impacto arquitectónico)
+
+| | Impacto arq. ALTO | Impacto arq. MEDIO | Impacto arq. BAJO |
+|---|---|---|---|
+| **Negocio ALTO** | … | … | — |
+| **Negocio MEDIO** | … | … | — |
+
+> Los cuadrantes superiores (alta importancia × alto impacto) son los **ASRs críticos**: se atacan
+> primero o se mitiga su riesgo lo antes posible (principio ADD de iterar hasta satisfacer los drivers
+> críticos / mitigar el riesgo).

package/skills/setup-architecture/assets/_backlog-arquitectonico.template.md

@@ -0,0 +1,51 @@
+# Backlog Arquitectónico (ADD — Paso 7)
+
+> Tablero de seguimiento del método ADD. Rastrea qué drivers/ASRs
+> ([0000-drivers-y-asrs.md](0000-drivers-y-asrs.md)) han sido abordados por una decisión, cuáles están en
+> progreso y cuáles pendientes. Equivale al Kanban arquitectónico que recomienda Len Bass para no perder
+> de vista la cobertura entre iteraciones.
+>
+> **Este archivo es el estado de la capa de arquitectura.** Lo escribe la skill `setup-architecture`
+> (`/build:architect`) y lo consumen los gates del arnés: el **DoR** verifica que los drivers
+> arquitectónicamente significativos de una épica tengan un ADR con estado ≥ `ABORDADO` antes de abrir el
+> slice; el gate **`stack_arch`** del Release Gate audita conformidad contra los ADRs referenciados aquí.
+
+**Convención de estado:**
+- `PENDIENTE` — driver sin decisión asociada.
+- `EN DISEÑO` — iteración en curso.
+- `ABORDADO` — existe ADR que lo cubre con análisis (Paso 7) registrado.
+- `VERIFICADO` — el análisis confirma que la decisión satisface la medida de respuesta (idealmente
+  revisado por un par).
+
+## Tablero por driver
+
+> La columna **Trazabilidad** (EP/HU/§PRD de los que sale el driver, heredada del `0000`) es la que usa
+> el DoR para el join épica↔driver: dado un `EP-XXX`, sus drivers son las filas cuya trazabilidad cita
+> esa épica o alguna de sus HU.
+
+| Driver | Tipo | Prioridad | Trazabilidad (EP/HU) | Iteración | ADR | Estado |
+|--------|------|-----------|----------------------|-----------|-----|--------|
+| UC-1 … | Funcional | (A,A) | EP-…, HU-… | 1 | 000N | PENDIENTE |
+| QA-1 … | QA | (A,M) | HU-…, §PRD | 1 | 000N | PENDIENTE |
+| CON-1 … | Restricción | — | §PRD | 1 | 000N | PENDIENTE |
+| CRN-1 … | Concern | — | — | 1 | 000N | PENDIENTE |
+
+## Riesgos arquitectónicos abiertos
+
+> Salida del análisis ATAM-lite (Paso 6/7): puntos de sensibilidad, trade-offs y riesgos sin mitigar.
+> Cada riesgo traza a su driver y a la mitigación planificada. Marcar ✅ CERRADO al resolver (no borrar:
+> deja el rastro).
+
+| Riesgo | Driver | Mitigación planificada | Iteración |
+|--------|--------|------------------------|-----------|
+| … | QA-… | … | … |
+
+## Bitácora de iteraciones
+
+> Una fila por ronda ADD. `Objetivo` = Paso 2; `Resultado` = Paso 7 (qué ADR se creó/refactorizó y qué
+> quedó sin resolver). La fila de **Cierre** registra la promoción `proposed → accepted` tras la revisión
+> humana.
+
+| Iteración | Fecha | Objetivo (Paso 2) | Resultado (Paso 7) |
+|-----------|-------|-------------------|--------------------|
+| 1 | YYYY-MM-DD | … | … |

package/skills/setup-architecture/assets/adr-add.template.md

@@ -0,0 +1,84 @@
+---
+id: NNNN
+title: "<Título de la decisión>"
+date: YYYY-MM-DD
+status: proposed   # proposed | accepted | superseded | deprecated
+authors:
+  - <Equipo / persona>
+tags: []
+add:
+  iteracion: <n>
+  fase_prd: "<Fase X>"
+---
+
+# ADR NNNN — <Título>
+
+> Plantilla alineada al método **ADD** (Attribute-Driven Design, Len Bass — *Software Architecture in
+> Practice*). Cada sección numerada corresponde a un paso del método. Las decisiones deben trazar a
+> [0000-drivers-y-asrs.md](0000-drivers-y-asrs.md) y actualizar
+> [_backlog-arquitectonico.md](_backlog-arquitectonico.md). Generada por la skill `setup-architecture`
+> (`/build:architect`); un humano la promueve `proposed → accepted`.
+
+## 1. Objetivo de la iteración y drivers seleccionados (Pasos 2–3)
+
+- **Objetivo de la iteración:** <qué se busca resolver en esta ronda>.
+- **Elemento(s) a refinar:** <sistema completo | servicio X | módulo Y>.
+- **Drivers abordados:**
+  - Funcionales: UC-…
+  - Atributos de calidad: QA-… (con su medida de respuesta)
+  - Restricciones: CON-…
+  - Concerns: CRN-…
+
+## 2. Conceptos de diseño elegidos (Paso 4)
+
+> Patrones arquitectónicos, **tácticas** (sentido Bass), componentes externos o arquitecturas de
+> referencia evaluados y elegidos para satisfacer los drivers. Registra las alternativas descartadas:
+> ese es el valor del ADR.
+
+| Driver | Concepto / Táctica | Alternativas descartadas | Razón |
+|--------|--------------------|--------------------------|-------|
+| QA-… | … | … | … |
+
+## 3. Instanciación: responsabilidades e interfaces (Paso 5)
+
+> Cómo se convierten los conceptos en estructuras reales: componentes/módulos, sus responsabilidades y
+> los contratos (interfaces) por los que se comunican.
+
+- **Elementos instanciados:** …
+- **Responsabilidades:** …
+- **Interfaces / contratos:** …
+
+## 4. Vistas y registro de la decisión (Paso 6)
+
+> Boceto de vista(s) estructural(es) — de módulos, de componentes-y-conectores o de asignación física —
+> y el rationale + trade-offs.
+
+```mermaid
+%% vista estructural / de despliegue / de secuencia
+```
+
+**Decisión:** …
+
+**Trade-offs aceptados:** …
+
+## 5. Análisis del diseño (Paso 7)
+
+> ¿La decisión satisface el objetivo de la iteración? Cada driver con veredicto y evidencia/medida.
+
+| Driver | ¿Satisfecho? | Evidencia / medida | Riesgo residual |
+|--------|--------------|--------------------|-----------------|
+| QA-… | ✅/⚠️/❌ | … | … |
+
+**Drivers no resueltos en esta iteración:** … (se devuelven al backlog arquitectónico).
+
+## 6. Consecuencias
+
+- Positivas: …
+- Negativas / riesgos: …
+- Operacionales: …
+
+## 7. Trazabilidad
+
+- Drivers: [0000-drivers-y-asrs.md](0000-drivers-y-asrs.md)
+- PRD / HU / Flows: …
+- Stack operacionalizado en: `.claude/config/stack-allowlist.json` (si esta ADR decide stack)