@trycore/spec-build-harness 0.6.0 → 0.7.1

package/commands/build/release.md

@@ -0,0 +1,84 @@
+---
+name: "BUILD: Release"
+description: Punto de entrada del outer loop. Corre el Release Gate UNA vez sobre el diff acumulado de una release — los 5 reviewers pesados (security, smell, ux, coherence, stack_arch) en paralelo + integración secuencial con deps reales — delegando en la skill releasing-a-version. No duplica el inner loop (ni TDD ni gates por slice).
+category: Workflow
+tags: [build-harness, outer-loop, release-gate, trycore]
+---
+
+Lanza el **outer loop**: las revisiones profundas que corren **una sola vez por release** sobre el diff
+acumulado, no por épica. Adaptador delgado: **delega** en la skill `releasing-a-version` (no la reimplementa).
+Si algo aquí contradice `METODOLOGIA.md`, **gana la metodología**.
+
+**Entrada:** `release_id` (p.ej. `R1-mvp`) o, si viene vacío, infiérelo del default computado tras archivar
+(ver §4 de la metodología y el nudge de `release-gate-nudge.sh`).
+
+---
+
+## 1. Preflight
+
+```bash
+test -f .claude/.build-harness-version || echo "NOT_INSTALLED"
+command -v python3 >/dev/null 2>&1 || echo "NO_PYTHON3"
+```
+
+Stop si no está instalado o falta `python3`.
+
+---
+
+## 2. Identificar la release y sus épicas
+
+Lee `build-state.json` y cruza con `docs/02-user-story-map/` para resolver qué épicas componen la release.
+Crea/actualiza la entrada en `releases[]` con `status: pending` (lo escribe `releasing-a-version`, única
+escritora de `releases[]`).
+
+---
+
+## 3. Computar el diff acumulado
+
+El alcance es el rango de commits de **todas** las épicas de la release: desde el merge anterior a la primera
+épica de la release hasta `main`.
+
+---
+
+## 4. Fan-out de reviewers pesados (en paralelo)
+
+Dispara **en paralelo** sobre ese diff los 5 reviewers (cada uno devuelve síntesis):
+
+| Gate | Subagente |
+|---|---|
+| `security` | `security-reviewer` |
+| `smell` | `simple-design-reviewer` |
+| `ux` (o `null` si sin UI) | `ux-krug-reviewer` |
+| `coherence` | `coherence-three-way` |
+| `stack_arch` | `stack-guardian` |
+
+Opcionalmente conduce este fan-out con la plantilla `skills/releasing-a-version/workflows/release-gate.workflow.js`
+(referencia). La plantilla **solo** paraleliza los 5 reviewers.
+
+---
+
+## 5. Integración SECUENCIAL (fuera del paralelo)
+
+Corre el gate `integration` con la skill `verify`/`run` (+ MCP chrome-devtools): el **journey completo** de la
+release end-to-end con **dependencias reales**, no stubs. **No** va dentro del `parallel()` ni delega en un
+reviewer. Es el gate **no negociable**: sin él, no hay release.
+
+---
+
+## 6. Síntesis y escritura
+
+- Todos los gates ✓ (o `null` cuando N/A) **y** `integration` ✓ → `releases[].status: passed`; escribe
+  `gates` y `updated_by: releasing-a-version` (valida contra `build-state.schema.json` antes de persistir;
+  una escritura por entrada). **Parciales no promueven a `passed`.**
+- Algo ✗ → `status: failed` con los hallazgos bloqueantes; el humano los corrige **como un slice normal**
+  (`/build:slice` / `building-a-slice`) y se **re-corre** el Release Gate.
+
+---
+
+## Guardrails
+
+- **Es outer loop.** Correr reviewers pesados **por slice** rompería el modelo de dos loops — aquí corren una
+  vez por release (`O(releases)`).
+- **No dupliques el inner loop**: no se hace TDD ni se cierran gates por slice.
+- **`integration` con deps reales es obligatorio**; no se acepta con todo stubbeado.
+- Delega en `releasing-a-version`; **no** la reimplementa. Si algo contradice `METODOLOGIA.md`, gana la metodología.

package/commands/build/slice.md

