@trycore/spec-build-harness 0.7.1 → 0.8.1

package/docs/decisiones/2026-07-03-gsd-vs-openspec-fork-vs-rama.md

@@ -0,0 +1,157 @@
+# Evaluación: ¿reemplazar el harness OpenSpec por GSD? ¿fork o rama?
+
+- **Fecha:** 2026-07-03
+- **Estado:** Decidido — ver **Actualización post-análisis de código** al final. Diseño en [`docs/superpowers/specs/2026-07-03-harness-context-engine-design.md`](../superpowers/specs/2026-07-03-harness-context-engine-design.md)
+- **Autor:** Jhonata.segura (asistido)
+- **Repo evaluado:** `@trycore/spec-build-harness` v0.7.1
+- **Candidato:** `open-gsd/gsd-core` (GSD — "Git. Ship. Done"), MIT
+- **Insumo relacionado:** `gsd-template.md` (PRD "Orquestador Semántico Determinista", análisis de 4 agentes)
+
+---
+
+## 1. Pregunta a resolver
+
+Dos preguntas, una depende de la otra:
+
+1. **¿Debemos reemplazar OpenSpec por GSD** como base del harness de construcción, motivado por que "los foros dicen que GSD es más nativo con Claude Code, usa mejor el contexto y es más eficiente"?
+2. **Si avanzamos, ¿fork de gsd-core o rama en este repo?**
+
+Este documento responde ambas con evidencia y deja una recomendación. No modifica arquitectura.
+
+---
+
+## 2. Punto de partida: qué es hoy el harness y qué papel juega OpenSpec
+
+`@trycore/spec-build-harness` no *es* OpenSpec: es un **arnés propio** que orquesta a Claude Code con arquitectura de **dos loops** (slice por épica con TDD + gates → release gate), **12 agentes de build** (coherence three-way, security-reviewer, wiring-adversarial-verifier, ux-krug, dor-dod-gatekeeper, stack-guardian, etc.), estado compartido, hooks y una **metodología documentada en español** (`METODOLOGIA.md`, `GOVERNANCE.md`). Es el compañero de `@trycore/spec-product-flow` (Discovery → Construcción).
+
+OpenSpec (`@fission-ai/openspec`) es **una pieza dentro**, no el todo. Aporta el **modelo de spec basado en cambios**: `changes/` (propuesta) → implementación → `archive` hacia `specs/`. Se expresa como:
+
+- **55 referencias** en el repo (`grep -ril openspec`).
+- Namespace `/opsx:*` — 10 comandos (`new`, `apply`, `archive`, `bulk-archive`, `continue`, `explore`, `ff`, `onboard`, `sync`, `verify`).
+- 8 skills `openspec-*` (todas con `Requires openspec CLI` y licencia MIT — son wrappers del CLI de OpenSpec).
+- Dependencia externa: `npm install -g @fission-ai/openspec`.
+
+**Conclusión de esta sección:** "reemplazar OpenSpec" ≠ "reemplazar el harness". OpenSpec es la **capa de gobernanza de spec** (propuesta de cambio → archivo). El valor diferencial de Trycore (dos loops, gates, agentes, metodología, coexistencia con product-flow) **no vive en OpenSpec**.
+
+---
+
+## 3. Qué es realmente GSD (verificado, no de oídas)
+
+GSD es un framework de **context-engineering + spec-driven** mucho **más grande y ambicioso** que nuestra capa OpenSpec:
+
+- **Loop de 5 fases:** Discuss → Plan → Execute → Verify → Ship, repetido por *milestones*.
+- **~55+ comandos** (`/gsd-*`): incluye planificación con convergencia cross-AI, ejecución en *waves* paralelas, *workstreams*, knowledge graph (`/gsd-graphify`), memory palace temporal (`/gsd-mempalace-*`), auditorías de milestone/UAT/seguridad, code-review, audit-fix, spikes, forensics, etc.
+- **Estado en archivos planos:** `STATE.md`, `CONTEXT.md`, `ROADMAP.md`, `.planning/` — con comandos de validación (`state validate`, `roadmap validate`).
+- **Multi-runtime:** Claude Code, Codex, Gemini CLI, Kimi, Copilot, Cursor, Windsurf… vía instalador (`npx @opengsd/gsd-core@latest`). **No se copian `agents/`/`commands/` a mano.**
+- **Licencia MIT.** Fork legalmente trivial.
+- **Escala/actividad:** ~48K estrellas; v1.34.2 el 2026-04-06; **1.693 commits en 47 releases** desde dic-2025. Es un proyecto que se mueve rápido.
+
+### 3.1 ¿Son ciertas las afirmaciones de los foros?
+
+| Afirmación de foro | Veredicto | Matiz |
+|---|---|---|
+| "Más nativo con Claude Code" | **Parcialmente cierto** | Nació Claude-Code-first y es lo más maduro ahí, pero hoy se posiciona **multi-runtime**. "Nativo" real = su patrón de *fresh-context subagents* encaja muy bien con el modelo de subagentes de Claude Code. |
+| "Usa mejor el contexto" | **Cierto en el patrón** | El núcleo — ejecutar research/plan/execute en **subagentes de contexto fresco (~200k)** manteniendo la sesión principal ligera — es una respuesta genuinamente buena al *context rot*. Es la idea que la comunidad realmente elogia. |
+| "Más eficiente" | **No demostrado como número** | El README no publica benchmarks de tokens. La eficiencia proviene del patrón, no de una métrica auditada. Ojo: fresh-context tiene su propio **"impuesto de arranque"** (reinyección) — es exactamente lo que critica tu PRD §2.2. |
+
+**Lo importante:** lo que los foros elogian de GSD es un **patrón de ejecución** (subagentes de contexto fresco + estado externalizado), *no* un motor de spec que haga a OpenSpec obsoleto. Ese patrón es **adoptable sin reemplazar OpenSpec**.
+
+---
+
+## 4. Solapamiento, brechas y choque de modelos
+
+| Capacidad | Harness actual | GSD | Lectura |
+|---|---|---|---|
+| Gobernanza de spec | OpenSpec `changes/ → specs/` (brownfield, delta por cambio) | `ROADMAP.md` + fases/milestones (`.planning/`) | **Modelos distintos.** OpenSpec = delta de cambio archivable; GSD = roadmap de fases. Migrar es re-conceptualizar, no un swap. |
+| Ejecución / context rot | Slices + orquestador propio | **Waves paralelas en subagentes frescos** | GSD es **más fuerte** aquí. Es la joya a mirar. |
+| Gates de calidad | 12 agentes Trycore + release gate | code-review, audit-fix, secure-phase, verify | **Solapan.** Adoptar GSD nos obliga a re-hospedar o botar nuestros agentes. |
+| TDD / Gitflow / release gate | **Explícito** (nuestro valor) | Ship/PR + verify; TDD/gitflow **no formalizados** | Perdemos rigor si migramos crudo. |
+| Metodología en español + product-flow | **Sí** (diferencial Trycore) | No existe | Se re-implementa igual, migremos o no. |
+| Extensibilidad | Nuestra, total | Vía instalador/capabilities/overlays; **no copiar archivos a mano** | Forkear = pelear contra su modelo de instalación. |
+
+**Choque clave:** OpenSpec gobierna **el cambio** (delta propuesto y archivado); GSD gobierna **el plan** (fases de un roadmap). No son intercambiables 1:1; "reemplazar" implicaría rehacer cómo pensamos la unidad de trabajo.
+
+---
+
+## 5. Riesgos de adoptar/forkear GSD
+
+1. **Gobernanza inestable (riesgo alto).** El proyecto original tuvo un incidente (meme-coin) y **el autor original ya no participa**. Hoy conviven `open-gsd/gsd-core`, `open-gsd/get-shit-done-redux` y otros forks. Atarnos a un upstream en plena reorganización de gobernanza es riesgo de cadena de suministro y de dirección.
+2. **Velocidad de upstream (riesgo de mantenimiento).** 47 releases / 1.693 commits en ~4 meses. Un **fork** nos obliga a un *sync* costoso y perpetuo, o a divergir y perder el motivo de forkear.
+3. **Superficie enorme.** ~55 comandos y subsistemas (knowledge graph, memory palace, cross-AI). Adoptarlo entero es asumir complejidad que **no pediste** (YAGNI) y que solapa lo nuestro.
+4. **Modelo de instalación cerrado.** "No copies `agents/`/`commands/`" → un fork/patch integrado con nuestro CLI (`trycore-build init`) va a contracorriente de su diseño.
+5. **Contradice tu propio PRD.** El consenso de los 4 agentes en `gsd-template.md` es explícito: *"El Orquestador… no reemplaza a GSD ni a Claude Code — se inserta entre ellos"*. Es decir, tu análisis ya descartó "reemplazar".
+
+---
+
+## 6. Opciones de estrategia de repositorio
+
+### Opción A — Rama en este repo (evolución in-place) ✅ recomendada para empezar
+Crear `spike/gsd-eval` (y luego `feature/…`) **en este mismo repo**. Adoptar **el patrón que sí vale de GSD** (ejecución en subagentes de contexto fresco / waves) dentro de nuestra arquitectura, **conservando** OpenSpec como gobernanza de cambio y nuestros gates.
+- **Pro:** control total, mantiene identidad Trycore y coexistencia con product-flow; reversible; publicable como v0.8/v1.0; cero riesgo de gobernanza externa.
+- **Contra:** reimplementamos el patrón (no heredamos el código de GSD).
+
+### Opción B — Fork de `gsd-core`
+Partir de su base MIT y montar gates/metodología encima.
+- **Pro:** heredamos madurez (waves, graph, memory palace).
+- **Contra:** **el más caro y arriesgado** — sync perpetuo con upstream velocísimo, gobernanza inestable, superficie que no queremos, choque con nuestro CLI e instalación. Botamos o duplicamos nuestros 12 agentes y los dos loops.
+
+### Opción C — GSD como dependencia (wrap, igual que hoy con OpenSpec)
+No forkear: invocar el CLI de GSD desde nuestro harness, como orquestamos OpenSpec hoy.
+- **Pro:** bajo mantenimiento; nos beneficiamos de upstream sin cargarlo.
+- **Contra:** dependemos de su CLI/estado; dos modelos de spec conviviendo (OpenSpec + GSD) puede confundir; seguimos expuestos a su gobernanza en runtime.
+
+### Opción D — Greenfield: el "Orquestador" del PRD (visión larga)
+Construir el plano de control determinista + datos semánticos (MCP a nivel símbolo + estado tipado) que describe `gsd-template.md`. GSD queda como capa metodológica, no como reemplazo.
+- **Pro:** ataca la métrica real (tokens/rework/first-time-pass) según tu propio análisis.
+- **Contra:** mayor esfuerzo; fuera del alcance de "una versión nueva del harness" ahora.
+
+---
+
+## 7. Recomendación
+
+**No forkear gsd-core y no arrancar OpenSpec a ciegas.** En concreto:
+
+1. **Reencuadrar el objetivo.** Lo que la comunidad elogia de GSD y lo que tú buscas ("mejor uso de contexto, más eficiente") es un **patrón de ejecución** (subagentes de contexto fresco + estado externalizado), **no** un motor de spec que reemplace a OpenSpec. Perseguir ese patrón ≠ reemplazar OpenSpec.
+2. **Opción A (rama en este repo) para un spike acotado.** Validar el patrón de contexto fresco dentro de nuestra arquitectura, midiendo contra un baseline. Reversible y publicable.
+3. **Descartar la Opción B (fork)** salvo que decidamos, con datos del spike, comprometer GSD como *motor* y aceptar el costo de mantenimiento/gobernanza. Hoy el riesgo de gobernanza (autor fuera, forks múltiples) lo hace desaconsejable.
+4. **Mantener la Opción D (orquestador del PRD) como norte de largo plazo**, no como esta release. Coincide con el consenso de tu propio PRD: *insertar entre*, no reemplazar.
+
+En una frase: **la próxima versión del harness debería robarle a GSD la *idea* (ejecución en contexto fresco), no el *repositorio*.**
+
+---
+
+## 8. Spike de validación propuesto (si se aprueba avanzar)
+
+Rama `spike/gsd-eval`, alcance de días, criterios de éxito medibles:
+
+1. **Baseline.** Correr un slice representativo con el harness actual; registrar tokens de entrada, nº de llamadas a herramientas, rework y first-time-pass.
+2. **Variante A (patrón GSD, sin GSD).** Reimplementar la ejecución del slice en **subagentes de contexto fresco** (ya tenemos `Agent`/waves nativos de Claude Code) manteniendo OpenSpec + gates. Medir lo mismo.
+3. **Variante B (GSD como dependencia, opcional).** Instalar `gsd-core` en un proyecto de prueba y comparar su Execute-phase contra nuestro slice, para calibrar cuánto valor real añade su motor vs. reimplementarlo.
+4. **Decisión.** Con las tres mediciones, elegir entre: (a) adoptar solo el patrón (Opción A), (b) wrap de GSD (Opción C), o (c) invertir en el orquestador (Opción D). Sólo entonces se justificaría —o no— un fork.
+
+**Criterio de descarte de fork:** si el spike no muestra ≥30% de mejora de tokens/rework atribuible al *código* de GSD (y no solo al patrón), no forkear.
+
+---
+
+## 9. Fuentes
+
+- [open-gsd/gsd-core (GitHub)](https://github.com/open-gsd/gsd-core)
+- [GSD hits 48K stars — Augment Code](https://www.augmentcode.com/learn/gsd-stars-spec-driven-dev-claude-code)
+- [The Anatomy of Claude Code Workflows (GSD deep dive) — codecentric](https://www.codecentric.de/en/knowledge-hub/blog/the-anatomy-of-claude-code-workflows-turning-slash-commands-into-an-ai-development-system)
+- [Superpowers, GSD, and gstack: what each constrains — Ewan Mak (Medium)](https://medium.com/@tentenco/superpowers-gsd-and-gstack-what-each-claude-code-framework-actually-constrains-12a1560960ad)
+- [GSD vs Spec Kit vs OpenSpec vs Taskmaster — Rick Hightower (Medium)](https://medium.com/@richardhightower/agentic-coding-gsd-vs-spec-kit-vs-openspec-vs-taskmaster-ai-where-sdd-tools-diverge-0414dcb97e46)
+- Interno: `gsd-template.md` (PRD "Orquestador Semántico Determinista"), `README.md`, `METODOLOGIA.md`, skills `openspec-*`.
+
+---
+
+## 10. Actualización post-análisis de código (2026-07-03)
+
+Se clonó `gsd-core` y se leyó su ingeniería real (5 exploradores, evidencia `file:line`). Confirma y **cierra** las decisiones:
+
+1. **NO forkear — confirmado con datos.** `git log --since=30d` = **861 commits**; sin campo `exports` (no es librería); artefactos compilados en `.gitignore`; instalador monolítico de **11.740 líneas**; 3 sistemas de toggles entrelazados. No hay costura estable para depender. Los patrones valiosos son portables (MIT) sin el motor.
+2. **El dolor real (reinicio manual) NO lo resuelve GSD tampoco:** GSD deja el `/clear` manual (filosofía #884). Su valor = **aviso temprano (hook a 35%/25%) + handoff sin pérdida**. Eso es lo adoptable, y es pequeño/portable.
+3. **Nuestro estado tipado ≥ el de GSD** (JSON schema vs Markdown+regex); GSD compensa con **derivación desde disco** — esa *idea* sí vale robarla.
+4. **Worktrees:** GSD paraleliza solo lo disjunto en archivos + seguro en el DAG, con serializador de solapes. Adoptamos el patrón a nivel **inter-épica** (no fundacionales, disjuntas).
+5. Lo *hypeado* (memory-palace, knowledge graph) es lo *menos* propio de GSD (MCP/Python externos). Descartado por ahora.
+
+**Veredicto final:** rama en este repo (`feature/gsd-context-engine`), robar patrones de contexto + estado-en-disco + worktrees inter-épica. Diseño detallado en el spec enlazado arriba.

package/docs/hooks.md

@@ -1,27 +1,32 @@
 # Hooks del arnés de construcció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.
+Este documento describe los **13 hooks** que `@trycore/spec-build-harness` instala en el proyecto del consumidor. Todos viven en `hooks/build/` (un script bash o python por hook, más el helper compartido `lib/state-io.sh`) 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, 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.
+Los hooks son el sistema nervioso del arnés: vigilan GitFlow, el stack declarado, el scaffold y la fuente de diseño (bloqueantes), inyectan y re-anclan el estado del build al iniciar la sesión, delegan estilo/typecheck a herramientas, vigilan la presión de contexto y escriben handoff automático, 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 10 hooks
+## Resumen de los 13 hooks
 
 | Hook | Evento | Matcher | Qué hace | ¿Bloqueante? |
 |---|---|---|---|---|
-| `load-build-state.sh` | `SessionStart` | `startup\|clear\|compact` | Inyecta al contexto la rama, la fase del arnés, el slice activo y los gates abiertos; sincroniza `harness_phase`. | No |
+| `load-build-state.sh` | `SessionStart` | `startup\|clear\|compact` | Inyecta al contexto la rama, la fase del arnés, el slice activo y los gates abiertos; sincroniza `harness_phase`. Invoca a `reconcile-build-state.py` antes de leer el estado. | No |
+| `reconcile-build-state.py` | `SessionStart` (invocado por `load-build-state.sh`) | — | Ancla `build-state.json` a la realidad de git + tests: degrada a `failing` los items de `wiring_checklist` marcados `passing` sin `evidence`, y anota (sin corregir) el *drift* entre la rama real y `active_slice.branch`. Nunca revierte gates `true→false`. | No |
+| `statusline-bridge.sh` | `statusLine` (comando, no evento de hooks; solo canal CLI) | — | Imprime la línea de estado (`🏗️ build · ctx N%`) y escribe el archivo-puente de contexto (`claude-ctx-<session>.json`) que `context-monitor.sh` consume para calcular la presión de contexto. | No |
 | `gitflow-guard.sh` | `PreToolUse` | `Bash` | Enforce GitHub Flow estricto sobre `git commit` / `git push`. | **Sí (exit 2)** |
 | `stack-guard.sh` | `PreToolUse` | `Write\|Edit\|MultiEdit` | Bloquea dependencias en `package.json` fuera de la allowlist del stack del PRD. | **Sí (exit 2)** |
 | `scaffold-guard.sh` | `PreToolUse` | `Write\|Edit\|MultiEdit` | Bloquea escribir código de slice (fases `red…data`) si el scaffold no está confirmado (`scaffold.confirmed`). | **Sí (exit 2)** |
 | `design-source-guard.sh` | `PreToolUse` | `Write\|Edit\|MultiEdit` | Bloquea escribir código de un slice **con UI** (`gates.fidelity===false`, fases `red…data`) si la fuente de diseño del proyecto no está confirmada (`design_source.confirmed`). | **Sí (exit 2)** |
 | `lint-typecheck.sh` | `PostToolUse` | `Write\|Edit\|MultiEdit` | Corre prettier/eslint/tsc sobre el archivo `.ts`/`.tsx` editado. | No |
 | `coherence-flag.sh` | `PostToolUse` | `Write\|Edit\|MultiEdit` | Recuerda validar la trazabilidad de un `proposal.md` de OpenSpec recién tocado. | No |
+| `context-monitor.sh` | `PostToolUse` \| `PreCompact` \| `Stop` | `Bash\|Edit\|Write\|MultiEdit\|Task` (`PostToolUse`) · `.*` (`PreCompact`/`Stop`) | Lee el puente de contexto de `statusline-bridge.sh`, aplica los umbrales `context.warning_pct`/`context.critical_pct` y, si está por debajo, inyecta `additionalContext` de advertencia; en `critical` escribe una sola vez por sesión el handoff (`active_slice.session_continuity`) en `build-state.json`. | 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 seis 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 nueve informativos. Los bloqueantes usan `exit 2`: Claude Code devuelve el `stderr` al modelo y aborta la herramienta; el resto siempre sale `0`.
+>
+> `lib/state-io.sh` no es un hook: es el **helper compartido** (`state_path`, `config_get`, `state_atomic_patch`) que usan `context-monitor.sh` y otros scripts para resolver la ruta del estado, leer `config/build-config.json` y escribir patches atómicos.
 
 ---
 
@@ -94,6 +99,18 @@ Refuerza el **seguro de fuente de diseño** (espejo de `scaffold-guard`, para sl
 
 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**).
 
+### 11. `statusline-bridge.sh` — comando `statusLine` · no bloqueante (desde v0.8.0)
+
+Es el motor de contexto visto desde la barra de estado. No es un hook de evento: es el comando que Claude Code invoca para renderizar el `statusLine` (solo canal CLI; el plugin no puede inyectar `statusLine`). Lee el payload por `stdin`, calcula `remaining_pct` desde `context_window.remaining_percentage` y escribe atómicamente el archivo-puente `claude-ctx-<session_id>.json` (nombre de sesión saneado contra *path traversal*) para que `context-monitor.sh` lo consuma. Imprime siempre una línea (`🏗️ build` o `🏗️ build · ctx N%`); si falta `python3` o el payload no trae el dato, degrada sin romper la barra (**fail-open**).
+
+### 12. `context-monitor.sh` — `PostToolUse` / `PreCompact` / `Stop` · no bloqueante (desde v0.8.0)
+
+Es la vigilancia de **presión de contexto**. Se dispara tras herramientas (`PostToolUse`, matcher `Bash|Edit|Write|MultiEdit|Task`), antes de compactar (`PreCompact`) y al cerrar el turno (`Stop`). Lee el puente que escribió `statusline-bridge.sh` (ignora lecturas más viejas que `context.stale_seconds`) y compara `remaining_pct` contra `context.warning_pct`/`context.critical_pct` (leídos vía `lib/state-io.sh#config_get`, con defaults 35/25). En `warning` inyecta `additionalContext` pidiendo buscar un punto de corte natural. En `critical`, y **una sola vez por sesión** (`active_slice.session_continuity.critical_recorded`), escribe el handoff en `build-state.json`: `stopped_at`, `resume_hint` (a partir de los items `failing` de `wiring_checklist`) y un hito en `progress_log[]`; si `context.auto_checkpoint` está activo, lo señala para continuar en sesión fresca sin pedir confirmación. **Nunca bloquea**; sin `python3`, sin puente, o con el puente desactualizado, sale `0` en silencio (**fail-open**).
+
+### 13. `reconcile-build-state.py` — `SessionStart` (invocado por `load-build-state.sh`) · no bloqueante (desde v0.8.0)
+
+Es el único hook en Python puro (los demás son bash que delegan fragmentos a `python3`). No se cablea como entrada independiente en `settings.json`/`hooks/build-harness.json`: `load-build-state.sh` lo invoca al arrancar, **antes** de leer el estado, para "anclarlo a la realidad" de git y de los tests. Deriva, nunca lanza: (1) degrada a `failing` cualquier item de `wiring_checklist` marcado `passing` sin `evidence` no vacía (self-heal contra falsos positivos); (2) detecta *drift* entre la rama git real y `active_slice.branch` y lo **anota** en `branch_drift` (no lo corrige); (3) nunca revierte un gate booleano de `true` a `false` (ratchet: solo una señal explícita lo haría). Escribe atómico (`tempfile` + `os.replace`) solo si algo cambió. Fail-open: cualquier error de lectura o parseo devuelve `0` sin tocar el archivo.
+
 ---
 
 ## La cadena de comando única (sin doble disparo entre canales)

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

@@ -4,7 +4,7 @@
 # No bloquea: al cerrar el turno, avisa si hay un slice activo con gates abiertos.
 set -uo pipefail
 
-ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$(pwd)}")"
+ROOT="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
 [ -f "$ROOT/package.json" ] || exit 0
 STATE="$ROOT/.claude/state/build-state.json"
 [ -f "$STATE" ] || exit 0

package/hooks/build/context-monitor.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# context-monitor.sh — PostToolUse|PreCompact|Stop. Lee el puente, aplica umbrales,
+# inyecta additionalContext y (en critical) escribe handoff. Fail-open.
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/lib/state-io.sh"
+payload="$(cat)"; command -v python3 >/dev/null 2>&1 || exit 0
+
+read -r SID EVT <<<"$(printf '%s' "$payload" | python3 -c '
+import json,sys
+try: p=json.load(sys.stdin)
+except Exception: p={}
+print(p.get("session_id","default"), p.get("hook_event_name","PostToolUse"))
+' 2>/dev/null)"
+SID="${SID:-default}"; EVT="${EVT:-PostToolUse}"
+
+sanitized_sid="$(printf '%s' "$SID" | tr -c 'A-Za-z0-9_-' '_')"
+BRIDGE="${TMPDIR:-/tmp}/claude-ctx-$sanitized_sid.json"
+[ -f "$BRIDGE" ] || BRIDGE="$(command ls "${TMPDIR:-/tmp}"/claude-ctx-*.json 2>/dev/null | head -1)"
+[ -n "${BRIDGE:-}" ] && [ -f "$BRIDGE" ] || exit 0
+
+WARN="$(config_get context.warning_pct 35)"; CRIT="$(config_get context.critical_pct 25)"
+STALE="$(config_get context.stale_seconds 60)"; AUTO="$(config_get context.auto_checkpoint false)"
+STATE="$(state_path)"
+
+python3 - "$BRIDGE" "$WARN" "$CRIT" "$STALE" "$EVT" "$STATE" "$AUTO" <<'PY' 2>/dev/null || true
+import json,sys,os,time,tempfile
+bridge,warn,crit,stale,evt,state,auto=sys.argv[1:8]
+warn,crit,stale=int(warn),int(crit),int(stale)
+try: b=json.load(open(bridge))
+except Exception: sys.exit(0)
+if time.time()-b.get("ts",0) > stale: sys.exit(0)   # métrica vieja
+rem=b.get("remaining_pct",100)
+sev = "critical" if rem<=crit else ("warning" if rem<=warn else None)
+if not sev: sys.exit(0)
+
+# ¿slice activo? handoff solo en critical y una vez por sesión.
+recorded=False
+if sev=="critical" and os.path.exists(state):
+    try:
+        d=json.load(open(state)); s=d.get("active_slice")
+        if s:
+            sc=s.setdefault("session_continuity",{})
+            if not sc.get("critical_recorded"):
+                iso=time.strftime("%Y-%m-%dT%H:%M:%SZ",time.gmtime())
+                sc["stopped_at"]=f"context exhaustion at {rem}% ({iso})"
+                failing=[w["id"] for w in (s.get("wiring_checklist") or []) if w.get("status")=="failing"]
+                sc["resume_hint"]=("cablear: "+", ".join(failing[:6])) if failing else "revisar progreso y continuar"
+                sc["critical_recorded"]=True
+                sc["auto_continue"]=(auto=="true")
+                s.setdefault("progress_log",[]).append(
+                    {"at":iso,"by":"context-monitor","note":f"handoff auto a {rem}% de contexto restante"})
+                dirn=os.path.dirname(state) or "."
+                fd,tmp=tempfile.mkstemp(dir=dirn,prefix=".build-state.",suffix=".tmp")
+                try:
+                    with os.fdopen(fd,"w") as o: json.dump(d,o,indent=2,ensure_ascii=False); o.flush(); os.fsync(o.fileno())
+                    os.replace(tmp,state); recorded=True
+                except Exception:
+                    try: os.unlink(tmp)
+                    except OSError: pass
+                    raise
+    except Exception: pass
+
+if sev=="warning":
+    msg=(f"⚠️ Contexto al {rem}% restante. Acércate a un punto natural de corte "
+         "(fin de fase/gate). No inicies trabajo complejo nuevo.")
+else:
+    tail=(" Handoff escrito en build-state.json (session_continuity)." if recorded else "")
+    cont=(" auto_checkpoint=ON: continúa en sesión fresca." if auto=="true" else
+          " Avisa al usuario para reiniciar en un punto natural.")
+    msg=(f"🛑 Contexto CRÍTICO al {rem}% restante.{tail} El estado ya vive en build-state.json;"
+         f" no reescribas handoff manual.{cont}")
+# En 'Stop', inyectar additionalContext RE-LANZA el turno (re-prompt): repetirlo en cada
+# intento de cierre entra en bucle hasta el tope CLAUDE_CODE_STOP_HOOK_BLOCK_CAP (=9→override).
+# Por eso en 'Stop' re-lanzamos como MUCHO una vez por sesión y solo en la TRANSICIÓN a crítico
+# (recorded=True, el instante en que se graba el handoff). 'warning' nunca inyecta en 'Stop'
+# (el nudge solo sirve mientras se trabaja). Fuera de 'Stop' se inyecta con normalidad.
+if evt=="Stop" and not (sev=="critical" and recorded): sys.exit(0)
+print(json.dumps({"hookSpecificOutput":{"hookEventName":evt,"additionalContext":msg}}))
+PY

package/hooks/build/design-source-guard.sh

@@ -8,7 +8,7 @@
 # AUTO-ARME: si no existe build-state.json, exit 0.
 set -uo pipefail
 
-ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$(pwd)}")"
+ROOT="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
 STATE="$ROOT/.claude/state/build-state.json"
 [ -f "$STATE" ] || exit 0
 

package/hooks/build/lib/state-io.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# state-io.sh — helpers compartidos: rutas, lectura de config y patch atómico del estado.
+# Diseño: fail-open. Nunca lanza; ante fallo deja el archivo intacto.
+
+state_path() {
+  # CLAUDE_PROJECT_DIR es la señal autoritativa que Claude Code fija en los hooks;
+  # git rev-parse solo aplica como fallback para invocación manual/dev (sin ese env).
+  local root; root="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+  echo "$root/.claude/state/build-state.json"
+}
+
+# config_get <clave.punteada> <default>
+config_get() {
+  local key="$1" def="$2" file
+  file="${BUILD_CONFIG_FILE:-$(dirname "$(state_path)")/../config/build-config.json}"
+  command -v python3 >/dev/null 2>&1 || { echo "$def"; return; }
+  python3 - "$file" "$key" "$def" <<'PY' 2>/dev/null || echo "$def"
+import json,sys
+file,key,default=sys.argv[1],sys.argv[2],sys.argv[3]
+try:
+    d=json.load(open(file))
+    for part in key.split("."): d=d[part]
+    print(d if not isinstance(d,bool) else str(d).lower())
+except Exception:
+    print(default)
+PY
+}
+
+# state_atomic_patch <state-file> <expr-python-que-muta-`d`>
+# Ejecuta la expresión con `d` = dict del estado; escribe atómico solo si válido.
+state_atomic_patch() {
+  local file="$1" expr="$2"
+  [ -f "$file" ] || return 0
+  command -v python3 >/dev/null 2>&1 || return 0
+  python3 - "$file" "$expr" <<'PY' 2>/dev/null || true
+import json,sys,os,tempfile
+path,expr=sys.argv[1],sys.argv[2]
+try:
+    d=json.load(open(path))
+    if not isinstance(d,dict): sys.exit(0)
+    exec(expr, {}, {"d":d})
+    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)
+    except Exception:
+        try: os.unlink(tmp)
+        except OSError: pass
+        raise
+except Exception:
+    pass
+PY
+}

package/hooks/build/lint-typecheck.sh

@@ -8,7 +8,7 @@
 # coste por edición no escale con el tamaño del repo.
 set -uo pipefail
 
-ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$(pwd)}")"
+ROOT="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
 [ -f "$ROOT/package.json" ] || exit 0   # guard de auto-arme
 
 # Guarda python3 [H4]: hook no-bloqueante; sin python3 no podemos extraer el archivo → omite.

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

@@ -3,14 +3,53 @@
 # Inyecta al contexto: rama actual, harness_phase, slice activo y gates abiertos.
 # Además sincroniza harness_phase (authoring -> active) según exista package.json.
 set -uo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/state-io.sh"
 
-ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$(pwd)}")"
-STATE="$ROOT/.claude/state/build-state.json"
+# Lee el payload de SessionStart (JSON en stdin) para extraer session_id. Fail-open:
+# si no hay stdin o no trae session_id, seguimos sin tocar session_continuity.
+payload="$(cat 2>/dev/null || true)"
+
+ROOT="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+STATE="$(state_path)"
 BRANCH="$(git -C "$ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'desconocida')"
 
 # Determina la fase real del arnés.
 if [ -f "$ROOT/package.json" ]; then PHASE="active"; else PHASE="authoring"; fi
 
