@trycore/spec-build-harness 0.14.2 → 0.16.0

package/scripts/tests/test-worktree-identity.sh

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+# test-worktree-identity.sh — identidad por árbol de trabajo [#74].
+#
+# El caso real: dos agentes construyendo dos épicas del mismo proyecto en la misma máquina,
+# uno por worktree. El hub reparte las dos sin objeción; el bloqueo estaba en el cliente —
+# un worktree sin `.claude/state/runtime.credentials` propio hereda el del clon principal
+# (`config_root()` cae al `--git-common-dir`) y firma sus actos con la identidad ajena.
+#
+# Cubre: la compuerta de escritura de slice-ops.sh/release-ops.sh (rc 9), el banner de
+# `status` y el alta explícita con `slice-ops.sh register` contra el stub HTTP.
+set -uo pipefail
+ROOT="$(git rev-parse --show-toplevel)"
+fail=0
+TMP="$(mktemp -d)"
+STUBS=""
+cleanup() {
+  for p in $STUBS; do kill "$p" 2>/dev/null; wait "$p" 2>/dev/null; done
+  git -C "$MAIN" worktree remove --force "$WT" >/dev/null 2>&1
+  rm -rf "$TMP"
+}
+SO="$ROOT/hooks/build/slice-ops.sh"
+RO="$ROOT/hooks/build/release-ops.sh"
+freeport() { python3 -c "import socket;s=socket.socket();s.bind(('',0));print(s.getsockname()[1]);s.close()"; }
+sha() { python3 -c "import hashlib,sys; print(hashlib.sha256(open(sys.argv[1],'rb').read()).hexdigest())" "$1" 2>/dev/null; }
+cred() { python3 -c "import json,sys; print(json.load(open(sys.argv[1])).get(sys.argv[2]) or '')" "$1" "$2" 2>/dev/null; }
+
+# ── Escenario: clon principal registrado + worktree recién abierto, sin nada ────────────
+MAIN="$(mkdir -p "$TMP/main" && cd "$TMP/main" && pwd -P)"
+WT="$TMP/wt"
+trap cleanup EXIT
+mkdir -p "$MAIN/.claude/state" "$MAIN/.claude/config"
+git -C "$MAIN" init -q 2>/dev/null
+git -C "$MAIN" config user.email t@t.io; git -C "$MAIN" config user.name t
+echo x > "$MAIN/f"; git -C "$MAIN" add -A >/dev/null 2>&1; git -C "$MAIN" commit -qm init >/dev/null 2>&1
+git -C "$MAIN" worktree add -q "$WT" -b wt-test >/dev/null 2>&1
+WT="$(cd "$WT" && pwd -P)"
+echo '{"runtime":{"mode":"runtime","stale_seconds":900}}' > "$MAIN/.claude/config/build-config.json"
+
+PORT="$(freeport)"
+cat > "$TMP/routes.json" <<JSON
+{"POST /agents/register": {"status": 200, "body": {"agent_key": "ak-wt", "project_id": "p-1", "poll_interval_s": 5, "lease_ttl_s": 300, "manifest_hash": "sha256:v1"}}}
+JSON
+: > "$TMP/calls.jsonl"
+python3 "$ROOT/scripts/tests/lib/http-stub.py" "$PORT" "$TMP/routes.json" "$TMP/calls.jsonl" &
+STUBS="$STUBS $!"
+sleep 0.3
+cat > "$MAIN/.claude/state/runtime.credentials" <<JSON
+{"runtime_url":"http://127.0.0.1:$PORT","project_token":"tok-main","project_id":"p-1","agent_key":"ak-main"}
+JSON
+MAIN_SHA_0="$(sha "$MAIN/.claude/state/runtime.credentials")"
+MAINCRED="$MAIN/.claude/state/runtime.credentials"
+WTCRED="$WT/.claude/state/runtime.credentials"
+
+# `curl` falso al frente del PATH: sirve para probar que la compuerta corta ANTES de la red.
+mkdir -p "$TMP/fakebin"
+cat > "$TMP/fakebin/curl" <<'FAKE'
+#!/usr/bin/env bash
+echo "$@" >> "$FAKE_CURL_LOG"
+exit 0
+FAKE
+chmod +x "$TMP/fakebin/curl"
+
+# wt <args…> — corre slice-ops.sh DENTRO del worktree, como lo haría el agente de ese árbol.
+wt() { (cd "$WT" && CLAUDE_PROJECT_DIR="$WT" bash "$SO" "$@"); }
+
+# ── 1) Toda escritura aborta con rc 9 y sin tocar la red ────────────────────────────────
+: > "$TMP/curl-guard.log"
+for sub in claim submit escalate progress checkpoint "gate dor pass" "phase change" "fact foundation" \
+           "wiring seed" "archive" "propose-epic" "graph-sync"; do
+  rc=0
+  out="$(cd "$WT" && PATH="$TMP/fakebin:$PATH" FAKE_CURL_LOG="$TMP/curl-guard.log" \
+         CLAUDE_PROJECT_DIR="$WT" bash "$SO" $sub 2>&1)" || rc=$?
+  if [ "$rc" = 9 ]; then
+    echo "OK «${sub%% *}» aborta con rc 9 desde un worktree sin identidad"
+  else
+    echo "FAIL «$sub» rc=$rc (esperado 9): $out"; fail=1
+  fi
+done
+[ ! -s "$TMP/curl-guard.log" ] && echo "OK la compuerta corta ANTES de abrir un socket" \
+  || { echo "FAIL la compuerta dejó salir tráfico"; fail=1; }
+
+rc=0; out="$(wt claim 2>&1)" || rc=$?
+echo "$out" | grep -q "register" && echo "OK el mensaje del guard dice cómo salir (register)" \
+  || { echo "FAIL el guard no es accionable: $out"; fail=1; }
+echo "$out" | grep -q "$MAIN" && echo "OK el mensaje nombra el clon principal suplantado" \
+  || { echo "FAIL el guard no nombra al principal: $out"; fail=1; }
+
+rc=0
+out="$(cd "$WT" && CLAUDE_PROJECT_DIR="$WT" bash "$RO" front-integration f-1 --merge-status merged 2>&1)" || rc=$?
+[ "$rc" = 9 ] && echo "OK release-ops front-integration aborta con rc 9" \
+  || { echo "FAIL front-integration rc=$rc: $out"; fail=1; }
+
+# ── 2) Las lecturas siguen funcionando, con banner ──────────────────────────────────────
+rc=0; out="$(wt status --no-refresh 2>&1)" || rc=$?
+[ "$rc" = 0 ] && echo "OK status sigue funcionando con identidad heredada" \
+  || { echo "FAIL status rc=$rc: $out"; fail=1; }
+echo "$out" | grep -q "HEREDADA" && echo "OK status avisa de la identidad heredada" \
+  || { echo "FAIL status no muestra el banner: $out"; fail=1; }
+[ "$(wt mode)" = "runtime" ] && echo "OK mode se lee sin compuerta" || { echo "FAIL mode"; fail=1; }
+
+# ── 3) register: el token NO se acepta por argumento ────────────────────────────────────
+rc=0; out="$(wt register --token tok-x 2>&1)" || rc=$?
+[ "$rc" = 2 ] && echo "OK register rechaza --token (el historial del shell no es un llavero)" \
+  || { echo "FAIL register --token rc=$rc: $out"; fail=1; }
+[ ! -f "$WTCRED" ] && echo "OK register --token no escribió nada" || { echo "FAIL escribió credenciales"; fail=1; }
+
+# ── 4) register con el token del clon principal: rechazo, y el principal INTACTO ────────
+rc=0; out="$(cd "$WT" && CLAUDE_PROJECT_DIR="$WT" bash "$SO" register <<< "tok-main" 2>&1)" || rc=$?
+[ "$rc" = 6 ] && echo "OK register rechaza el token del clon principal" \
+  || { echo "FAIL token repetido rc=$rc: $out"; fail=1; }
+echo "$out" | grep -qi "agent_id" && echo "OK el rechazo dice qué pedirle al ADMIN" \
+  || { echo "FAIL rechazo poco accionable: $out"; fail=1; }
+[ ! -f "$WTCRED" ] && echo "OK el token repetido no dejó credenciales locales" \
+  || { echo "FAIL quedaron credenciales tras el rechazo"; fail=1; }
+[ "$(sha "$MAINCRED")" = "$MAIN_SHA_0" ] && echo "OK el fichero del clon principal quedó intacto" \
+  || { echo "FAIL se tocó el fichero del clon principal"; fail=1; }
+
+# ── 5) register cuando el hub devuelve el MISMO agent_key: rechazo + rollback ───────────
+cat > "$TMP/routes.json" <<JSON
+{"POST /agents/register": {"status": 200, "body": {"agent_key": "ak-main", "project_id": "p-1"}}}
+JSON
+rc=0; out="$(cd "$WT" && CLAUDE_PROJECT_DIR="$WT" bash "$SO" register <<< "tok-otro" 2>&1)" || rc=$?
+[ "$rc" = 6 ] && echo "OK register rechaza un token que resuelve al agent_key del principal" \
+  || { echo "FAIL agent_key repetido rc=$rc: $out"; fail=1; }
+[ ! -f "$WTCRED" ] && echo "OK rollback: no quedan credenciales a medias" \
+  || { echo "FAIL quedaron credenciales tras el rollback"; fail=1; }
+[ "$(sha "$MAINCRED")" = "$MAIN_SHA_0" ] && echo "OK el clon principal sigue intacto tras el rollback" \
+  || { echo "FAIL el rollback tocó al principal"; fail=1; }
+
+# ── 6) Sin red: rollback y rc 5 ─────────────────────────────────────────────────────────
+DEADPORT="$(freeport)"
+rc=0; out="$(cd "$WT" && CLAUDE_PROJECT_DIR="$WT" bash "$SO" register --runtime-url "http://127.0.0.1:$DEADPORT" <<< "tok-wt" 2>&1)" || rc=$?
+[ "$rc" = 5 ] && echo "OK register sin red -> rc 5" || { echo "FAIL register offline rc=$rc: $out"; fail=1; }
+[ ! -f "$WTCRED" ] && echo "OK register sin red no deja credenciales huérfanas" \
+  || { echo "FAIL quedaron credenciales tras el fallo de red"; fail=1; }
+
+# ── 7) Camino feliz: identidad propia, solo en el worktree ──────────────────────────────
+cat > "$TMP/routes.json" <<JSON
+{"POST /agents/register": {"status": 200, "body": {"agent_key": "ak-wt", "project_id": "p-1", "lease_ttl_s": 300, "manifest_hash": "sha256:v1"}}}
+JSON
+: > "$TMP/calls.jsonl"
+rc=0; out="$(cd "$WT" && CLAUDE_PROJECT_DIR="$WT" bash "$SO" register <<< "tok-wt" 2>&1)" || rc=$?
+[ "$rc" = 0 ] && echo "OK register con token propio -> rc 0" || { echo "FAIL register feliz rc=$rc: $out"; fail=1; }
+echo "$out" | grep -q "tok-wt" && { echo "FAIL register imprimió el token"; fail=1; } \
+  || echo "OK register nunca imprime el token"
+[ -f "$WTCRED" ] && echo "OK las credenciales quedan en el worktree" || { echo "FAIL sin credenciales locales"; fail=1; }
+[ "$(cred "$WTCRED" agent_key)" = "ak-wt" ] && echo "OK el worktree tiene su propio agent_key" \
+  || { echo "FAIL agent_key local ($(cred "$WTCRED" agent_key))"; fail=1; }
+[ "$(cred "$WTCRED" project_token)" = "tok-wt" ] && echo "OK el token propio quedó persistido" \
+  || { echo "FAIL token local"; fail=1; }
+[ "$(cred "$WTCRED" project_id)" = "p-1" ] && echo "OK mismo proyecto, otro agente" || { echo "FAIL project_id"; fail=1; }
+[ "$(sha "$MAINCRED")" = "$MAIN_SHA_0" ] && echo "OK el clon principal NUNCA se tocó" \
+  || { echo "FAIL el alta pisó al clon principal"; fail=1; }
+grep -q '"auth": "Bearer tok-wt"' "$TMP/calls.jsonl" \
+  && echo "OK el registro viajó con el token NUEVO, no con el heredado" \
+  || { echo "FAIL el registro no usó el token nuevo: $(cat "$TMP/calls.jsonl")"; fail=1; }
+perm="$(python3 -c "import os,stat,sys; print(oct(stat.S_IMODE(os.stat(sys.argv[1]).st_mode)))" "$WTCRED")"
+[ "$perm" = "0o600" ] && echo "OK credenciales 0600" || { echo "FAIL permisos $perm"; fail=1; }
+[ -f "$WT/.claude/config/build-config.json" ] \
+  && echo "OK register copió build-config.json (el árbol no cae a legacy)" \
+  || { echo "FAIL sin build-config el worktree registrado caería a legacy"; fail=1; }
+
+# ── 8) Ya registrado: la compuerta se abre y register es idempotente ────────────────────
+rc=0; out="$(wt claim 2>&1)" || rc=$?
+[ "$rc" != 9 ] && echo "OK tras register el claim ya no choca con la compuerta (rc $rc)" \
+  || { echo "FAIL sigue bloqueado tras registrar: $out"; fail=1; }
+rc=0; out="$(wt status --no-refresh 2>&1)" || rc=$?
+echo "$out" | grep -q "HEREDADA" && { echo "FAIL status sigue diciendo heredada"; fail=1; } \
+  || echo "OK status ya no marca identidad heredada"
+echo "$out" | grep -q "ak-wt" && echo "OK status informa del agente propio" || { echo "FAIL status no ve ak-wt: $out"; fail=1; }
+rc=0; out="$(wt register 2>&1 </dev/null)" || rc=$?
+[ "$rc" = 0 ] && echo "$out" | grep -q "YA tiene identidad" \
+  && echo "OK register es idempotente: no vuelve a pedir token" \
+  || { echo "FAIL register no idempotente rc=$rc: $out"; fail=1; }
+[ "$(cred "$WTCRED" agent_key)" = "ak-wt" ] && echo "OK la identidad no cambió al repetir register" \
+  || { echo "FAIL register repetido alteró la identidad"; fail=1; }
+
+# ── 8-bis) --force rota el token y ESTRENA identidad (no recicla el agent_key viejo) ────
+cat > "$TMP/routes.json" <<JSON
+{"POST /agents/register": {"status": 200, "body": {"agent_key": "ak-wt2", "project_id": "p-1"}}}
+JSON
+rc=0; out="$(cd "$WT" && CLAUDE_PROJECT_DIR="$WT" bash "$SO" register --force <<< "tok-wt2" 2>&1)" || rc=$?
+[ "$rc" = 0 ] && [ "$(cred "$WTCRED" agent_key)" = "ak-wt2" ] && [ "$(cred "$WTCRED" project_token)" = "tok-wt2" ] \
+  && echo "OK register --force rota token e identidad" \
+  || { echo "FAIL register --force rc=$rc key=$(cred "$WTCRED" agent_key): $out"; fail=1; }
+
+# Un 200 SIN agent_key no puede pasar por bueno reciclando el de la identidad anterior.
+cat > "$TMP/routes.json" <<JSON
+{"POST /agents/register": {"status": 200, "body": {"project_id": "p-1"}}}
+JSON
+rc=0; out="$(cd "$WT" && CLAUDE_PROJECT_DIR="$WT" bash "$SO" register --force <<< "tok-wt3" 2>&1)" || rc=$?
+[ "$rc" = 6 ] && echo "OK register rechaza un 200 sin agent_key" \
+  || { echo "FAIL 200 sin agent_key rc=$rc: $out"; fail=1; }
+[ "$(cred "$WTCRED" agent_key)" = "ak-wt2" ] && [ "$(cred "$WTCRED" project_token)" = "tok-wt2" ] \
+  && echo "OK el rollback devuelve la identidad anterior intacta" \
+  || { echo "FAIL rollback de --force perdió la identidad previa"; fail=1; }
+[ "$(sha "$MAINCRED")" = "$MAIN_SHA_0" ] && echo "OK el clon principal sigue intacto tras --force" \
+  || { echo "FAIL --force tocó al principal"; fail=1; }
+
+# ── 9) El clon principal nunca pasa por la compuerta ────────────────────────────────────
+rc=0
+out="$(cd "$MAIN" && PATH="$TMP/fakebin:$PATH" FAKE_CURL_LOG="$TMP/curl-main.log" \
+       CLAUDE_PROJECT_DIR="$MAIN" bash "$SO" claim 2>&1)" || rc=$?
+[ "$rc" != 9 ] && echo "OK el clon principal no queda bloqueado por su propio guard (rc $rc)" \
+  || { echo "FAIL el guard bloquea al dueño del estado: $out"; fail=1; }
+
+exit $fail

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