@@ -0,0 +1,93 @@
+---
+name: "BUILD: Slice"
+description: Punto de entrada del inner loop. Abre o continúa un slice (épica EP-XXX) y conduce el pipeline DoR → change → TDD → smoke → api/data → dod → PR+archive delegando en la skill building-a-slice (o el agente build-orchestrator para épicas multicapa). Respeta el orden estricto de gates y el scaffold como precondición.
+category: Workflow
+tags: [build-harness, inner-loop, slice, trycore]
+---
+
+Lanza el **inner loop** de construcción sobre una épica. Este comando es un **adaptador delgado**: no
+reimplementa el pipeline — **delega** en la skill `building-a-slice` (motor del inner loop) y en `opsx:*`
+(motor de changes). Si algo aquí contradice `METODOLOGIA.md`, **gana la metodología**.
+
+**Entrada:** `EP-XXX` o una descripción de la épica. Si viene vacío, usa **AskUserQuestion** para elegir la
+épica desde `docs/03-backlog/epicas.md`.
+
+---
+
+## 1. Preflight
+
+```bash
+test -f .claude/.build-harness-version || echo "NOT_INSTALLED"
+command -v python3 >/dev/null 2>&1 || echo "NO_PYTHON3"
+```
+
+**Si `NOT_INSTALLED`:** este proyecto no tiene el arnés instalado → ejecuta `trycore-build init` y vuelve.
+Stop si no está instalado o falta `python3`.
+
+---
+
+## 2. Leer el estado y decidir punto de entrada
+
+```bash
+python3 - <<'PY'
+import json, os, sys
+p = ".claude/state/build-state.json"
+if not os.path.exists(p): print("NO_STATE"); sys.exit(0)
+try: d = json.load(open(p))
+except Exception as e: print("CORRUPT_STATE", e); sys.exit(0)
+s = d.get("active_slice")
+if not s:
+    print("START dor")
+else:
+    g = s.get("gates", {})
+    abierto = next((k for k, v in g.items() if v is False), None)
+    print(f"RESUME {s.get('epica')} fase={s.get('phase')} primer_gate_abierto={abierto}")
+PY
+```
+
+- `NO_STATE`/`CORRUPT_STATE` → reporta y detente (no escribas).
+- `START dor` → no hay slice activo: arranca en **dor** con la épica objetivo.
+- `RESUME …` → ya hay un slice activo: **reanuda en su primer gate abierto** (no abras otro: el modelo es
+  secuencial, un solo slice activo).
+
+---
+
+## 3. Precondición de scaffold (y fuente de diseño si hay UI)
+
+Antes de escribir código de slice, verifica los gates de proyecto:
+
+- `scaffold.confirmed` debe ser `true`. Si es `false` → **STOP**: delega en la **Fase 0** de `building-a-slice`
+  (pregunta explícita; el arnés **no genera** el scaffold). No abras el slice.
+- Si el proyecto tiene UI, `design_source.confirmed` debe ser `true` (Fase 0-bis). Si no → **STOP** igual.
+
+El hook `scaffold-guard.sh` respalda esto en tiempo real.
+
+---
+
+## 4. Conducir el pipeline (delegar)
+
+Invoca la skill **`building-a-slice`** para conducir el inner loop. Para una épica **multicapa / grande**
+(superó el gate de tamaño → `sub_slices[]`), invoca el agente **`build-orchestrator`** (trabaja por fases
+encadenadas y, opcionalmente, conduce la exploración solo-lectura con `workflows/explore-fanout.workflow.js`).
+
+- **No** ejecutes `opsx:apply` directamente ni saltes gates: el orden es estricto
+  (`dor → change → tdd → smoke → api/data → dod → pr`).
+- **No** dispares reviewers pesados aquí (`security`, `smell`, `ux`, `coherence`, `stack_arch`): pertenecen
+  al **Release Gate** (`/build:release`). Hacerlo por slice rompería el modelo de dos loops.
+
+---
+
+## 5. Resumen
+
+Al terminar el paso, resume: fase actual, gates cerrados/abiertos y el siguiente gate. Si la épica quedó
+archivada, recuerda el default del Release Gate (ver `/build:release`).
+
+---
+
+## Guardrails
+
+- **Un solo slice activo** (secuencial). No abras un segundo mientras haya `active_slice`.
+- **Orden estricto de gates**; un gate no se salta. `dod` exige `wiring_verified: true`.
+- **Sin scaffold confirmado, no hay slice** (el arnés lo exige pero no lo genera).
+- **Agnóstico**: este comando no asume dominio; lo específico entra por `/build:onboard` y `stack-allowlist.json`.
+- Si algo contradice `METODOLOGIA.md`, **gana la metodología**.

package/commands/build/work.md

@@ -0,0 +1,68 @@
+---
+name: "BUILD: Work"
+description: Router de entrada (classify-and-act) del arnés. Clasifica el trabajo entrante y enruta a la skill correcta — building-a-micro-change (mantenimiento), building-a-slice (épica/producto nuevo) o releasing-a-version (Release Gate) — codificando los límites duros del micro-change y el default del Release Gate. Es RUTEO, no política: no ejecuta el pipeline, no toca el estado ni crea ramas.
+category: Workflow
+tags: [build-harness, router, classify-and-act, trycore]
+---
+
+**Router puro.** Decide *qué carril* aplica y **delega** en la skill correspondiente. NO ejecuta el pipeline,
+NO escribe `build-state.json`, NO crea ramas. Codifica como **ruteo** (no política nueva) el *decision gate*
+del micro-change y el default del Release Gate de `METODOLOGIA.md` (§2, §4). Si algo contradice la metodología,
+**gana la metodología**.
+
+**Entrada:** una descripción del trabajo a hacer.
+
+---
+
+## 1. Preflight
+
+```bash
+test -f .claude/.build-harness-version || echo "NOT_INSTALLED"
+```
+
+Si `NOT_INSTALLED` → ejecuta `trycore-build init` y vuelve.
+
+---
+
+## 2. Clasificar (decision gate)
+
+Aplica las reglas en orden:
+
+1. **¿Mantenimiento sin capacidad nueva?** — typo, ajuste de copy/config/docs, bump de dependencia **ya
+   permitida**, o fix de **pocas líneas** sin nueva capacidad **Y** sin ninguno de los límites duros del
+   paso 3 → carril **`building-a-micro-change`** (`fix/*`|`chore/*` → PR, **sin** abrir `active_slice`).
+2. **¿Producto nuevo / una épica?** — capacidad nueva, o cualquier límite duro cruzado → carril
+   **`building-a-slice`** (una épica `EP-XXX` = un slice = un change = una rama = un PR). Si no hay épica aún,
+   el trabajo vuelve a discovery para crearla.
+3. **¿Toca correr el Release Gate?** — la épica recién archivada **cierra una línea de release** del Story Map,
+   o hay **≥ 2 épicas archivadas** desde el último entry de `releases[]` → sugiere el carril
+   **`releasing-a-version`** (outer loop). (El destino es la skill existente; este router no depende de
+   `/build:release`.)
+
+---
+
+## 3. Límites duros del micro-change (escalan a épica)
+
+Si el cambio **añade una dependencia nueva**, **crea un endpoint/API nuevo**, o **toca lógica de dominio o el
+modelo/invariantes de datos** → **deja de ser micro-change** y se enruta a **`building-a-slice`** (épica).
+**Ante la duda, SIEMPRE épica.**
+
+---
+
+## 4. Actuar (delegar) — con degradación headless
+
+- **Con TTY**: confirma la clasificación con **una sola** `AskUserQuestion` (ofrece el carril propuesto como
+  primera opción "(Recomendado)") y luego invoca la skill elegida.
+- **Sin TTY / headless / entrada ausente**: **no bloquees**. Clasifica determinísticamente y emite por stdout
+  `{clasificación, skill recomendada, criterio que disparó la rama}`. Si es **ambiguo**, aplica el **default
+  duro**: escalar a épica → `building-a-slice`, declarándolo explícitamente.
+
+---
+
+## Guardrails
+
+- **Solo ruteo.** No corres el pipeline, no tocas el estado, no creas ramas: eso es de las skills destino.
+- **Ante la duda, épica.** Nunca degrades un cambio con límite duro a micro-change.
+- **No dupliques gates** ni saltes el orden: las skills destino los gobiernan.
+- **Agnóstico**: vocabulario genérico del arnés; lo específico del dominio entra por `/build:onboard`.
+- Si algo contradice `METODOLOGIA.md`, **gana la metodología**.