+# Ancla el estado a disco antes de leerlo (fail-open; nunca rompe SessionStart).
+if [ -f "$STATE" ] && command -v python3 >/dev/null 2>&1; then
+  python3 "$(dirname "${BASH_SOURCE[0]}")/reconcile-build-state.py" "$STATE" 2>/dev/null || true
+fi
+
+# Reset once-per-SESSION del guard de auto-handoff (A1): si esta sesión (session_id del
+# payload de SessionStart) es distinta de la última registrada en session_continuity,
+# reabrimos critical_recorded para que context-monitor.sh pueda volver a escribir handoff
+# fresco en ESTA sesión. Fail-open: sin stdin/session_id/state, no se toca nada.
+if [ -f "$STATE" ] && command -v python3 >/dev/null 2>&1; then
+  SESSION_ID="$(printf '%s' "$payload" | python3 -c '
+import json,sys
+try:
+    p=json.load(sys.stdin)
+    sid=p.get("session_id","")
+    print(sid if isinstance(sid,str) else "")
+except Exception:
+    print("")
+' 2>/dev/null || true)"
+  if [ -n "$SESSION_ID" ]; then
+    SID_JSON="$(python3 -c 'import json,sys; print(json.dumps(sys.argv[1]))' "$SESSION_ID" 2>/dev/null || true)"
+    if [ -n "$SID_JSON" ]; then
+      state_atomic_patch "$STATE" "
+s = d.get('active_slice')
+if isinstance(s, dict):
+    sc = s.setdefault('session_continuity', {})
+    if sc.get('last_session') != $SID_JSON:
+        sc['last_session'] = $SID_JSON
+        sc['critical_recorded'] = False
+"
+    fi
+  fi
+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
@@ -79,6 +118,11 @@ else:
     if log:
         last=log[-1]
         print(f"   Última bitácora: [{last.get('by')}] {last.get('note')}")