@@ -1,40 +1,64 @@
 ---
 name: managing-parallel-front
-description: Use when building multiple NON-foundational, file-disjoint epics in parallel via git worktrees. Prepares the disjoint selection and merge order locally (front-plan.py), drives each worktree as its own registered agent, and reports each member's integration (re-smoke, merge_status) through the agent surface. Planning, opening, draining and closing the front are human acts in the hub console. Never parallelizes foundational epics or overlapping file scopes.
+description: Use when building multiple NON-foundational, file-disjoint epics in parallel via git worktrees. Prepares the disjoint selection and merge order locally (front-plan.py), enrolls each worktree as its own agent with its own ADMIN-issued token (slice-ops.sh register), and reports each member's integration (re-smoke, merge_status) through the agent surface. Planning, opening, draining and closing the front are human acts in the hub console. Never parallelizes foundational epics, overlapping file scopes, or two worktrees sharing one token.
 ---
 
 # Gestionar el front paralelo inter-épica (outer-loop)
 
 **Invariante:** el paralelismo es outer-loop. Cada worktree es un checkout aislado con **su
-propio agente registrado** (mismo token de proyecto, `agent_key` distinto) y un slice activo
-singular: el inner loop no cambia.
+propio agente registrado** — un token propio, emitido por el ADMIN para ese agente — y un slice
+activo singular: el inner loop no cambia.
+
+> **Un token por agente, no uno por proyecto.** El hub **no crea identidad** en
+> `POST /agents/register`: el `agent_key` es el `agent_id` que el ADMIN grabó en el token al
+> emitirlo. Dos worktrees con el mismo token son **el mismo agente**, y el segundo `claim`
+> devuelve el slice que ya tiene reclamado el primero. Y un worktree **sin** credenciales
+> propias no queda huérfano: hereda en silencio las del clon principal (`config_root()` cae
+> al `--git-common-dir`) y **suplanta** a ese agente. Por eso toda escritura —`claim`, `gate`,
+> `submit`, `archive`, `wiring`, `progress`, `checkpoint`, `fact`, `escalate`,
+> `front-integration`— aborta con **rc 9** hasta que el árbol se da de alta. Las lecturas
+> (`status`, `next-step`) siguen funcionando, y `status` avisa con `identidad: ⚠ HEREDADA`.
 
 **Reparto agente ↔ humano (spec §2).** El agente **prepara y reporta**; la persona **decide**:
 
 | Acto | Quién |
 |---|---|
 | Proponer el conjunto disjunto y el `merge_order` (`front-plan.py`, local) | agente |