package/dist/lib/settings-merge.js

@@ -20,7 +20,7 @@ const HOOK_SPECS = [
     { event: 'PreToolUse', matcher: 'Bash', scripts: ['gitflow-guard.sh'] },
     { event: 'PreToolUse', matcher: 'Write|Edit|MultiEdit', scripts: ['stack-guard.sh', 'scaffold-guard.sh', 'design-source-guard.sh'] },
     { event: 'PostToolUse', matcher: 'Write|Edit|MultiEdit', scripts: ['lint-typecheck.sh', 'coherence-flag.sh'] },
-    { event: 'Stop', matcher: '.*', scripts: ['build-gate-check.sh', 'reflect-nudge.sh'] },
+    { event: 'Stop', matcher: '.*', scripts: ['build-gate-check.sh', 'reflect-nudge.sh', 'release-gate-nudge.sh'] },
 ];
 /** Permisos MÍNIMOS y enumerados [H11]. Nunca permisos amplios (mcp__*, additionalDirectories…). */
 const MIN_PERMISSIONS = [

package/docs/agents.md

@@ -12,7 +12,14 @@ veredicto al `build-orchestrator`**, que es quien propone la escritura del estad
 > **inner loop** (skill `building-a-slice`, por épica `EP-XXX`). Los 5 revisores pesados de
 > release (`security-reviewer`, `simple-design-reviewer`, `ux-krug-reviewer`,
 > `coherence-three-way`, `stack-guardian`) corren **una vez por release** en el **outer loop**
-> (skill `releasing-a-version`).
+> (skill `releasing-a-version`) y escriben sus veredictos en `releases[].gates`
+> (`security`, `smell`, `ux`, `coherence`, `stack_arch` — este último renombrado desde el antiguo
+> `stack` por-slice).
+>
+> **Conducción opcional vía plantillas de workflow.** Tres plantillas read-only (opt-in, no editan
+> estado) sirven de andamiaje para orquestar estos agentes sin sustituir su juicio:
+> `explore-fanout.workflow.js` y `wiring-verify.workflow.js` en `building-a-slice` (inner loop), y
+> `release-gate.workflow.js` en `releasing-a-version` (outer loop).
 
 ## Tabla resumen
 
@@ -23,8 +30,8 @@ veredicto al `build-orchestrator`**, que es quien propone la escritura del estad
 | 3 | `security-reviewer` | sonnet | Revisores de release | Gate `security` — seguridad enfocada al dominio |
 | 4 | `simple-design-reviewer` | sonnet | Revisores de release | Gate `smell` — 4 reglas de Beck + code smells |
 | 5 | `ux-krug-reviewer` | sonnet | Revisores de release | Gate `ux` — usabilidad (Steve Krug) |
-| 6 | `coherence-three-way` | **opus** | Revisores de release | Gate `coherence` — coherencia triple AC↔change↔código |
-| 7 | `stack-guardian` | sonnet | Revisores de release | Gate `stack` — stack y arquitectura vs. allowlist |
+| 6 | `coherence-three-way` | **opus** | Revisores de release | Gate `coherence` (en `releases[].gates`) — coherencia triple AC↔change↔código |
+| 7 | `stack-guardian` | sonnet | Revisores de release | Gate `stack_arch` (en `releases[].gates`) — stack y arquitectura vs. allowlist |
 | 8 | `api-contract-tester` | sonnet | Contrato / datos | Gate `api` — pruebas de contrato (Newman/Postman) |
 | 9 | `data-consistency-checker` | sonnet | Contrato / datos | Gate `data` — invariantes y consistencia de datos |
 | 10 | `change-epic-coherence` | sonnet | Trazabilidad | Gate `coherence_link` — enlace change↔épica↔HU |
@@ -53,7 +60,7 @@ frontmatter completo y `estado: lista`; AC en Given/When/Then con happy/error/ed
 dependencias declaradas; alcance dentro de la allowlist) y abre el `active_slice` si pasa. A
 la salida valida la **Definition of Done reducida por slice** (gate `dod`): `tdd`,
 `journey_smoke`, `coherence_link`, `data`, `api`, documentación con back-refs y hooks verdes.
-**No valida aquí** `security`, `smell`, `ux`, `coherence` ni `stack`: esos son del Release Gate.
+**No valida aquí** `security`, `smell`, `ux`, `coherence` ni `stack_arch`: esos son del Release Gate (viven en `releases[].gates`).
 
 ## Revisores de release
 
@@ -69,39 +76,39 @@ los **especializa al dominio declarado por el consumidor**: secretos de servicio
 solo server-side, datos sensibles/PII regulados no persistidos crudos, validación de archivos
 y entrada, salida de servicios externos/IA tratada como input no confiable, logs sin PII y
 decisiones auditables sin sobre-exposición. Veredicto por severidad
-(CRÍTICO/ALTO/MEDIO/BAJO); sin CRÍTICO/ALTO → `gates.security: true`.
+(CRÍTICO/ALTO/MEDIO/BAJO); sin CRÍTICO/ALTO → `releases[].gates.security: true`.
 
 ### `simple-design-reviewer` · modelo `sonnet`
 **Revisor de diseño simple y code smells** (gate `smell`), sobre código ya en verde. Aplica
 las 4 reglas de Kent Beck (pasa los tests → revela la intención → sin duplicación → mínimos
 elementos) y caza un catálogo de smells (funciones largas, clases "Dios", números mágicos,
 duplicación de validación, props drilling, código muerto, `any`, acoplamiento a servicios
-externos). Hallazgos BLOQUEANTE/RECOMENDADO/NIT; sin bloqueantes → `gates.smell: true`.
+externos). Hallazgos BLOQUEANTE/RECOMENDADO/NIT; sin bloqueantes → `releases[].gates.smell: true`.
 
 ### `ux-krug-reviewer` · modelo `sonnet` · lee el dominio
