@trycore/spec-build-harness 0.7.1 → 0.8.1

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.1",
+  "version": "0.8.1",
   "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

package/scripts/tests/test-context-monitor.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+set -uo pipefail
+ROOT="$(git rev-parse --show-toplevel)"
+fail=0
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+export TMPDIR="$TMP"
+
+# bridge: escribe puente sanitizando session_id
+echo '{"session_id":"ab/../cd","context_window":{"remaining_percentage":22}}' \
+  | bash "$ROOT/hooks/build/statusline-bridge.sh" >/dev/null
+if ls "$TMP"/claude-ctx-*.json >/dev/null 2>&1; then
+  b="$(ls "$TMP"/claude-ctx-*.json)"
+  case "$b" in *..*|*/claude-ctx-ab/*) echo "FAIL bridge no sanitiza"; fail=1;; *) echo "OK bridge sanitiza";; esac
+  rp="$(python3 -c "import json;print(json.load(open('$b'))['remaining_pct'])")"
+  [ "$rp" = 22 ] && echo "OK bridge remaining_pct" || { echo "FAIL bridge remaining_pct ($rp)"; fail=1; }
+else echo "FAIL bridge no escribió puente"; fail=1; fi
+
+# monitor: a 20% (critical<25) inyecta additionalContext y escribe handoff
+sid="sess1"; echo "{\"remaining_pct\":20,\"used_pct\":80,\"ts\":$(date +%s)}" > "$TMP/claude-ctx-$sid.json"
+mkdir -p "$TMP/proj/.claude/state" "$TMP/proj/.claude/config"
+cat > "$TMP/proj/.claude/state/build-state.json" <<'JSON'
+{"version":"1.0","harness_phase":"active","scaffold":{"confirmed":true},
+ "active_slice":{"epica":"EP-001","hus":["HU-001"],"openspec_change":"x","branch":"feature/x","phase":"tdd",
+   "gates":{"dor":true,"tdd":false,"dod":false},"updated_at":"2026-07-03T00:00:00Z","updated_by":"t","progress_log":[]},
+ "history":[],"releases":[]}
+JSON
+echo '{"context":{"critical_pct":25,"warning_pct":35,"auto_checkpoint":false}}' > "$TMP/proj/.claude/config/build-config.json"
+out="$(echo "{\"session_id\":\"$sid\",\"hook_event_name\":\"PostToolUse\"}" \
+  | CLAUDE_PROJECT_DIR="$TMP/proj" bash "$ROOT/hooks/build/context-monitor.sh")"
+echo "$out" | grep -q 'additionalContext' && echo "OK monitor inyecta aviso" || { echo "FAIL monitor sin aviso"; fail=1; }
+sc="$(python3 -c "import json;print(json.load(open('$TMP/proj/.claude/state/build-state.json'))['active_slice'].get('session_continuity',{}).get('critical_recorded'))" 2>/dev/null)"
+[ "$sc" = True ] && echo "OK monitor handoff" || { echo "FAIL monitor handoff ($sc)"; fail=1; }
+
+# ── Stop: no debe re-lanzar el turno en bucle (regresión CLAUDE_CODE_STOP_HOOK_BLOCK_CAP) ──
+# En 'Stop' inyectar additionalContext = re-prompt (bloquea el cierre). El warning es solo un
+# nudge mientras se trabaja → en 'Stop' NO debe inyectar (si no, bucle hasta el tope de 9).
+sidW="sessW"; echo "{\"remaining_pct\":30,\"used_pct\":70,\"ts\":$(date +%s)}" > "$TMP/claude-ctx-$sidW.json"
+PW="$TMP/proj-warn-stop"; mkdir -p "$PW/.claude/state" "$PW/.claude/config"
+cp "$TMP/proj/.claude/state/build-state.json" "$PW/.claude/state/build-state.json"
+echo '{"context":{"critical_pct":25,"warning_pct":35,"auto_checkpoint":false}}' > "$PW/.claude/config/build-config.json"
+outW="$(echo "{\"session_id\":\"$sidW\",\"hook_event_name\":\"Stop\"}" \
+  | CLAUDE_PROJECT_DIR="$PW" bash "$ROOT/hooks/build/context-monitor.sh")"
+echo "$outW" | grep -q 'additionalContext' \
+  && { echo "FAIL warning+Stop inyecta (re-prompt → bucle)"; fail=1; } \
+  || echo "OK warning+Stop no inyecta"
+# warning en PostToolUse (trabajando) SÍ debe seguir avisando (regresión: no romper el nudge útil).
+outWP="$(echo "{\"session_id\":\"$sidW\",\"hook_event_name\":\"PostToolUse\"}" \
+  | CLAUDE_PROJECT_DIR="$PW" bash "$ROOT/hooks/build/context-monitor.sh")"
+echo "$outWP" | grep -q 'additionalContext' \
+  && echo "OK warning+PostToolUse sigue avisando" \
+  || { echo "FAIL warning+PostToolUse dejó de avisar"; fail=1; }
+
+# critical en 'Stop': inyecta como MUCHO una vez (la transición que graba el handoff), luego calla.
+sidC="sessC"; echo "{\"remaining_pct\":20,\"used_pct\":80,\"ts\":$(date +%s)}" > "$TMP/claude-ctx-$sidC.json"
+PC="$TMP/proj-crit-stop"; mkdir -p "$PC/.claude/state" "$PC/.claude/config"
+cp "$TMP/proj/.claude/state/build-state.json" "$PC/.claude/state/build-state.json"
+python3 -c "import json;p='$PC/.claude/state/build-state.json';d=json.load(open(p));d['active_slice'].pop('session_continuity',None);json.dump(d,open(p,'w'))"
+echo '{"context":{"critical_pct":25,"warning_pct":35,"auto_checkpoint":false}}' > "$PC/.claude/config/build-config.json"
+outC1="$(echo "{\"session_id\":\"$sidC\",\"hook_event_name\":\"Stop\"}" \
+  | CLAUDE_PROJECT_DIR="$PC" bash "$ROOT/hooks/build/context-monitor.sh")"
+echo "$outC1" | grep -q 'additionalContext' \
+  && echo "OK critical+Stop inyecta la transición (1ª vez)" \
+  || { echo "FAIL critical+Stop no inyecta la transición"; fail=1; }
+outC2="$(echo "{\"session_id\":\"$sidC\",\"hook_event_name\":\"Stop\"}" \
+  | CLAUDE_PROJECT_DIR="$PC" bash "$ROOT/hooks/build/context-monitor.sh")"
+echo "$outC2" | grep -q 'additionalContext' \
+  && { echo "FAIL critical+Stop re-inyecta (bucle)"; fail=1; } \
+  || echo "OK critical+Stop NO re-inyecta (bucle roto)"
+
+# load-build-state (SessionStart): reset once-per-SESSION del guard critical_recorded.
+# Sesión NUEVA (last_session distinto del session_id del payload) -> reabre el guard y
+# persiste el session_id actual.
+PROJ="$TMP/proj-lbs"; mkdir -p "$PROJ/.claude/state"
+cat > "$PROJ/.claude/state/build-state.json" <<'JSON'
+{"version":"1.0","harness_phase":"active","scaffold":{"confirmed":true},
+ "active_slice":{"epica":"EP-001","hus":["HU-001"],"openspec_change":"x","branch":"feature/x","phase":"tdd",
+   "gates":{"dor":true,"tdd":false,"dod":false},"updated_at":"2026-07-03T00:00:00Z","updated_by":"t",
+   "progress_log":[],"session_continuity":{"critical_recorded":true,"last_session":"old"}},
+ "history":[],"releases":[]}
+JSON
+echo '{"session_id":"new"}' | CLAUDE_PROJECT_DIR="$PROJ" bash "$ROOT/hooks/build/load-build-state.sh" >/dev/null
+cr="$(python3 -c "import json;print(json.load(open('$PROJ/.claude/state/build-state.json'))['active_slice']['session_continuity']['critical_recorded'])")"
+ls_="$(python3 -c "import json;print(json.load(open('$PROJ/.claude/state/build-state.json'))['active_slice']['session_continuity']['last_session'])")"
+[ "$cr" = False ] && echo "OK load-build-state resetea critical_recorded en sesión nueva" || { echo "FAIL critical_recorded no se reseteó ($cr)"; fail=1; }
+[ "$ls_" = new ] && echo "OK load-build-state persiste last_session nuevo" || { echo "FAIL last_session no persistió ($ls_)"; fail=1; }
+
+# Sesión IDÉNTICA (last_session == session_id del payload) -> NO toca critical_recorded.
+PROJ2="$TMP/proj-lbs-same"; mkdir -p "$PROJ2/.claude/state"
+cat > "$PROJ2/.claude/state/build-state.json" <<'JSON'
+{"version":"1.0","harness_phase":"active","scaffold":{"confirmed":true},
+ "active_slice":{"epica":"EP-001","hus":["HU-001"],"openspec_change":"x","branch":"feature/x","phase":"tdd",
+   "gates":{"dor":true,"tdd":false,"dod":false},"updated_at":"2026-07-03T00:00:00Z","updated_by":"t",
+   "progress_log":[],"session_continuity":{"critical_recorded":true,"last_session":"s1"}},
+ "history":[],"releases":[]}
+JSON
+echo '{"session_id":"s1"}' | CLAUDE_PROJECT_DIR="$PROJ2" bash "$ROOT/hooks/build/load-build-state.sh" >/dev/null
+cr2="$(python3 -c "import json;print(json.load(open('$PROJ2/.claude/state/build-state.json'))['active_slice']['session_continuity']['critical_recorded'])")"
+[ "$cr2" = True ] && echo "OK load-build-state NO toca critical_recorded en misma sesión" || { echo "FAIL critical_recorded se tocó en misma sesión ($cr2)"; fail=1; }
+
+# wiring: ambos canales cablean context-monitor en PostToolUse/PreCompact/Stop
+grep -q 'PreCompact' "$ROOT/hooks/build-harness.json" && echo "OK plugin PreCompact" || { echo "FAIL plugin PreCompact"; fail=1; }
+grep -q 'context-monitor.sh' "$ROOT/hooks/build-harness.json" && echo "OK plugin monitor" || { echo "FAIL plugin monitor"; fail=1; }
+grep -q "PreCompact" "$ROOT/src/lib/settings-merge.ts" && echo "OK cli PreCompact" || { echo "FAIL cli PreCompact"; fail=1; }
+grep -q "context-monitor.sh" "$ROOT/src/lib/settings-merge.ts" && echo "OK cli monitor" || { echo "FAIL cli monitor"; fail=1; }
+
+exit $fail

package/scripts/tests/test-front-plan.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -uo pipefail
+ROOT="$(git rev-parse --show-toplevel)"; fail=0
+run() { echo "$1" | python3 "$ROOT/scripts/lib/front-plan.py"; }
+
+out="$(run '[{"epica":"EP-001","layer":"foundational","files_scope":["src/**"]},
+             {"epica":"EP-002","layer":"business","files_scope":["src/a/**"]},
+             {"epica":"EP-003","layer":"business","files_scope":["src/b/**"]},
+             {"epica":"EP-004","layer":"business","files_scope":["src/a/x.ts"]}]')"
+echo "$out" | python3 -c "import json,sys;d=json.load(sys.stdin);
+assert d['excluded_foundational']==['EP-001'], d
+assert set(d['selected'])=={'EP-002','EP-003'}, d
+assert [m['epica'] for m in d['serialized']]==['EP-004'], d
+print('OK front-plan disjunción')" || { echo "FAIL front-plan disjunción"; fail=1; }
+
+for bad in 'null' '[1,2,3]' '"abc"' '{"a":1}'; do
+  if out="$(echo "$bad" | python3 "$ROOT/scripts/lib/front-plan.py" 2>/dev/null)" \
+     && echo "$out" | python3 -c "import json,sys;assert json.load(sys.stdin)['selected']==[]" 2>/dev/null; then
+    echo "OK front-plan fail-open ($bad)"; else echo "FAIL front-plan fail-open ($bad)"; fail=1; fi
+done
+
+out="$(echo '[{"epica":"EP-010","layer":"business","files_scope":["*a*.ts"]},
+              {"epica":"EP-011","layer":"business","files_scope":["*b*.ts"]}]' | python3 "$ROOT/scripts/lib/front-plan.py")"
+echo "$out" | python3 -c "import json,sys;d=json.load(sys.stdin);
+assert d['selected']==['EP-010'] and [m['epica'] for m in d['serialized']]==['EP-011'], d
+print('OK front-plan mid-wildcard overlap serializado')" || { echo "FAIL mid-wildcard overlap"; fail=1; }
+
+SK="$ROOT/skills/managing-parallel-front/SKILL.md"
+{ [ -f "$SK" ] && grep -q 'git worktree add' "$SK" && grep -q 'front-plan.py' "$SK" \
+  && grep -q 'merge_order' "$SK" && grep -q 'foundational' "$SK"; } \
+  && echo "OK skill front" || { echo "FAIL skill front"; fail=1; }
+
+{ [ -f "$ROOT/commands/build/front.md" ] && grep -q 'managing-parallel-front' "$ROOT/commands/build/front.md"; } \
+  && echo "OK comando front" || { echo "FAIL comando front"; fail=1; }
+grep -q 'files_scope' "$ROOT/skills/building-a-slice/references/dor.md" && echo "OK dor files_scope" || { echo "FAIL dor files_scope"; fail=1; }
+grep -q 'parallel_front' "$ROOT/agents/build/build-orchestrator.md" && echo "OK orquestador front" || { echo "FAIL orquestador front"; fail=1; }
+
+exit $fail

package/scripts/tests/test-install.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# test-install.sh — smoke test del CANAL CLI de instalación (init/update).
+# Reproduce el bug real: el instalador solo copiaba *.sh de hooks/build/ (sin
+# recursar en lib/) y nunca creaba .claude/scripts/, dejando muertos en un
+# install real los 3 archivos v0.8 (reconcile-build-state.py, state-io.sh,
+# front-plan.py) aunque el smoke suite "en el repo" no lo detectara (los
+# archivos ya existen ahí, fuera del flujo de instalación).
+set -uo pipefail
+ROOT="$(git rev-parse --show-toplevel)"
+fail=0
+
+# 1) Build fresco del CLI compilado (dist/cli.js) — el test corre contra el artefacto publicado.
+if [ ! -f "$ROOT/dist/cli.js" ]; then
+  echo "ℹ dist/cli.js no existe — corriendo npm run build"
+  (cd "$ROOT" && npm run build) >/dev/null 2>&1
+fi
+if [ ! -f "$ROOT/dist/cli.js" ]; then
+  echo "FAIL install: npm run build no produjo dist/cli.js"
+  exit 1
+fi
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+# 2) `init` no interactivo, modo copy (para no depender de symlinks al paquete),
+#    sin exigir openspec/python3/git en el runner (--skip-doctor).
+node "$ROOT/dist/cli.js" init "$TMP" \
+  --copy \
+  --skip-doctor \
+  --yes \
+  --stack "" \
+  --pkg-manager npm \
+  --runtime ">=18.18" \
+  --prd-path "docs/01-prd/x.md#req" \
+  >"$TMP/.init.log" 2>&1
+rc=$?
+if [ $rc -ne 0 ]; then
+  echo "FAIL install: \`trycore-build init\` salió con código $rc"
+  cat "$TMP/.init.log"
+  fail=1
+fi
+
+check() { # <ruta relativa a .claude> <descripción>
+  local rel="$1"
+  local p="$TMP/.claude/$rel"
+  if [ -f "$p" ]; then
+    echo "OK install: .claude/$rel"
+  else
+    echo "FAIL install: .claude/$rel NO existe"
+    fail=1
+  fi
+}
+
+check "hooks/build/reconcile-build-state.py"
+check "hooks/build/lib/state-io.sh"
+check "hooks/build/context-monitor.sh"
+check "hooks/build/statusline-bridge.sh"
+check "scripts/lib/front-plan.py"
+
+# 3) Bit ejecutable en los .py/.sh copiados (modo copy no preserva +x por defecto — el
+#    instalador debe forzarlo con chmodExec tras copiar).
+checkexec() {
+  local rel="$1"
+  local p="$TMP/.claude/$rel"
+  if [ -f "$p" ] && [ -x "$p" ]; then
+    echo "OK install: .claude/$rel es ejecutable"
+  else
+    echo "FAIL install: .claude/$rel NO es ejecutable"
+    fail=1
+  fi
+}
+checkexec "hooks/build/reconcile-build-state.py"
+checkexec "hooks/build/lib/state-io.sh"
+checkexec "scripts/lib/front-plan.py"
+
+# 4) `update` (canal de refresco tras `npm i` del paquete) también debe dejarlos — re-correr
+#    sobre la misma instalación no debe romper nada ni perder archivos.
+node "$ROOT/dist/cli.js" update "$TMP" --copy --skip-doctor >"$TMP/.update.log" 2>&1
+rc=$?
+if [ $rc -ne 0 ]; then
+  echo "FAIL install: \`trycore-build update\` salió con código $rc"
+  cat "$TMP/.update.log"
+  fail=1
+fi
+check "hooks/build/reconcile-build-state.py"
+check "hooks/build/lib/state-io.sh"
+check "scripts/lib/front-plan.py"
+
+exit $fail

package/scripts/tests/test-reconciler.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+set -uo pipefail
+ROOT="$(git rev-parse --show-toplevel)"
+source "$ROOT/hooks/build/lib/state-io.sh" 2>/dev/null || { echo "FAIL no existe state-io.sh"; exit 1; }
+fail=0
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+
+# config_get lee clave punteada con default
+echo '{"context":{"warning_pct":40}}' > "$TMP/cfg.json"
+got="$(BUILD_CONFIG_FILE="$TMP/cfg.json" config_get context.warning_pct 35)"
+[ "$got" = 40 ] && echo "OK config_get valor" || { echo "FAIL config_get valor ($got)"; fail=1; }
+got="$(BUILD_CONFIG_FILE="$TMP/cfg.json" config_get context.critical_pct 25)"
+[ "$got" = 25 ] && echo "OK config_get default" || { echo "FAIL config_get default ($got)"; fail=1; }
+
+# state_atomic_patch muta y deja JSON válido
+echo '{"version":"1.0","n":1}' > "$TMP/s.json"
+state_atomic_patch "$TMP/s.json" 'd["n"]=2'
+got="$(python3 -c "import json;print(json.load(open('$TMP/s.json'))['n'])")"
+[ "$got" = 2 ] && echo "OK atomic_patch" || { echo "FAIL atomic_patch ($got)"; fail=1; }
+
+# reconcile-build-state: degrada passing sin evidencia, conserva con evidencia, fail-open
+cat > "$TMP/state.json" <<'JSON'
+{"version":"1.0","harness_phase":"active","scaffold":{"confirmed":true},
+ "active_slice":{"epica":"EP-001","hus":["HU-001"],"openspec_change":"x","branch":"feature/x","phase":"tdd",
+   "gates":{"dor":true,"tdd":true,"dod":false},"updated_at":"2026-07-03T00:00:00Z","updated_by":"t",
+   "wiring_checklist":[{"id":"HU-001-AC1","kind":"hu_ac","ref":"HU-001#1","status":"passing","evidence":""},
+                       {"id":"HU-001-AC2","kind":"hu_ac","ref":"HU-001#2","status":"passing","evidence":"pytest ok"}]},
+ "history":[],"releases":[]}
+JSON
+python3 "$ROOT/hooks/build/reconcile-build-state.py" "$TMP/state.json" 2>/dev/null
+st1="$(python3 -c "import json;d=json.load(open('$TMP/state.json'));print(d['active_slice']['wiring_checklist'][0]['status'])")"
+st2="$(python3 -c "import json;d=json.load(open('$TMP/state.json'));print(d['active_slice']['wiring_checklist'][1]['status'])")"
+[ "$st1" = failing ] && echo "OK reconcile degrada sin evidencia" || { echo "FAIL degrada ($st1)"; fail=1; }
+[ "$st2" = passing ] && echo "OK reconcile conserva con evidencia" || { echo "FAIL conserva ($st2)"; fail=1; }
+# fail-open: archivo corrupto no rompe
+echo 'no json' > "$TMP/bad.json"
+python3 "$ROOT/hooks/build/reconcile-build-state.py" "$TMP/bad.json" 2>/dev/null; echo "OK reconcile fail-open (rc=$?)"
+
+# fail-open: wiring_checklist malformado (item no-dict) no debe crashear ni corromper el archivo
+cat > "$TMP/mal.json" <<'JSON'
+{"version":"1.0","harness_phase":"active","scaffold":{"confirmed":true},
+ "active_slice":{"epica":"EP-001","hus":["HU-001"],"openspec_change":"x","branch":"feature/x","phase":"tdd",
+   "gates":{"dor":true,"tdd":false,"dod":false},"updated_at":"2026-07-03T00:00:00Z","updated_by":"t",
+   "wiring_checklist":["not-a-dict"]},
+ "history":[],"releases":[]}
+JSON
+if python3 "$ROOT/hooks/build/reconcile-build-state.py" "$TMP/mal.json" 2>/dev/null; then
+  python3 -c "import json;json.load(open('$TMP/mal.json'))" 2>/dev/null && echo "OK reconcile fail-open wiring malformado" || { echo "FAIL mal json corrupto"; fail=1; }
+else echo "FAIL reconcile crashed on malformed wiring"; fail=1; fi
+
+# SessionStart integra reconciliador
+grep -q 'reconcile-build-state.py' "$ROOT/hooks/build/load-build-state.sh" && echo "OK sessionstart reconcilia" || { echo "FAIL sessionstart no reconcilia"; fail=1; }
+grep -q 'resume_hint' "$ROOT/hooks/build/load-build-state.sh" && echo "OK sessionstart imprime hint" || { echo "FAIL sessionstart sin hint"; fail=1; }
+exit $fail

package/scripts/tests/test-schema.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# test-schema.sh — valida build-state.schema.json contra ejemplos válidos/ inválidos.
+set -uo pipefail
+ROOT="$(git rev-parse --show-toplevel)"
+SCHEMA="$ROOT/state/build-state.schema.json"
+fail=0
+
+check() { # <descripción> <esperado: pass|fail> <json-file>
+  python3 - "$SCHEMA" "$3" <<'PY'
+import json,sys
+try:
+    import jsonschema
+except ImportError:
+    print("SKIP: jsonschema no instalado"); sys.exit(2)
+schema=json.load(open(sys.argv[1])); data=json.load(open(sys.argv[2]))
+from jsonschema import Draft202012Validator
+errs=sorted(Draft202012Validator(schema).iter_errors(data), key=str)
+sys.exit(1 if errs else 0)
+PY
+  local rc=$?
+  if [ "$rc" = 2 ]; then echo "SKIP $1"; return; fi
+  if { [ "$2" = pass ] && [ "$rc" = 0 ]; } || { [ "$2" = fail ] && [ "$rc" = 1 ]; }; then
+    echo "OK   $1"
+  else echo "FAIL $1 (rc=$rc)"; fail=1; fi
+}
+
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+cat > "$TMP/valid.json" <<'JSON'
+{"version":"1.0","harness_phase":"active","scaffold":{"confirmed":true},
+ "active_slice":{"epica":"EP-001","hus":["HU-001"],"openspec_change":"add-login",
+   "branch":"feature/login","phase":"change","layer":"business","files_scope":["src/auth/**"],
+   "gates":{"dor":true,"tdd":false,"dod":false},"updated_at":"2026-07-03T00:00:00Z","updated_by":"test",
+   "session_continuity":{"last_session":"s1","stopped_at":null,"resume_hint":"cablear AC2","critical_recorded":false,"auto_continue":false}},
+ "history":[],"releases":[],
+ "parallel_front":{"status":"active","opened_at":"2026-07-03T00:00:00Z","updated_by":"test",
+   "members":[{"epica":"EP-002","worktree":{"path":".wt/ep-002","branch":"feature/ep-002","created_at":"2026-07-03T00:00:00Z"},
+     "files_scope":["src/reports/**"],"journey_smoke":false,"merge_status":"pending"}],
+   "merge_order":["EP-002"]}}
+JSON
+cat > "$TMP/bad-layer.json" <<'JSON'
+{"version":"1.0","harness_phase":"active","scaffold":{"confirmed":true},
+ "active_slice":{"epica":"EP-001","hus":["HU-001"],"openspec_change":"x","branch":"feature/x","phase":"change",
+   "layer":"WRONG","gates":{"dor":true,"tdd":false,"dod":false},"updated_at":"2026-07-03T00:00:00Z","updated_by":"t"},
+ "history":[],"releases":[]}
+JSON
+check "estado válido con campos nuevos" pass "$TMP/valid.json"
+check "layer inválido rechazado" fail "$TMP/bad-layer.json"
+
+CFG="$ROOT/config/build-config.template.json"
+if [ -f "$CFG" ] && python3 -c "import json,sys; d=json.load(open('$CFG'))['context']; assert d['warning_pct']==35 and d['critical_pct']==25 and d['auto_checkpoint'] is False" 2>/dev/null; then
+  echo "OK   build-config.template.json con defaults"
+else echo "FAIL build-config.template.json con defaults"; fail=1; fi
+
+CMD="$ROOT/commands/build/resume.md"
+{ [ -f "$CMD" ] && grep -q 'reconcile-build-state.py' "$CMD" && grep -q 'session_continuity' "$CMD"; } \
+  && echo "OK   comando resume" || { echo "FAIL comando resume"; fail=1; }
+
+exit $fail

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

@@ -16,6 +16,8 @@ la épica; lo de abajo aplica a la épica y a **cada HU** que cubre (`hus[]`). L
 - [ ] **Fuente de diseño identificada (slices con UI)**: la fuente visual de verdad del slice
   (el `DESIGN_SOURCE` del dominio) está declarada y confirmada (`design_source.confirmed`), y este
   slice apunta a la(s) pantalla(s) equivalente(s). No se construye UI fuera de la fuente declarada.
+- [ ] **Clasificación `layer`**: `foundational` (auth/datos/design-system/arquitectura base) | `business`. Se escribe en `active_slice.layer`. Gatea el front paralelo (foundational nunca en paralelo).
+- [ ] **`files_scope`**: globs de los archivos que la épica tocará (p.ej. `src/reports/**`). Fuente de la disjunción inter-épica. Se escribe en `active_slice.files_scope`.
 
 **Si todo ✓** → `dor-dod-gatekeeper` abre `active_slice` en `build-state.json` con `epica`, `hus[]`,
 `phase: dor`, `gates.dor: true` y el resto en `false` —incluido **`wiring_verified: false`**—

package/skills/managing-parallel-front/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: managing-parallel-front
+description: Use when building multiple NON-foundational, file-disjoint epics in parallel via git worktrees. Coordinates the parallel_front in build-state.json (selection, worktrees, deterministic merge order with re-smoke). Never parallelizes foundational epics or overlapping file scopes.
+---
+
+# Gestionar el front paralelo inter-épica (outer-loop)
+
+**Invariante:** el paralelismo es outer-loop. Cada worktree es un checkout aislado con su
+**propio** `build-state.json` y su `active_slice` singular (el inner loop no cambia).
+
+## Precondiciones (compuertas)
+- `scaffold.confirmed == true`.
+- **G1 Fundacionales primero:** ninguna épica `layer=foundational` abierta. Si aparece una,
+  poner `parallel_front.status="draining"` (terminar en curso, no admitir nuevas) antes de abrirla.
+
+## Procedimiento
+1. **Reunir candidatas** no fundacionales listas (DoR pasado), cada una con `layer` y `files_scope`.
+2. **Seleccionar el conjunto disjunto** (G2):
+   `echo "$CANDS" | python3 .claude/scripts/lib/front-plan.py`
+   → `selected` van al front; `serialized` esperan (construir secuencial después);
+   `excluded_foundational` nunca en paralelo.
+3. **Abrir un worktree por épica seleccionada:**
+   `git worktree add ".wt/<epica>" -b feature/<slug>` (rama por `1 épica = 1 rama = 1 PR`).
+   Registrar el miembro en `parallel_front.members[]` (`merge_status:"pending"`).
+4. **Construir cada worktree** con la skill `building-a-slice` (inner loop normal, en su cwd).
+   Cada uno mantiene su `journey_smoke` verde localmente.
+5. **Coordinar merge (G3)** en `merge_order` (determinista: por orden de épica):
+   - Merge del PR; tras cada merge, **re-smoke del journey completo** en el árbol principal.
+   - Conflicto → `merge_status:"conflict"`, serializar la perdedora (rebase + re-correr sus gates).
+   - Éxito → `merge_status:"merged"`; `git worktree remove`.
+6. **Cerrar el front** cuando todos `merged`: `parallel_front=null`.
+
+## Reglas duras
+- Nunca escritores paralelos sobre el mismo árbol (por eso worktrees).
+- Nunca paralelizar dentro de una épica (preserva la "regla del esqueleto que camina").
+- Un solape de `files_scope` no detectado que cause conflicto de merge → el re-smoke (G3) lo caza.

package/state/build-state.schema.json

@@ -31,6 +31,10 @@
       "type": "array",
       "description": "Release Gates (outer loop). Una entrada por línea de release del Story Map auditada en bloque.",
       "items": { "$ref": "#/$defs/release" }
+    },
+    "parallel_front": {
+      "description": "Coordinación outer-loop de worktrees inter-épica (C). null = modo secuencial normal.",
+      "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/parallel_front" } ]
     }
   },
   "$defs": {
@@ -75,6 +79,7 @@
         },
         "openspec_change": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
         "branch": { "type": "string", "pattern": "^(feature|fix|chore)/[a-z0-9._-]+$" },
+        "branch_drift": { "type": "string", "description": "Rama git real cuando difiere de branch (lo escribe el reconciliador)." },
         "phase": {
           "type": "string",
           "enum": ["dor", "change", "red", "green", "refactor", "smoke", "api", "data", "dod", "pr", "archived"]
@@ -151,6 +156,19 @@
               "journey_smoke": { "type": "boolean", "description": "El backbone-hasta-este-sub-slice camina end-to-end." }
             }
           }
+        },
+        "layer": { "type": "string", "enum": ["foundational", "business"], "default": "business", "description": "Clasificación (taxonomía existente del arnés): foundational (auth/datos/design-system/arquitectura base) nunca va en paralelo; business = épica de negocio (paralelizable si es disjunta). Gatea el front paralelo (C)." },
+        "files_scope": { "type": "array", "items": { "type": "string" }, "description": "Globs de archivos que la épica toca. Fuente de la disjunción inter-épica (G2)." },
+        "session_continuity": {
+          "type": "object", "additionalProperties": false,
+          "description": "Handoff de sesión (A): permite resume sin pérdida tras presión de contexto.",
+          "properties": {
+            "last_session": { "type": ["string", "null"] },
+            "stopped_at": { "type": ["string", "null"], "description": "p.ej. 'context exhaustion at 24% (ISO)'." },
+            "resume_hint": { "type": ["string", "null"], "description": "Siguiente acción concisa." },
+            "critical_recorded": { "type": "boolean", "description": "Guard once-per-session del auto-handoff." },
+            "auto_continue": { "type": "boolean", "description": "true cuando context.auto_checkpoint disparó continuación automática (§4.4)." }
+          }
         }
       }
     },
@@ -184,6 +202,38 @@
         "created_at": { "type": "string", "format": "date-time" },
         "updated_by": { "type": "string" }
       }
+    },
+    "parallel_front": {
+      "type": "object", "additionalProperties": false,
+      "required": ["status", "opened_at", "updated_by", "members", "merge_order"],
+      "properties": {
+        "status": { "type": "string", "enum": ["active", "draining"] },
+        "opened_at": { "type": "string", "format": "date-time" },
+        "updated_by": { "type": "string" },
+        "members": {
+          "type": "array",
+          "items": {
+            "type": "object", "additionalProperties": false,
+            "required": ["epica", "worktree", "files_scope", "merge_status"],
+            "properties": {
+              "epica": { "type": "string", "pattern": "^EP-[0-9]{3}$" },
+              "worktree": {
+                "type": "object", "additionalProperties": false,
+                "required": ["path", "branch", "created_at"],
+                "properties": {
+                  "path": { "type": "string" },
+                  "branch": { "type": "string", "pattern": "^(feature|fix|chore)/[a-z0-9._-]+$" },
+                  "created_at": { "type": "string", "format": "date-time" }
+                }
+              },
+              "files_scope": { "type": "array", "items": { "type": "string" } },
+              "journey_smoke": { "type": "boolean" },
+              "merge_status": { "type": "string", "enum": ["pending", "merged", "conflict"] }
+            }
+          }
+        },
+        "merge_order": { "type": "array", "items": { "type": "string", "pattern": "^EP-[0-9]{3}$" } }
+      }
     }
   }
 }