+| **Emitir un token por agente** (uno por worktree, `agent_id` distinto) | **humano** (ADMIN), en la consola del hub |
 | **Planificar, abrir, drenar y cerrar** el front | **humano**, en la consola del hub |
 | Construir cada worktree (inner loop) | agente (uno por worktree) |
 | Reportar re-smoke y `merge_status` de su miembro | agente, vía `release-ops.sh front-integration` |
 
 ## Precondiciones (compuertas)
 - Scaffold confirmado (`bash .claude/hooks/build/slice-ops.sh status`).
+- **Un token de agente por worktree**, ya emitido por el ADMIN (paso 3). Sin él no hay front:
+  no es un trámite, es lo que hace que dos agentes sean dos.
 - **G1 Fundacionales primero:** ninguna épica `layer=foundational` abierta. Si aparece una, el
   front debe **drenarse** (terminar en curso, no admitir nuevas) antes de abrirla — el drenaje
   lo hace una persona en la consola.
 
 ## Procedimiento
-1. **Reunir candidatas** no fundacionales listas (DoR pasado), cada una con `layer` y `files_scope`.
+1. **Reunir candidatas** no fundacionales listas (DoR pasado), cada una con `layer`,
+   `files_scope` y `depends_on` (las dependencias declaradas del grafo; `graph-bundle.py` ya las
+   computa desde los docs de discovery). Sin `files_scope` declarado una épica **no es
+   candidata** y `front-plan.py` la serializa — no es un olvido tolerable, es la compuerta.
 2. **Seleccionar el conjunto disjunto** (G2), en local:
    `echo "$CANDS" | python3 .claude/scripts/lib/front-plan.py`