-**Revisor de usabilidad** según Steve Krug (gate `ux`); aplica solo a slices con UI (sin UI →
-`gates.ux: null`). Verifica "don't make me think", jerarquía visual, convenciones,
+**Revisor de usabilidad** según Steve Krug (gate `releases[].gates.ux`); aplica solo a releases con UI (sin UI →
+`releases[].gates.ux: null`). Verifica "don't make me think", jerarquía visual, convenciones,
 escaneabilidad, affordances, tolerancia al error (claridad de las decisiones de alto impacto y
 su justificación según el dominio) y accesibilidad básica. Revisión estática y, si la app
 corre, dinámica vía MCP `chrome-devtools` (`take_snapshot`, `lighthouse_audit`). Sin
-bloqueantes → `gates.ux: true`.
+bloqueantes → `releases[].gates.ux: true`.
 
 ### `coherence-three-way` · modelo `opus` · lee el dominio
-**Auditor de coherencia triple** (gate `coherence`). Usa el modelo más capaz porque razona a
+**Auditor de coherencia triple** (gate `releases[].gates.coherence`). Usa el modelo más capaz porque razona a
 la vez sobre tres documentos: los **AC (G/W/T)** de las HU de la épica ↔ el **OpenSpec change**
 (`specs/` + `tasks.md`) ↔ el **código y tests** implementados. Hace comprobaciones top-down
 (cada requisito tiene implementación) y bottom-up (nada huérfano: ni tests sin propósito ni
 código fuera del alcance de `hus[]`). Produce una matriz de trazabilidad; COHERENTE →
-`gates.coherence: true`. Complementa a `change-epic-coherence` verificando la implementación real.
+`releases[].gates.coherence: true`. Complementa a `change-epic-coherence` verificando la implementación real.
 
 ### `stack-guardian` · modelo `sonnet` · lee el dominio
-**Guardián del stack** (gate `stack`, arquitectura). Defiende la sección de requisitos
+**Guardián del stack** (gate `releases[].gates.stack_arch`, arquitectura; antes `gates.stack` por-slice). Defiende la sección de requisitos
 técnicos del PRD del consumidor (ruta en `stack-allowlist.json#source`), operacionalizada en
 `.claude/config/stack-allowlist.json`. Verifica que las **dependencias** matcheen la
 allowlist y que la **arquitectura** respete el stack declarado (frontend/runtime del
 consumidor; servicio externo/IA usado solo en su frontera server-side; capa de decisión del
 dominio determinista sin servicio no determinista cuando el PRD lo exige; persistencia sin PII
-regulada cruda) y señala anti-patrones. STACK-OK → `gates.stack: true`. El hook
+regulada cruda) y señala anti-patrones. STACK-OK → `releases[].gates.stack_arch: true`. El hook
 `stack-guard.sh` bloquea deps fuera de lista en tiempo real; este agente razona sobre
 arquitectura y uso.
 

package/docs/commands.md

@@ -2,8 +2,8 @@
 
 Esta referencia cubre los **dos planos de operación** del arnés de construcción:
 
-1. El **CLI `trycore-build`** (binario Node, paquete `@trycore/spec-build-harness` v0.3.0) — instala, actualiza, diagnostica y desinstala el arnés en el proyecto consumidor. Captura el **stack mecánico**.
-2. Los **slash commands de Claude Code** (`/opsx:*` + `/build:onboard` + `/build:reflect`) — operan el pipeline de dos loops, resuelven la parametrización **semántica** del dominio y capturan el conocimiento aprendido por slice.
+1. El **CLI `trycore-build`** (binario Node, paquete `@trycore/spec-build-harness` v0.7.0) — instala, actualiza, diagnostica y desinstala el arnés en el proyecto consumidor. Captura el **stack mecánico**.
+2. Los **slash commands de Claude Code** (`/opsx:*` + los 5 `/build:*`: `onboard`, `reflect`, `slice`, `release`, `work`) — operan el pipeline de dos loops, resuelven la parametrización **semántica** del dominio y capturan el conocimiento aprendido por slice.
 
 > **División de responsabilidades del onboarding (dos capas).** Un binario Node **no puede** escribir la auto-memory de Claude. Por eso `trycore-build init` siembra archivos y captura el stack mecánico (lenguaje/deps, package manager, runtime, ruta del PRD), y el slash command `/build:onboard` —ejecutado por Claude— lee el PRD, pregunta por PII / capa de servicios externos-IA / capa determinista / secretos / decisiones de alto impacto, resuelve los `{{placeholders}}` del bloque marcado de `CLAUDE.md` y escribe la auto-memory.
 
@@ -52,7 +52,7 @@ Solo `init` y `update` aceptan flags. `status`, `uninstall` y `doctor` toman ún
 
 ## 2. Slash commands de Claude Code
 
-El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y `.claude/commands/build/` → `/build:onboard` y `/build:reflect`.
+El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y `.claude/commands/build/` → los 5 `/build:*` (`onboard`, `reflect`, `slice`, `release`, `work`).
 
 ### `/opsx:*` — pipeline OpenSpec
 
@@ -69,6 +69,24 @@ El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y
 | `/opsx:onboard` | Onboarding guiado: recorre un ciclo completo del workflow OpenSpec con narración (tutorial de aprendizaje). |
 | `/opsx:sync` | Sincroniza los delta specs de un cambio hacia los specs principales. |
 
