@trycore/spec-build-harness 0.7.0 → 0.8.0

package/docs/hooks.md

@@ -1,26 +1,32 @@
 # 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 **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 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 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 9 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 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 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.
 
 ---
 
@@ -89,6 +95,22 @@ 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**).
+
+### 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)
@@ -113,7 +135,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 +156,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 +170,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 +183,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

@@ -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,74 @@
+#!/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}")
+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"

package/hooks/build-harness.json

@@ -52,6 +52,26 @@
             "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/coherence-flag.sh\""
           }
         ]
+      },
+      {
+        "matcher": "Bash|Edit|Write|MultiEdit|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/context-monitor.sh\""
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/context-monitor.sh\""
+          }
+        ]
       }
     ],
     "Stop": [
@@ -69,6 +89,10 @@
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/release-gate-nudge.sh\""
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/context-monitor.sh\""
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trycore/spec-build-harness",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "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": {

package/scripts/lib/front-plan.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""front-plan.py — selecciona el conjunto disjunto máximo de épicas no fundacionales.
+
+stdin: JSON [{"epica","layer","files_scope":[glob]}]
+stdout: {"selected":[...],"serialized":[{"epica","reason"}],"excluded_foundational":[...]}
+Determinista: orden por 'epica'. Solape de globs por prefijo de directorio o glob idéntico.
+"""
+import json, sys, fnmatch
+
+def overlap(a, b):
+    for ga in a:
+        for gb in b:
+            if ga == gb or fnmatch.fnmatch(ga, gb) or fnmatch.fnmatch(gb, ga):
+                return True
+            pa, pb = ga.split("*", 1)[0], gb.split("*", 1)[0]
+            # Fail closed: a leading/empty-prefix wildcard could match anything → assume overlap.
+            if not pa or not pb:
+                return True
+            if pa.startswith(pb) or pb.startswith(pa):
+                return True
+    return False
+
+def _empty_result():
+    return {"selected": [], "serialized": [], "excluded_foundational": []}
+
+def main():
+    try:
+        cands = json.load(sys.stdin)
+        if not isinstance(cands, list) or not all(isinstance(c, dict) for c in cands):
+            raise ValueError("entrada inválida: se esperaba una lista de objetos")
+        cands = sorted(cands, key=lambda c: c.get("epica",""))
+        excluded = [c["epica"] for c in cands if c.get("layer") == "foundational"]
+        pool = [c for c in cands if c.get("layer") != "foundational"]
+        selected, sel_scopes, serialized = [], [], []
+        for c in pool:
+            sc = c.get("files_scope") or []
+            if any(overlap(sc, s) for s in sel_scopes):
+                serialized.append({"epica": c["epica"], "reason": "solape de files_scope con épica seleccionada"})
+            else:
+                selected.append(c["epica"]); sel_scopes.append(sc)
+        print(json.dumps({"selected":selected,"serialized":serialized,"excluded_foundational":excluded}))
+    except Exception:
+        print(json.dumps(_empty_result()))
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/smoke-test.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# smoke-test.sh — corre los tests de humo del motor de contexto y front.
+set -uo pipefail
+DIR="$(cd "$(dirname "$0")" && pwd)"
+FAILED=0
+
+echo "── Tests del motor de contexto y front ──"
+for t in test-schema.sh test-reconciler.sh test-context-monitor.sh test-front-plan.sh test-install.sh; do
+  if bash "$DIR/tests/$t"; then echo "smoke: $t OK"; else echo "smoke: $t FALLÓ"; FAILED=1; fi
+done
+
+exit $FAILED