-   → `selected` propuestas al front; `serialized` esperan (construir secuencial después);
+   → `selected` propuestas al front; `serialized` esperan (construir secuencial después) por
+   solape de ficheros, por camino en el DAG de `depends_on` o por no declarar `files_scope`;
    `excluded_foundational` nunca en paralelo. **Presenta el plan al humano**: es él quien abre el
    front en la consola con ese `merge_order`.
-3. **Abrir un worktree por épica aprobada:**
+3. **Abrir un worktree por épica aprobada y darlo de alta con su propio token:**
    `git worktree add ".wt/<epica>" -b feature/<slug>` (rama por `1 épica = 1 rama = 1 PR`).
-   En cada worktree corre `trycore-build init` con el **mismo token de proyecto**: se registra
-   como agente propio y obtiene su `agent_key`.
+   El estado del arnés está en `.gitignore`, así que **no viaja al worktree**: en cada uno,
+   1. `trycore-build init` (sin `--runtime-token`) para tender `.claude/`;
+   2. `bash .claude/hooks/build/slice-ops.sh register` — **pide el token por stdin**, nunca por
+      argumento (un `--token` queda en el historial del shell y en `ps`). Cada worktree usa el
+      token que el ADMIN emitió **para ese agente**.
+   `register` siembra las credenciales locales antes de tocar la red, verifica contra el hub que
+   el `agent_key` obtenido **difiere** del del clon principal y, ante cualquier fallo, revierte:
+   el fichero del clon principal nunca se toca. Si el token repetido es el del principal, lo
+   rechaza y te manda a pedir uno con `agent_id` distinto.
 4. **Construir cada worktree** con la skill `building-a-slice` (inner loop normal, en su cwd).
    Cada uno reclama su slice y mantiene su `journey_smoke` verde localmente.
 5. **Coordinar merge (G3)** en el `merge_order` aprobado:
@@ -46,6 +70,9 @@ singular: el inner loop no cambia.
    (el agente solo reporta que su miembro terminó).
 
 ## Reglas duras
+- **Un token por agente.** Dos worktrees con el mismo token son un solo agente para el hub.
+- Un worktree sin dar de alta **no trabaja**: toda escritura sale con rc 9 hasta que corras
+  `register`. No lo esquives exportando `CLAUDE_PROJECT_DIR` — el guard compara el árbol real.
 - 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.