+### `/build:slice` — entrada del inner loop
+
+| Slash command | Propósito |
+|---|---|
+| `/build:slice` | Punto de entrada del **inner loop** sobre una épica (`EP-XXX`). Adaptador delgado: **delega** en la skill `building-a-slice` (o en el agente `build-orchestrator` para épicas multicapa) y conduce el pipeline `DoR → change → TDD → smoke → api/data → DoD → PR + archive` respetando el **orden estricto de gates**. Exige `scaffold.confirmed: true` (y `design_source.confirmed: true` si hay UI) como precondición; el arnés **lo exige pero no lo genera**. **Un solo slice activo** (secuencial). No dispara los reviewers pesados (eso es del Release Gate). |
+
+### `/build:release` — entrada del outer loop (Release Gate)
+
+| Slash command | Propósito |
+|---|---|
+| `/build:release` | Punto de entrada del **outer loop**: corre el **Release Gate UNA vez** sobre el diff acumulado de una release (no por épica). Dispara **en paralelo** los 5 reviewers pesados (`security` → `security-reviewer`, `smell` → `simple-design-reviewer`, `ux` → `ux-krug-reviewer`, `coherence` → `coherence-three-way`, `stack_arch` → `stack-guardian`) y luego el gate `integration` **secuencial** con dependencias reales (no stubs). Escribe `releases[].gates.{security,smell,ux,coherence,stack_arch}` y `status` vía la skill `releasing-a-version` (única escritora de `releases[]`). Lo **sugiere** el hook `release-gate-nudge.sh` al cerrar sesión. No duplica el inner loop (ni TDD ni gates por slice). |
+
+### `/build:work` — router classify-and-act
+
+| Slash command | Propósito |
+|---|---|
+| `/build:work` | **Router puro** (classify-and-act): clasifica el trabajo entrante y **delega** en la skill correcta — `building-a-micro-change` (mantenimiento), `building-a-slice` (épica / capacidad nueva) o `releasing-a-version` (Release Gate) — codificando el *decision gate* del micro-change y el default del Release Gate. Es **ruteo, no política**: no ejecuta el pipeline, no escribe `build-state.json` ni crea ramas. Aplica los **límites duros** del micro-change (dependencia nueva, endpoint/API nuevo, o tocar lógica de dominio / invariantes de datos → escala a épica) y, **ante la duda, SIEMPRE épica**. |
+
 ### `/build:onboard` — parametrización del dominio
 
 | Slash command | Propósito |
@@ -90,7 +108,7 @@ El arnés se distribuye por **dos canales** que coexisten, pero **namespacean di
 | Aspecto | Canal **CLI** (canónico) | Canal **Plugin** nativo |
 |---|---|---|
 | Instalación | `npm i -g @trycore/spec-build-harness` → `trycore-build init` | `/plugin marketplace add <repo-github>` → `/plugin install trycore-spec-build-harness@trycore-build` |
-| Namespace de comandos | Por subcarpeta: `/opsx:*`, `/build:onboard` y `/build:reflect` | Por nombre del plugin: `/trycore-spec-build-harness:*` (por diseño de Claude Code) |
+| Namespace de comandos | Por subcarpeta: `/opsx:*` y los 5 `/build:*` (`onboard`, `reflect`, `slice`, `release`, `work`) | Por nombre del plugin: `/trycore-spec-build-harness:*` (por diseño de Claude Code) |
 | Referencia a agentes | Por su nombre (p. ej. `build-orchestrator`) | Bajo el nombre del plugin |
 | Cross-references internas | ✔ Escritas para este canal (skills invocan `/opsx:*`, agentes por nombre) | Pueden no resolver según están escritas |
 | Recomendación | **Usar este canal para operar un proyecto** | Conveniencia a nivel usuario |

package/docs/customization/mcp-extensions.md

@@ -78,14 +78,15 @@ cada uno por el que aplique a **tu** stack declarado en el PRD; ninguno es oblig
 | `ux` (release) | `ux-krug-reviewer` | Navegador headless con auditoría tipo Lighthouse | Accesibilidad / Best-Practices y snapshots de la UI ensamblada de la release. | Revisión heurística Krug sobre el código + capturas manuales. |
 | `api` (inner) | `api-contract-tester` | **Newman corre por CLI, no es MCP** | Contratos de endpoints sobre una colección de pruebas. | Es la vía por defecto: se ejecuta vía Bash, sin MCP. |
 | `data` (inner) | `data-consistency-checker` | MCP de base de datos (solo si tu slice usa esa BD) | Consultas de lectura / describe de tablas para validar invariantes y consistencia. | Validación por tests contra un almacén embebido o cliente del stack. |
-| `coherence` / diseño | `coherence-three-way`, `simple-design-reviewer`, `stack-guardian` | **LSP del lenguaje** (p. ej. LSP de TypeScript en stacks TS tipados) | Seguir definiciones/referencias con precisión de compilador: trazar símbolo→test, detectar duplicación y uso real. Mejor ROI que `grep` en código tipado. | Navegación con `grep`/`glob` + lectura dirigida. |
+| `coherence` / `smell` / `stack_arch` (release) | `coherence-three-way`, `simple-design-reviewer`, `stack-guardian` | **LSP del lenguaje** (p. ej. LSP de TypeScript en stacks TS tipados) | Seguir definiciones/referencias con precisión de compilador: trazar símbolo→test, detectar duplicación y uso real. Mejor ROI que `grep` en código tipado. | Navegación con `grep`/`glob` + lectura dirigida. |
 | perf (opcional, **fuera del DoD**) | — | MCP de pruebas de carga (p. ej. un MCP de k6) | Carga/latencia si una HU de la épica lo exige explícitamente. | Omitir; no es un gate del arnés. |
 
 Notas de coherencia con el arnés:
 
-- En el **inner loop** los gates pesados (`security`, `smell`, `ux`, coherencia triple completa,
-  arquitectura, integración con deps reales) **no** se cierran por épica: corren **una vez por
-  release** en `releasing-a-version`. Habilita los MCP de esas fases pensando en el outer loop.
+- En el **inner loop** los gates pesados (`security`, `smell`, `ux`, `coherence` —coherencia triple
+  completa, distinta del `coherence_link` barato del inner—, `stack_arch` —arquitectura— e
+  `integration` con deps reales) **no** se cierran por épica: corren **una vez por release** en
+  `releasing-a-version`. Habilita los MCP de esas fases pensando en el outer loop.
 - El gate `api` usa **Newman por CLI**: es un ejemplo de que la herramienta de un gate **no tiene por
   qué ser un MCP**. Lo importante es la evidencia (los contratos responden), no el canal.
 - **Excepción única — `fidelity` en slices con UI.** Es el **único** gate donde un MCP es **requerido**,