+    sc=s.get("session_continuity") or {}
+    if sc.get("resume_hint"):
+        print(f"   ▶️  Retomar: {sc.get('resume_hint')}" + ("  [auto-continue]" if sc.get("auto_continue") else ""))
+    if s.get("branch_drift"):
+        print(f"   ⚠️  Rama real ({s.get('branch_drift')}) != branch del slice ({s.get('branch')}).")
 PY
 fi
 exit 0

package/hooks/build/reconcile-build-state.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""reconcile-build-state.py — ancla el estado a la realidad (git + tests). Fail-open.
+
+Deriva/reconcilia, nunca lanza:
+- wiring_checklist: un item 'passing' sin 'evidence' se degrada a 'failing' (self-heal).
+- branch_drift: si la rama git real != active_slice.branch, lo anota (no corrige).
+- ratchet: no revierte gates booleanos true->false (solo señal explícita lo haría).
+Uso: reconcile-build-state.py [<state-file>]
+"""
+import json, os, sys, subprocess, tempfile
+
+def git_branch(root):
+    try:
+        return subprocess.run(["git","-C",root,"rev-parse","--abbrev-ref","HEAD"],
+                              capture_output=True,text=True,timeout=5).stdout.strip() or None
+    except Exception:
+        return None
+
+def main():
+    path = sys.argv[1] if len(sys.argv) > 1 else os.path.join(
+        os.environ.get("CLAUDE_PROJECT_DIR",os.getcwd()), ".claude","state","build-state.json")
+    try:
+        with open(path) as fh:
+            d = json.load(fh)
+    except Exception:
+        return 0  # fail-open
+    if not isinstance(d, dict):
+        return 0
+    changed = False
+    s = d.get("active_slice")
+    if isinstance(s, dict):
+        try:
+            # 1) wiring: passing sin evidencia -> failing
+            wc = s.get("wiring_checklist")
+            wc = wc if isinstance(wc, list) else []
+            for w in wc:
+                if not isinstance(w, dict):
+                    continue
+                if w.get("status") == "passing" and not (w.get("evidence") or "").strip():
+                    w["status"] = "failing"; changed = True
+            # 2) branch drift
+            root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(path))))
+            rb = git_branch(root)
+            if rb and s.get("branch") and rb != s["branch"] and rb not in ("HEAD",):
+                if s.get("branch_drift") != rb:
+                    s["branch_drift"] = rb; changed = True
+            elif s.get("branch_drift") and rb == s.get("branch"):
+                s.pop("branch_drift", None); changed = True
+        except Exception:
+            pass
+    if changed:
+        try:
+            dirn = os.path.dirname(path) or "."
+            fd, tmp = tempfile.mkstemp(dir=dirn, prefix=".build-state.", suffix=".tmp")
+        except Exception:
+            return 0
+        try:
+            with os.fdopen(fd,"w") as o:
+                json.dump(d,o,indent=2,ensure_ascii=False); o.flush(); os.fsync(o.fileno())
+            os.replace(tmp, path)
+            sys.stderr.write("reconcile: estado re-anclado a disco\n")
+        except Exception:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/build/reflect-nudge.sh

@@ -5,7 +5,7 @@
 # Determinista y barato: el razonamiento (qué se aprendió) lo hace el MODELO en /build:reflect.
 set -uo pipefail
 
-ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$(pwd)}")"
+ROOT="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
 STATE="$ROOT/.claude/state/build-state.json"
 [ -f "$STATE" ] || exit 0
 command -v python3 >/dev/null 2>&1 || exit 0   # fail-open: jamás impide cerrar sesión

package/hooks/build/release-gate-nudge.sh

@@ -8,7 +8,7 @@
 # (lo computa la skill building-a-slice en la fase 8).
 set -uo pipefail
 
-ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$(pwd)}")"
+ROOT="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
 STATE="$ROOT/.claude/state/build-state.json"
 [ -f "$STATE" ] || exit 0
 command -v python3 >/dev/null 2>&1 || exit 0   # fail-open: jamás impide cerrar sesión

package/hooks/build/scaffold-guard.sh

@@ -7,7 +7,7 @@
 # AUTO-ARME: si no existe build-state.json, no hay nada que vigilar -> exit 0.
 set -uo pipefail
 
-ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$(pwd)}")"
+ROOT="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
 STATE="$ROOT/.claude/state/build-state.json"
 [ -f "$STATE" ] || exit 0
 

package/hooks/build/stack-guard.sh

@@ -5,7 +5,7 @@
 # dependencias fuera de .claude/config/stack-allowlist.json (el contrato de stack del PRD).
 set -uo pipefail
 
-ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$(pwd)}")"
+ROOT="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
 ALLOW="$ROOT/.claude/config/stack-allowlist.json"
 [ -f "$ALLOW" ] || exit 0
 

package/hooks/build/statusline-bridge.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# statusline-bridge.sh — statusLine command (canal CLI). Imprime la línea de estado
+# y escribe el puente de contexto que lee context-monitor.sh. Fail-open siempre.
+set -uo pipefail
+payload="$(cat)"
+command -v python3 >/dev/null 2>&1 || { echo "🏗️ build"; exit 0; }
+echo "$payload" | python3 -c '
+import json,sys,os,time,re,tempfile
+try:
+    p=json.load(sys.stdin)
+except Exception:
+    print("🏗️ build"); sys.exit(0)
+sid=str(p.get("session_id","default"))
+if re.search(r"[\\/]|\.\.", sid): sid=re.sub(r"[^A-Za-z0-9_-]","_",sid)  # sanitiza path traversal
+rem=None
+try: rem=int(p.get("context_window",{}).get("remaining_percentage"))
+except Exception: rem=None
+if rem is not None:
+    d={"remaining_pct":rem,"used_pct":100-rem,"ts":int(time.time())}
+    path=os.path.join(tempfile.gettempdir(), f"claude-ctx-{sid}.json")
+    try:
+        fd,tmp=tempfile.mkstemp(dir=tempfile.gettempdir(),prefix=".ctx-",suffix=".tmp")
+        try:
+            with os.fdopen(fd,"w") as f: json.dump(d,f)
+            os.replace(tmp,path)
+        except Exception:
+            try: os.unlink(tmp)
+            except OSError: pass
+    except Exception: pass
+tag = f"🏗️ build · ctx {rem}%" if rem is not None else "🏗️ build"
+print(tag)
+' 2>/dev/null || echo "🏗️ build"