package/docs/getting-started.md

@@ -16,9 +16,10 @@ trycore-build doctor     # verifica requisitos y hooks
 ```text
 # 3) En Claude Code (lo corre Claude, no la terminal)
 /build:onboard               # parametriza el dominio: lee tu PRD, resuelve los {{placeholders}}
-skill building-a-slice       # construye una épica: DoR → change → TDD → smoke → DoD → PR
+/build:slice                 # construye una épica: DoR → change → TDD → smoke → DoD → PR
 /build:reflect               # (opcional) captura aprendizajes del slice recién archivado
-skill releasing-a-version    # al cerrar una línea de release del Story Map
+/build:release               # al cerrar una línea de release del Story Map
+# /build:work                # (opcional) router: clasifica la tarea y la enruta (micro-change/slice/release)
 ```
 
 Eso es el ciclo completo. Lo de abajo explica cada paso.
@@ -47,7 +48,7 @@ npm i -g @fission-ai/openspec @trycore/spec-build-harness
 
 ## 2 · `trycore-build init` (terminal)
 
-Desde la raíz de tu proyecto. Es **idempotente** (re-correrlo es seguro) y siembra: **12 agentes**, **12 skills**, **10 comandos `/opsx:*`** + `/build:onboard` + `/build:reflect`, **9 hooks**, el estado vacío `.claude/state/build-state.json` (gitignored, nunca se sobreescribe) y el bloque `<!-- BEGIN trycore-build-harness -->` en tu `CLAUDE.md` con `{{placeholders}}` sin resolver.
+Desde la raíz de tu proyecto. Es **idempotente** (re-correrlo es seguro) y siembra: **12 agentes**, **13 skills** (`building-a-slice`, `building-a-micro-change`, `releasing-a-version` + 10 `openspec-*`), **10 comandos `/opsx:*`** + **5 comandos `/build:*`** (`onboard`, `slice`, `release`, `reflect`, `work`), **10 hooks**, el estado vacío `.claude/state/build-state.json` (gitignored, nunca se sobreescribe) y el bloque `<!-- BEGIN trycore-build-harness -->` en tu `CLAUDE.md` con `{{placeholders}}` sin resolver.
 
 ```bash
 trycore-build init
@@ -81,7 +82,7 @@ Si un punto no aplica, se registra como "no aplica" (no se deja como `{{...}}`).
 
 ## 4 · Construir un slice (Claude Code)
 
-**Un slice = una épica `EP-XXX` = un OpenSpec change = una rama = un PR.** Las HU de la épica son su alcance interno. Invoca `skill building-a-slice` (o pídelo en lenguaje natural: *"construye EP-001"*). Pipeline del **inner loop**:
+**Un slice = una épica `EP-XXX` = un OpenSpec change = una rama = un PR.** Las HU de la épica son su alcance interno. Invoca `/build:slice` —la entrada del **inner loop**— (o pídelo en lenguaje natural: *"construye EP-001"*; o deja que `/build:work` clasifique y enrute la tarea). Pipeline del **inner loop**:
 
 ```
 DoR → change (+ trazabilidad) → TDD → journey-smoke (+ fidelidad si hay UI) → api/data → DoD reducido → PR + archive
@@ -99,7 +100,7 @@ Lo que importa:
 
 ## 5 · Release Gate (Claude Code, por release)
 
-Al archivar una épica, la skill te **pregunta** si correr el Release Gate (default computado desde las líneas de release del Story Map). `skill releasing-a-version` corre las **revisiones pesadas una sola vez** sobre el diff acumulado:
+Al archivar una épica, la skill te **pregunta** si correr el Release Gate (default computado desde las líneas de release del Story Map; lo respalda el hook `release-gate-nudge`, que solo **sugiere** y nunca ejecuta trabajo pesado). `/build:release` (outer loop) corre las **revisiones pesadas una sola vez** sobre el diff acumulado:
 
 | Gate | Delega en |
 |---|---|

package/docs/hooks.md

@@ -1,12 +1,12 @@
 # Hooks del arnés de construcción
 
-Este documento describe los **9 hooks** que `@trycore/spec-build-harness` instala en el proyecto del consumidor. Todos viven en `hooks/build/` (un script bash por hook) y se cablean a los eventos de Claude Code mediante una **cadena de comando única**, idéntica en ambos canales de instalación.
+Este documento describe los **10 hooks** que `@trycore/spec-build-harness` instala en el proyecto del consumidor. Todos viven en `hooks/build/` (un script bash por hook) y se cablean a los eventos de Claude Code mediante una **cadena de comando única**, idéntica en ambos canales de instalación.
 
-Los hooks son el sistema nervioso del arnés: vigilan GitFlow, el stack declarado, el scaffold y la fuente de diseño (bloqueantes), inyectan el estado del build al iniciar la sesión, delegan estilo/typecheck a herramientas, y recuerdan validar trazabilidad, gates abiertos y reflexionar al cerrar un slice. No reemplazan a los agentes ni a las skills; los **complementan** liberando capacidad de razonamiento del modelo y poniendo barandillas mecánicas donde un olvido cuesta caro.
+Los hooks son el sistema nervioso del arnés: vigilan GitFlow, el stack declarado, el scaffold y la fuente de diseño (bloqueantes), inyectan el estado del build al iniciar la sesión, delegan estilo/typecheck a herramientas, y recuerdan validar trazabilidad, gates abiertos, reflexionar al cerrar un slice y correr el Release Gate cuando se acumulan épicas sin auditar. No reemplazan a los agentes ni a las skills; los **complementan** liberando capacidad de razonamiento del modelo y poniendo barandillas mecánicas donde un olvido cuesta caro.
 
 ---
 
-## Resumen de los 9 hooks
+## Resumen de los 10 hooks
 
 | Hook | Evento | Matcher | Qué hace | ¿Bloqueante? |
 |---|---|---|---|---|
@@ -19,8 +19,9 @@ Los hooks son el sistema nervioso del arnés: vigilan GitFlow, el stack declarad
 | `coherence-flag.sh` | `PostToolUse` | `Write\|Edit\|MultiEdit` | Recuerda validar la trazabilidad de un `proposal.md` de OpenSpec recién tocado. | No |
 | `build-gate-check.sh` | `Stop` | `.*` | Al cerrar el turno, avisa si el slice activo tiene gates abiertos. | No |
 | `reflect-nudge.sh` | `Stop` | `.*` | Al cerrar el turno, sugiere `/build:reflect` si hay slice(s) archivado(s) sin reflexionar (`reflected != true`). | No |
+| `release-gate-nudge.sh` | `Stop` | `.*` | Al cerrar el turno, sugiere correr el Release Gate (`/build:release`) cuando hay ≥2 épicas archivadas sin auditar desde el último release. Determinista; solo sugiere. | No |
 
-> Cuatro bloqueantes (`gitflow-guard`, `stack-guard`, `scaffold-guard`, `design-source-guard`) y cinco informativos. Los bloqueantes usan `exit 2`: Claude Code devuelve el `stderr` al modelo y aborta la herramienta; el resto siempre sale `0`.
+> Cuatro bloqueantes (`gitflow-guard`, `stack-guard`, `scaffold-guard`, `design-source-guard`) y seis informativos. Los bloqueantes usan `exit 2`: Claude Code devuelve el `stderr` al modelo y aborta la herramienta; el resto siempre sale `0`.
 
 ---
 
@@ -89,6 +90,10 @@ Cierra el **ciclo autocorrectivo**. Al terminar el turno, si en `history[]` hay
 
 Refuerza el **seguro de fuente de diseño** (espejo de `scaffold-guard`, para slices con UI). Bloquea con `exit 2` la escritura de **código de un slice con UI** —cuando `active_slice.phase` ∈ `red`/`green`/`refactor`/`smoke`/`api`/`data` **y** `active_slice.gates.fidelity === false` (marcado UI-pendiente por la DoR)— mientras el proyecto tenga UI (`design_source.applies === true`) y `design_source.confirmed` no sea `true`. **Permite** todo lo demás: slices sin UI (`gates.fidelity === null` o ausente), proyectos sin UI (`applies !== true`), fases de planificación (`dor`/`change`), o fuente ya confirmada. El arnés **exige** la fuente de diseño pero **no genera** el prototipo; la confirmación es **explícita** (vía `building-a-slice` Fase 0-bis / `dor-dod-gatekeeper`), nunca auto-detectada. Guarda `python3` fail-closed dirigido. En la práctica, como `design_source` es gate de proyecto, solo muerde la **primera** construcción de UI sin fuente declarada.
 
+### 10. `release-gate-nudge.sh` — `Stop` · no bloqueante (desde v0.7.0)
+
+Cierra el lazo del **outer loop**. Al terminar el turno, cuenta las épicas **archivadas** (`history[].epica`) que **ningún** release ha cubierto todavía (`releases[].epicas`); si quedan **≥2 épicas sin auditar**, imprime un *nudge* sugiriendo ejecutar `/build:release` (o la skill `releasing-a-version`) para correr los gates pesados **una sola vez** sobre el diff acumulado. Es puramente determinista: **aritmética de conjuntos** (archivadas − cubiertas) independiente de *timestamps*, sin consultar fechas ni el criterio de "cierre de línea de release" (eso lo computa la skill `building-a-slice` en su fase de cierre). **Nunca bloquea** el cierre, **nunca** ejecuta trabajo pesado, **nunca** llama al modelo ni escribe el estado; si falta `python3` o el estado, sale `0` en silencio (**fail-open**).
+
 ---
 
 ## La cadena de comando única (sin doble disparo entre canales)
@@ -113,7 +118,7 @@ Como la cadena es **carácter por carácter idéntica** en ambos canales, si el
 Los hooks parsean el JSON del evento con `python3`. Qué pasa si **falta** `python3` depende de si el hook es bloqueante:
 
 - **Bloqueantes** (`gitflow-guard`, `stack-guard`, `scaffold-guard`, `design-source-guard`) → **fail-closed dirigido**: si no pueden analizar el comando/edición, solo bloquean (`exit 2`) cuando la entrada *cruda* parece relevante (un `git commit`/`push`, una edición que menciona `package.json`, o código de slice sin scaffold/fuente de diseño confirmados); en cualquier otro caso salen `0`. Esto evita falsos negativos peligrosos sin frenar el trabajo no relacionado. El mensaje pide instalar `python3` (verificable con `trycore-build doctor`).
-- **No bloqueantes** (`load-build-state`, `lint-typecheck`, `coherence-flag`, `build-gate-check`, `reflect-nudge`) → si falta `python3`, simplemente **omiten** su trabajo y salen `0` (fail-open).
+- **No bloqueantes** (`load-build-state`, `lint-typecheck`, `coherence-flag`, `build-gate-check`, `reflect-nudge`, `release-gate-nudge`) → si falta `python3`, simplemente **omiten** su trabajo y salen `0` (fail-open).
 
 > `python3` es un **requisito duro**: `trycore-build init` y `trycore-build doctor` **fallan** si no está presente, justo porque toda la cadena de hooks depende de él para leer el JSON del evento.
 
@@ -134,6 +139,7 @@ Los hooks que tocan el código construido se **auto-arman**: permanecen **inerte
 | `design-source-guard.sh` | Permite (sin slice UI en fases de código, o sin `design_source.applies=true`, no hay nada que bloquear). |
 | `build-gate-check.sh` | Inerte (sale `0` de inmediato). |
 | `reflect-nudge.sh` | Silencioso (en `authoring` no hay slices archivados que reflexionar). |
+| `release-gate-nudge.sh` | Silencioso (en `authoring` no hay épicas archivadas que auditar). |
 
 Así el arnés convive sin fricción con la fase de *discovery* y se "enciende" cuando empieza la construcción real.
 
@@ -147,7 +153,7 @@ Una sola definición de hooks, expresada en dos archivos espejo según el canal:
 
 `trycore-build init` hace un **merge idempotente y aditivo** en el `settings.json` del consumidor (lógica en `src/lib/settings-merge.ts`; espejo documental en `templates/settings-hooks.template.json`):
 
-- Agrega las 5 agrupaciones de hooks (las 9 invocaciones: `PreToolUse·Write` agrupa `stack-guard` + `scaffold-guard` + `design-source-guard`; `PostToolUse·Write` agrupa `lint-typecheck` + `coherence-flag`; `Stop` agrupa `build-gate-check` + `reflect-nudge`) sin pisar lo que ya exista.
+- Agrega las 5 agrupaciones de hooks (10 invocaciones: `PreToolUse·Write` agrupa `stack-guard` + `scaffold-guard` + `design-source-guard`; `PostToolUse·Write` agrupa `lint-typecheck` + `coherence-flag`; `Stop` agrupa `build-gate-check` + `reflect-nudge` + `release-gate-nudge`) sin pisar lo que ya exista. Ambos canales (CLI y plugin) cablean las **mismas 10 invocaciones**.
 - Agrega **permisos mínimos y enumerados** (sin `mcp__*` ni rutas absolutas):
 
   ```
@@ -160,6 +166,6 @@ Una sola definición de hooks, expresada en dos archivos espejo según el canal:
 
 ### Canal plugin — `hooks/build-harness.json`
 
-El plugin declara los hooks en `hooks/build-harness.json` (referenciado desde `.claude-plugin/plugin.json` con `"hooks": "./hooks/build-harness.json"`). El contenido es **equivalente** al bloque que mergea el CLI y usa la **misma cadena de comando**.
+El plugin declara los hooks en `hooks/build-harness.json` (referenciado desde `.claude-plugin/plugin.json` con `"hooks": "./hooks/build-harness.json"`) y usa la **misma cadena de comando**. Es el bloque más completo: su grupo `Stop` cablea las **3** invocaciones (`build-gate-check` + `reflect-nudge` + `release-gate-nudge`), por lo que el canal plugin suma las **10** invocaciones. La única diferencia con el merge del CLI es ese `release-gate-nudge.sh`; las otras 4 agrupaciones son idénticas. Si un consumidor instala ambos canales, las cadenas comunes se deduplican (ver arriba) y `release-gate-nudge.sh` lo aporta el plugin.
 
 > **Caveat de canales:** el canal CLI es el **canónico** para operar en un proyecto. El plugin namespacea los componentes bajo el nombre del plugin (`/trycore-spec-build-harness:*`) por diseño de Claude Code; las cross-references internas (skills que invocan `/opsx:*`, agentes por nombre) están escritas para el canal CLI. Los **hooks**, en cambio, son idénticos en ambos canales y se deduplican si coexisten.

package/hooks/build/build-gate-check.sh

@@ -18,7 +18,9 @@ if not s: sys.exit(0)
 g=s.get("gates",{})
 abiertos=[k for k,v in g.items() if v is False]
 if abiertos:
-    print(f"build-gate-check: slice {s.get('hu')} en fase '{s.get('phase')}' con gates abiertos: {', '.join(abiertos)}.", file=sys.stderr)
+    epica=s.get('epica') or '?'
+    hus=', '.join(s.get('hus') or []) or '—'
+    print(f"build-gate-check: slice {epica} [{hus}] en fase '{s.get('phase')}' con gates abiertos: {', '.join(abiertos)}.", file=sys.stderr)
     print("   No archives ni abras PR hasta cerrarlos (ver building-a-slice / dod.md).", file=sys.stderr)
 PY
 exit 0

package/hooks/build/load-build-state.sh

@@ -12,15 +12,37 @@ BRANCH="$(git -C "$ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'descon
 if [ -f "$ROOT/package.json" ]; then PHASE="active"; else PHASE="authoring"; fi
 
 # Sincroniza harness_phase en el estado (si python3 disponible y el archivo existe).
+# Escritura ATÓMICA + validada: este hook corre en CADA SessionStart (alta frecuencia,
+# headless incluido); una escritura no atómica que se interrumpa truncaría la ÚNICA
+# fuente de verdad. Solo escribe si harness_phase cambia; si algo falla, deja el original
+# intacto (fail-open) y nunca rompe el SessionStart.
 if [ -f "$STATE" ] && command -v python3 >/dev/null 2>&1; then
   python3 - "$STATE" "$PHASE" <<'PY' 2>/dev/null || true
-import json,sys
+import json,sys,os,tempfile
 path,phase=sys.argv[1],sys.argv[2]
 try:
-    d=json.load(open(path))
-    if d.get("harness_phase")!=phase:
-        d["harness_phase"]=phase
-        json.dump(d,open(path,"w"),indent=2,ensure_ascii=False)
+    with open(path) as fh:
+        d=json.load(fh)
+    # No escribir si no hay cambio.
+    if d.get("harness_phase")==phase:
+        sys.exit(0)
+    # Validación mínima de forma antes de tocar disco (no relajamos el schema completo,
+    # solo evitamos persistir algo que claramente no es un build-state).
+    if not isinstance(d,dict) or not all(k in d for k in ("version","harness_phase","active_slice","history","releases")):
+        sys.exit(0)
+    d["harness_phase"]=phase
+    dirn=os.path.dirname(path) or "."
+    fd,tmp=tempfile.mkstemp(dir=dirn,prefix=".build-state.",suffix=".tmp")
+    try:
+        with os.fdopen(fd,"w") as out:
+            json.dump(d,out,indent=2,ensure_ascii=False)
+            out.flush()
+            os.fsync(out.fileno())
+        os.replace(tmp,path)  # sustitución atómica
+    except Exception:
+        try: os.unlink(tmp)
+        except OSError: pass
+        raise
 except Exception:
     pass
 PY