@trycore/spec-build-harness 0.14.2 → 0.16.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "trycore-spec-build-harness",
   "displayName": "Trycore — Spec & Build Harness",
-  "version": "0.14.2",
+  "version": "0.16.0",
   "description": "Arnés de construcción de dos loops (slice por épica + release gate) para Claude Code, con gates de calidad, estado compartido y OpenSpec. Compañero de @trycore/spec-product-flow. Agnóstico al proyecto.",
   "author": {
     "name": "Trycore",

package/GOVERNANCE.md

@@ -8,7 +8,7 @@ evoluciona con el modelo y el proyecto. No es "instalar y olvidar".
 |---|---|---|
 | Contexto | sección Construcción de CLAUDE.md, `openspec/project.md` | raíz / `openspec/` |
 | Estado (modo `legacy`, default) | `build-state.json` (+schema, README) | `.claude/state/` |
-| Cliente runtime (modo `dual`/`runtime`, opt-in — beta) | `runtime.credentials` (0600), `context.lock`, `runtime-projection.json`, `outbox/`; `slice-ops.sh`/`release-ops.sh` (13 subcomandos) | `.claude/state/`, `.claude/hooks/build/` |
+| Cliente runtime (modo `dual`/`runtime`, opt-in — beta) | `runtime.credentials` (0600), `context.lock`, `runtime-projection.json`, `outbox/`; `slice-ops.sh`/`release-ops.sh` (20 + 3 subcomandos) | `.claude/state/`, `.claude/hooks/build/` |
 | Agentes | 14 agentes de build | `.claude/agents/build/` |
 | Hooks | settings.json + 19 scripts (15 registrados + 4 invocados: `reconcile-build-state.py`, `context-sync.sh`, `heartbeat.sh` como daemon, `statusline-bridge.sh` como comando `statusLine`) | `.claude/settings.json`, `.claude/hooks/build/` |
 | Skill | `building-a-slice` (+11 refs · `workflows/`) · `releasing-a-version` (`workflows/`) · `building-a-micro-change` (carril ligero de mantenimiento) · `managing-parallel-front` (front paralelo inter-épica) · `prototyping-screens` (prototipo HTML de referencia) | `.claude/skills/` |

package/INSTALL.md

@@ -107,7 +107,7 @@ Qué hace `init`:
 1. **Verifica requisitos duros** (a menos que uses `--skip-doctor`).
 2. **Siembra los assets** en rutas nativas de Claude Code:
    - `.claude/agents/build/` — 14 agentes.
-   - `.claude/commands/opsx/` (10 comandos `/opsx:*`) y `.claude/commands/build/` (13 comandos: `/build:onboard`, `/build:reflect`, `/build:architect`, `/build:prototype`, `/build:slice`, `/build:release`, `/build:work`, `/build:resume`, `/build:front`, `/build:claim`, `/build:status`, `/build:escalate`, `/build:epic`). Los cuatro últimos son la **superficie de agente del modo runtime** (§9): en `legacy`, `claim`, `escalate` y `epic` devuelven `rc 3` remitiendo al flujo del fichero, y `status` informa de que la fuente de verdad es `build-state.json`.
+   - `.claude/commands/opsx/` (10 comandos `/opsx:*`) y `.claude/commands/build/` (14 comandos: `/build:onboard`, `/build:reflect`, `/build:architect`, `/build:prototype`, `/build:slice`, `/build:release`, `/build:work`, `/build:resume`, `/build:front`, `/build:claim`, `/build:status`, `/build:escalate`, `/build:epic`, `/build:graph-sync`). Los cinco últimos son la **superficie de agente del modo runtime** (§9): en `legacy`, `claim`, `escalate`, `epic` y `graph-sync` devuelven `rc 3` remitiendo al flujo del fichero, y `status` informa de que la fuente de verdad es `build-state.json`.
    - `.claude/skills/` — 16 skills (`building-a-slice`, `building-a-micro-change`, `releasing-a-version`, `managing-parallel-front`, `setup-architecture`, `prototyping-screens`, `openspec-*`).
    - `.claude/hooks/build/` — 19 hooks (bash + python; 6 son del cliente runtime opt-in — §9).
 3. **Siembra el estado**: `state/build-state.schema.json` y `state/README.md` se versionan;

package/METODOLOGIA.md

@@ -332,15 +332,26 @@ worktree— y coordina la selección, la construcción y el merge desde el estad
 (`parallel_front`). Es un concepto de **outer-loop**: no es una fase nueva del pipeline por-épica, es
 orquestación **entre** épicas.
 
+**Compuerta cero: un agente por worktree, un token por agente.** En modo `runtime`, cada worktree
+se da de alta como **agente propio** con un token que el ADMIN emitió **para él**
+(`slice-ops.sh register`, que lo pide por stdin). No es un trámite: el hub deriva el `agent_key`
+del `agent_id` grabado en el token, así que dos worktrees con el mismo token son **un solo agente**
+y el segundo `claim` devuelve el slice del primero. Y un worktree **sin** credenciales propias no
+queda huérfano — hereda las del clon principal y **suplanta** a ese agente. Por eso toda escritura
+desde un árbol sin identidad propia aborta con `rc 9` (issue #74).
+
 **Compuertas del front:**
 
 1. **Foundational-first (G1).** Ninguna épica `layer: foundational` entra jamás al front: el
    cimiento se construye secuencial, antes que el negocio (§1-bis.2, §3.1). Solo épicas
    `layer: business` son candidatas a paralelizarse.
-2. **Disjunción por `files_scope` (G2).** `scripts/lib/front-plan.py` calcula, a partir de los globs
-   declarados en `files_scope` de cada épica candidata, qué subconjunto es mutuamente disjunto
-   (`selected`, va al front) y cuál se solapa (`serialized`, espera y se construye después,
-   secuencial). Sin `files_scope` declarado, una épica no es candidata al front.
+2. **Disjunción por `files_scope` y por el grafo (G2).** `scripts/lib/front-plan.py` calcula, a
+   partir de los globs declarados en `files_scope` de cada épica candidata, qué subconjunto es
+   mutuamente disjunto (`selected`, va al front) y cuál se solapa (`serialized`, espera y se
+   construye después, secuencial). Sin `files_scope` declarado, una épica **no es candidata** al
+   front: el script la serializa (fail-closed). Tampoco son paralelizables dos épicas unidas por
+   un camino en el DAG de `depends_on`, aunque sus ficheros sean disjuntos — la de abajo
+   construiría sobre lo que la de arriba todavía no ha mergeado.
 3. **Merge en orden + re-smoke (G3).** El merge de los worktrees sigue un `merge_order`
    determinista; tras **cada** merge se re-corre el `journey_smoke` completo sobre el árbol
    principal (no basta con el smoke local del worktree). Un solape no capturado por la disjunción

package/README.md

@@ -80,6 +80,7 @@ Gate de release que corre **una sola vez por versión** sobre el conjunto de sli
 | `/build:resume` | Rehidrata el slice activo **desde disco** (no desde la conversación) tras un reinicio de contexto: reconcilia el estado, lee `session_continuity`/`wiring_checklist`/`parallel_front` y determina la siguiente acción por prioridad. |
 | `/build:front` | Abre y coordina un **front paralelo** de épicas no fundacionales y disjuntas en archivos (`parallel_front`), cada una en su worktree/rama/PR. Delega en la skill `managing-parallel-front`. |
 | `/build:epic` | Propone una **épica incremental** al hub (modo `runtime`): el agente redacta y propone, el hub asigna el `EP-XXX` al aprobar y un humano aprueba; después `epicas.md` se escribe como **proyección** del grafo. En `legacy`/`dual` no aplica. |
+| `/build:graph-sync` | Propone el **re-sync del grafo** del hub desde los docs de discovery (modo `runtime`): el hub calcula el delta y un humano lo aprueba — nada se aplica sin esa aprobación. Con `--check` lee el veredicto. Sin esto, el grafo del hub se quedaba en la foto del import inicial y los eventos de las épicas posteriores rebotaban. |
 | `/opsx:*` (10) | Ciclo OpenSpec: `explore` · `new` · `continue` · `apply` · `verify` · `archive` · `bulk-archive` · `ff` · `onboard` · `sync`. Detalle → [`docs/commands.md`](docs/commands.md). |
 
 ## Gestión de contexto
@@ -120,14 +121,21 @@ Cuando hay **≥ 2 épicas de negocio (`layer: business`)** listas (DoR pasado)
 archivos**, el comando **`/build:front`** (skill `managing-parallel-front`) las construye en
 paralelo, cada una en su propio `git worktree`/rama/PR — el inner loop no cambia: cada worktree
 mantiene su `active_slice` singular y su propio `build-state.json`. Tres compuertas gobiernan el
-front:
+front (más una compuerta cero, de identidad, cuando se corre contra el hub):
 
+0. **Un agente por worktree, un token por agente** (modo `runtime`). Cada árbol se da de alta con
+   `slice-ops.sh register` y un token que el ADMIN emitió **para él**: el hub deriva el `agent_key`
+   del token, así que dos worktrees con el mismo token son un solo agente. Un árbol sin dar de alta
+   hereda las credenciales del clon principal y lo suplantaría — por eso toda escritura desde él
+   aborta con `rc 9`.
 1. **Foundational-first.** Ninguna épica `layer: foundational` entra jamás al front; si una aparece
    mientras el front está activo, el front pasa a `status: "draining"` (termina lo que ya empezó, no
    admite épicas nuevas) hasta vaciarse.
-2. **Disjunción por `files_scope`.** `scripts/lib/front-plan.py` calcula, por conjuntos de globs
-   declarados en cada épica, qué candidatas son mutuamente disjuntas (`selected`) y cuáles deben
-   esperar (`serialized`) por solaparse.
+2. **Disjunción por `files_scope` y por el grafo.** `scripts/lib/front-plan.py` calcula, por
+   conjuntos de globs declarados en cada épica, qué candidatas son mutuamente disjuntas
+   (`selected`) y cuáles deben esperar (`serialized`) por solaparse. Sin `files_scope` declarado una
+   épica **no es candidata** (se serializa), y dos épicas unidas por un camino en el DAG de
+   `depends_on` tampoco van juntas aunque sus ficheros sean disjuntos.
 3. **Merge en orden + re-smoke.** El merge de los worktrees sigue un `merge_order` determinista; tras
    cada merge se re-corre el `journey_smoke` completo en el árbol principal. Un conflicto no
    detectado por la disjunción declarada lo caza el re-smoke: la épica perdedora se serializa
@@ -143,7 +151,7 @@ trycore-spec-build-harness/
 ├── agents/build/              ← 14 agentes revisores (segunda opinión, contexto limpio)
 ├── commands/
 │   ├── opsx/                  ← 10 comandos /opsx:* (ciclo OpenSpec)
-│   └── build/                 ← 13 comandos /build:* (onboard, reflect, architect, prototype, slice, release, work, resume, front, claim, status, escalate, epic)
+│   └── build/                 ← 14 comandos /build:* (onboard, reflect, architect, prototype, slice, release, work, resume, front, claim, status, escalate, epic, graph-sync)
 ├── skills/                    ← 16 skills (building-a-slice, building-a-micro-change, releasing-a-version, managing-parallel-front, setup-architecture, prototyping-screens, 10 openspec-*) + 3 plantillas *.workflow.js (opt-in, read-only)
 ├── hooks/build/               ← 19 hooks (gate-check, reflect-nudge, release-gate-nudge, scaffold-guard, gitflow-guard, stack-guard, statusline-bridge, context-monitor, reconcile-build-state, …) + 6 opt-in del cliente runtime (session-start, event-emitter, context-sync, heartbeat, dual-compare, session-stop — ver docs/hooks.md)
 ├── state/                     ← máquina de estado legacy: build-state.json + schema + README
@@ -183,7 +191,36 @@ El core no menciona ningún dominio de cliente. Toda parametrización entra por
 
 ## Roadmap
 
-- ✅ **v0.14.0 (actual) — contexto vivo, épicas propuestas y versión de grafo** (#61, #62, #63) —
+- ✅ **v0.16.0 (actual) — identidad por árbol de trabajo** (#74) — construir dos épicas en paralelo
+  en la misma máquina, una por `git worktree`, ya es una operación segura. El reparto nunca fue el
+  problema del hub —ya entrega dos épicas a dos agentes sin objeción—: el bloqueo estaba en el
+  cliente. El estado del arnés está en `.gitignore` y no viaja a un worktree, así que el árbol nuevo
+  **heredaba en silencio** las credenciales del clon principal y lo suplantaba: reclamaba con su
+  `agent_key`, reportaba los sha del árbol equivocado (cegando la detección de drift justo en el
+  escenario paralelo) y compartía su heartbeat. Ahora toda **escritura** desde un árbol sin dar de
+  alta aborta con **`rc 9`** antes de abrir un socket (las lecturas siguen, y `status` avisa con
+  `identidad: ⚠ HEREDADA`), y el alta es explícita: **`slice-ops.sh register`**, con el token por
+  **stdin** —nunca por argumento—, siembra local antes de tocar la red, verificación de que el
+  `agent_key` **difiera** del principal y rollback total ante cualquier fallo. Dato que corrige la
+  documentación anterior: `POST /agents/register` **no crea identidad** —el `agent_key` es el
+  `agent_id` grabado en el token por el ADMIN—, así que es **un token por agente**, no uno por
+  proyecto. Además, `front-plan.py` cierra tres fallos silenciosos: `layer` normalizado (el bundle
+  del grafo emite `FOUNDATIONAL` y la exclusión foundational-first podía no disparar),
+  **fail-closed** sin `files_scope` declarado, y serialización de los pares con camino en el DAG de
+  `depends_on`.
+- ✅ **v0.15.0 — el arnés propone el re-sync de su grafo** (EP-OR-17) — el grafo del hub se sembraba
+  una vez, con el import de admin de `/build:onboard`, y ahí se quedaba: las épicas que discovery
+  escribía después no tenían por dónde entrar y **todos** los eventos de un slice cuya épica falta
+  rebotan. Comando **`/build:graph-sync`** (+ `--check`) y subcomandos `graph-sync`/
+  `graph-sync-status`: el arnés construye el bundle desde los docs, el hub calcula el delta y un
+  **humano aprueba** en la consola — nada se aplica sin esa aprobación; tras ella, las historias
+  nuevas entran solas al reparto del claim. `client_event_id` determinista para que el reintento
+  deduplique en vez de dejar dos propuestas del mismo grafo esperando. En el camino, dos defectos
+  vivos desde antes: el `409` se leía en la raíz y con un nombre que no existe en el backend (el
+  claim no reintentaba ante grafo rancio ni ante drift), y el **espejo del modo `dual` era un 422 el
+  100 % de las veces** (mandaba un cuerpo que el contrato no tiene). Total: **14 comandos
+  `/build:*`**.
+- ✅ **v0.14.0 — contexto vivo, épicas propuestas y versión de grafo** (#61, #62, #63) —
   tres capacidades del cliente del runtime que componen entre sí. **(1)** El daemon de heartbeat
   refresca `GET /agent/context` con **cadencia propia** (`runtime.context_refresh_s`, default 45 s,
   `0` la desactiva): antes la caché se hidrataba al arrancar la sesión y en cada `claim` —y el

package/VERSION

@@ -1 +1 @@
-0.14.2
+0.16.0

package/agents/build/build-orchestrator.md

@@ -23,6 +23,9 @@ Eres el único que reporta gates y transiciona fases; los reviewers solo emiten
 ## Coexistencia con el front paralelo (outer-loop)
 Si hay un front paralelo abierto, el paralelismo lo gobierna la skill
 `managing-parallel-front`; cada worktree corre su propio inner loop con `active_slice` singular.
+En modo `runtime`, cada worktree es además un **agente propio** con su token del ADMIN (alta con
+`slice-ops.sh register`): si un árbol no está dado de alta, sus escrituras salen con `rc 9` porque
+estaría operando con la identidad del clon principal — eso se arregla registrando, no reintentando.
 **Regla de drenado:** si se necesita abrir una épica `layer=foundational`, primero pon
 `parallel_front.status="draining"` (termina las en curso, no admite nuevas) y espera a cerrarlo.
 

package/commands/build/front.md

@@ -1,6 +1,6 @@
 ---
 name: "BUILD: Front"
-description: Prepara y coordina un front paralelo de épicas NO fundacionales y disjuntas en archivos, cada una en su worktree/rama/PR con su propio agente registrado. Delega en la skill managing-parallel-front (selección disjunta local vía scripts/lib/front-plan.py, worktrees, merge en orden con re-smoke reportado por cada worktree). Planificar, abrir, drenar y cerrar el front son actos humanos en la consola.
+description: Prepara y coordina un front paralelo de épicas NO fundacionales y disjuntas en archivos, cada una en su worktree/rama/PR con su propio agente registrado (un token por agente, alta con slice-ops.sh register). Delega en la skill managing-parallel-front (selección disjunta local vía scripts/lib/front-plan.py, worktrees, merge en orden con re-smoke reportado por cada worktree). Planificar, abrir, drenar y cerrar el front son actos humanos en la consola.
 category: Workflow
 tags: [build-harness, outer-loop, front-paralelo, trycore]
 ---
@@ -10,11 +10,15 @@ tags: [build-harness, outer-loop, front-paralelo, trycore]
 Delega en la skill **managing-parallel-front**. Resumen:
 1. Verifica precondiciones (scaffold confirmado; sin épica foundational abierta) con
    `bash .claude/hooks/build/slice-ops.sh status`.
-2. Reúne candidatas no fundacionales listas (DoR pasado) con `layer` y `files_scope`.
+2. Reúne candidatas no fundacionales listas (DoR pasado) con `layer`, `files_scope` y
+   `depends_on`. Sin `files_scope` declarado la épica **no es candidata** (se serializa).
 3. Propón el conjunto disjunto y el `merge_order` (`scripts/lib/front-plan.py`, local) y
    **preséntaselo a una persona**: abrir el front es acto de gobierno, en la consola del hub.
-4. Un worktree por épica aprobada, cada uno registrado como **agente propio**
-   (`trycore-build init` con el mismo token de proyecto); construye con `/build:slice`.
+4. Un worktree por épica aprobada, cada uno dado de alta como **agente propio** con **su
+   propio token** emitido por el ADMIN: `trycore-build init` (sin `--runtime-token`) y luego
+   `bash .claude/hooks/build/slice-ops.sh register` (pide el token por stdin). Sin ese alta,
+   toda escritura desde el worktree sale con **rc 9**: estaría suplantando al clon principal.
+   Después, construye con `/build:slice`.
 5. Tras cada merge, re-smoke y reporte desde el worktree:
    `bash .claude/hooks/build/release-ops.sh front-integration <front_id> --merge-status … --resmoke …`.
 

package/commands/build/graph-sync.md

@@ -0,0 +1,129 @@
+---
+name: "BUILD: Graph Sync"
+description: Propone al hub el re-sync del grafo del proyecto desde los docs de discovery (epicas.md + HU-*.md). El hub calcula el delta y un humano lo aprueba en la consola; nada se aplica sin esa aprobación. Con --check no propone nada: solo consulta el veredicto de las propuestas ya enviadas. Adaptador delgado sobre slice-ops.sh graph-sync/graph-sync-status.
+category: Workflow
+tags: [build-harness, runtime, backlog, grafo, trycore]
+---
+
+# /build:graph-sync — re-sincronizar el grafo del hub con los docs (la aprobación es humana)
+
+El grafo del hub se siembra una vez, con el **import de admin** de `/build:onboard`. A partir de
+ahí discovery sigue escribiendo: épicas nuevas en `docs/03-backlog/epicas.md`, historias nuevas
+en las `HU-*.md`. Sin este comando, nada de eso llega al hub — y el síntoma es concreto: **todos
+los eventos de un slice cuya épica no está en el grafo rebotan** con «la épica no existe en el
+grafo del proyecto».
+
+**Regla dura**: el arnés **propone**, un humano **aprueba**. Este comando no muta el grafo; deja
+una propuesta con su delta calculado, y hasta que alguien la apruebe en la consola del hub no
+cambia ni una arista.
+
+**Entrada (opcional):** `--check`. Sin argumento, el comando **propone** el re-sync.
+
+## Despacho por argumento (léelo antes que nada)
+
+- **Con `--check`** → ve directo al **§0** y luego **salta al §4**. `--check` es una consulta de
+  **solo lectura**: no construyas ningún bundle y no propongas nada (§1–§3 no se ejecutan, ni
+  siquiera "por si acaso"). Proponer aquí crearía una segunda propuesta del mismo grafo cada vez
+  que alguien comprueba el estado.
+- **Sin argumento** → §0 → §1 → §2 → §3. El §4 se recorre después, cuando el humano haya
+  resuelto la propuesta en la consola (normalmente en otra invocación, con `--check`).
+
+## 0. Precondición
+
+```bash
+bash .claude/hooks/build/slice-ops.sh mode
+```
+
+- `legacy` → **STOP**: el grafo vive en los documentos y no hay hub con el que sincronizarlo.
+- `dual` → **STOP** para proponer, pero aquí **sí hay hub**: el fichero local es el primario y el
+  grafo entra por el import de admin. No lo diagnostiques como un problema de conexión. El
+  `--dry-run` del §2 sí funciona: úsalo para revisar el grafo antes del corte a `runtime`.
+- `runtime` → sigue.
+
+## 1. Construir el JSON de épicas desde los docs
+
+Lee `docs/03-backlog/epicas.md` y las `HU-*.md` y escribe un fichero temporal con **todo** el
+backlog vigente, no solo lo nuevo: el hub compara el bundle contra su grafo y calcula el delta,
+así que mandar un subconjunto no borra nada pero tampoco describe el proyecto.
+
+```json
+{"project_ref": "<nombre del proyecto>",
+ "epics": [{"code": "EP-001", "title": "…", "layer": "foundational",
+            "files_scope": ["src/core/**"], "depends_on": [],
+            "stories": [{"id": "HU-001", "title": "…"}]},
+           {"code": "EP-002", "title": "…", "layer": "business",
+            "files_scope": ["src/pagos/**"], "depends_on": ["EP-001"],
+            "stories": [{"id": "HU-011", "title": "…"}]}],
+ "release_lines": [{"id": "R1-mvp", "epics": ["EP-001", "EP-002"]}]}
+```
+
+Es el **mismo formato** que la fase de grafo de `/build:onboard`: si ya lo generaste allí,
+reutilízalo. A diferencia de las propuestas de épica, aquí el `code` **sí** viaja: el re-sync es
+la puerta de lo que ya tiene identidad en los documentos.
+
+**No inventes ninguna épica ni ninguna capa.** Si un dato falta en los docs, falta en el grafo:
+se corrige en discovery, no aquí.
+
+## 2. Revisar antes de proponer (`--dry-run`)
+
+```bash
+bash .claude/hooks/build/slice-ops.sh graph-sync \
+  --file /tmp/epics.json --from-docs docs/03-backlog/epicas.md --dry-run
+```
+
+**Pasa siempre `--from-docs`**: relee el campo `**Depende de**` de cada sección de épica y une
+ese grafo al del JSON. Es la única lectura fiable de las dependencias, que la metodología escribe
+como prosa; sin él, un backlog lleno de dependencias sale con `depends_on: []` y el Lienzo del
+hub queda sin una sola arista.
+
+`--dry-run` imprime el bundle ya proyectado al contrato del hub y **no envía nada**. Revísalo con
+el usuario: número de épicas, capas, aristas.
+
+Un `rc 2` aquí no es un fallo del comando: es el bundle incumpliendo el contrato del hub, con un
+motivo por línea que nombra la épica y el campo (`layer` ausente, historia sin `code`, techos
+excedidos). Corrígelo **en los docs de discovery** y repite. El hub rechaza el grafo entero ante
+una sola épica mal formada, así que estas comprobaciones se hacen aquí para no gastar un viaje.
+
+## 3. Proponer
+
+```bash
+bash .claude/hooks/build/slice-ops.sh graph-sync \
+  --file /tmp/epics.json --from-docs docs/03-backlog/epicas.md
+```
+
+| rc | Significado | Qué haces |
+|---|---|---|
+| `0` | Propuesta creada (el comando enseña el `id` y el delta), **o** el grafo ya estaba al día | Si hay `id`, dile al usuario que queda **pendiente de aprobación humana** en la consola. Si dice «ya está al día», no hay nada que hacer |
+| `5` | Encolada, aún sin entregar (sin conexión, o el daemon estaba drenando la cola) | Avisa de que se despachará sola y de que `--check` la sigue |
+| `6` | El hub la rechazó (422 con el motivo, 404, o falta `project_id`) | Muestra la razón; **no** reintentes en bucle |
+| `2` | El bundle no cumple el contrato, o falta `--file` | Corrige lo que indique el mensaje, en los docs |
+| `3` | `legacy`/`dual` | Vuelve al paso 0 |
+
+Un **409 de grafo rancio** no lo verás como error: el comando refresca el contexto y reintenta
+una vez con el mismo identificador, para que el hub deduplique en vez de crear una segunda
+propuesta del mismo grafo.
+
+## 4. Después de la decisión — `/build:graph-sync --check`
+
+**Aquí aterriza `--check`.** Es mecánico y de solo lectura:
+
+```bash
+bash .claude/hooks/build/slice-ops.sh graph-sync-status
+```
+
+- `APPROVED` (con la versión de grafo aplicada) → **no hay nada más que hacer**. Las historias
+  nuevas entran solas al reparto del claim: no hay que reclamar de otra forma ni tocar el estado.
+- `REJECTED` (con el motivo que escribió el ADMIN) → **léeselo al usuario**. El motivo existe
+  precisamente para que esta terminal lo lea. Corrige en discovery y vuelve a proponer.
+- `PROPOSED` → sigue esperando decisión humana. No propongas otra vez.
+- `QUEUED` → aún sin despachar; el daemon de heartbeat la lleva.
+
+## Guardrails
+
+- El arnés **propone**; la aprobación es humana (gobierno, METODOLOGIA §10 regla 8). Ni el
+  modelo ni el arnés aprueban un cambio de grafo.
+- **No edites `docs/03-backlog/epicas.md` para «arreglar» el bundle.** El fichero es la fuente;
+  si el bundle no cumple, lo que está mal es la fuente, y se corrige con el usuario delante.
+- **No propongas dos veces sin mirar `--check`.** Dos propuestas del mismo grafo esperando
+  aprobación es exactamente el ruido que este carril evita.
+- Un `REJECTED` **no** se resuelve reintentando: se resuelve leyendo el motivo.

package/dist/commands/init.js

@@ -230,6 +230,9 @@ function syncGitignoreBlock(targetDir, mode) {
         // sin esto, un consumidor los commitea por descuido.
         '.claude/state/epic-proposals.json',
         '.claude/state/graph-status.json',
+        // [EP-OR-17] El ledger del re-sync del grafo es lo mismo: el rastro local de una
+        // conversación con el hub, no estado del proyecto.
+        '.claude/state/graph-sync-proposals.json',
         // [Ronda final · C5] Estado del daemon de heartbeat (EP-OR-08-B): un pid y unos ppids
         // solo significan algo en LA máquina que los escribió. Commiteados, otro clon recibe un
         // pidfile ajeno que el relanzamiento da por bueno hasta el `kill -0`, y un

package/docs/commands.md

@@ -121,7 +121,7 @@ El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y
 
 | Slash command | Propósito |
 |---|---|
-| `/build:front` | Abre y coordina un **front paralelo** de épicas NO fundacionales y disjuntas en archivos, cada una en su propio worktree/rama/PR. Delega en la skill `managing-parallel-front`: verifica precondiciones (scaffold confirmado, sin épica foundational abierta), selecciona el conjunto disjunto (`scripts/lib/front-plan.py`) y mergea en orden con re-smoke. Úsalo solo con ≥2 épicas no fundacionales disjuntas listas; para una sola épica, usa `/build:slice`. |
+| `/build:front` | Abre y coordina un **front paralelo** de épicas NO fundacionales y disjuntas en archivos, cada una en su propio worktree/rama/PR. Delega en la skill `managing-parallel-front`: verifica precondiciones (scaffold confirmado, sin épica foundational abierta), selecciona el conjunto disjunto (`scripts/lib/front-plan.py`, que serializa también las candidatas sin `files_scope` declarado y los pares con camino en el DAG de `depends_on`) y mergea en orden con re-smoke. En modo `runtime`, **cada worktree se da de alta como agente propio** con su token del ADMIN (`slice-ops.sh register`): sin ese alta, toda escritura desde el árbol sale con `rc 9` porque estaría firmando con la identidad del clon principal. Úsalo solo con ≥2 épicas no fundacionales disjuntas listas; para una sola épica, usa `/build:slice`. |
 
 ### `/build:prototype` — prototipo HTML de referencia (fuente de diseño)
 
@@ -129,17 +129,26 @@ El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y
 |---|---|
 | `/build:prototype` | Genera o amplía el **prototipo HTML de referencia** (el `DESIGN_SOURCE`) en `docs/05-prototipo/` (`DESIGN.md` + `tokens.css` + `manifest.json` + un HTML autocontenido por pantalla). Adaptador delgado: **delega** en la skill `prototyping-screens`. Dos modos — **greenfield** (`/build:prototype`): inventario de pantallas desde PRD/mapa/historias → confirmación humana → dirección estética (manual de marca o 2-3 variantes a elección humana) → generación por lotes con auto-verificación visual; **feature** (`/build:prototype <épica>`): pantallas nuevas coherentes con el UX/UI **ya implementado**, con **precondición dura** (app corriendo + MCP de inspección de UI: extrae CSS computado real, screenshots en 3 viewports y estructura; sin degradación estática). Es **outer-loop** (antes de abrir slices). **La skill genera; el humano aprueba**: las pantallas nacen `borrador`, solo las `aprobada` son fuente de verdad (las lee `ux-fidelity-reviewer` vía `manifest.json`) y `design_source.confirmed` sigue siendo humano. |
 
-### `/build:claim`, `/build:status`, `/build:escalate`, `/build:epic` — superficie de agente del runtime (beta, opt-in)
+### `/build:claim`, `/build:status`, `/build:escalate`, `/build:epic`, `/build:graph-sync` — superficie de agente del runtime (beta, opt-in)
 
 Adaptadores delgados sobre `slice-ops.sh`; en modo `legacy` (default) devuelven `rc 3` y remiten al
 protocolo del fichero (`/build:slice`) — no rompen el flujo normal si el proyecto no está migrado.
 
+> **Un árbol de trabajo, un agente.** Estos comandos operan con la identidad de
+> `.claude/state/runtime.credentials`. Ese fichero está en `.gitignore` y **no viaja** a un
+> `git worktree`, así que un árbol nuevo hereda la del clon principal y lo suplantaría: por eso
+> toda **escritura** desde un árbol sin dar de alta aborta con **`rc 9`**. El alta no es un slash
+> command —pide el token por stdin y necesita un terminal humano—: se corre una vez por worktree
+> con `bash .claude/hooks/build/slice-ops.sh register`. Ver
+> [guía runtime → «Varios agentes en la misma máquina»](runtime/guia-modo-dual-y-migracion.md).
+
 | Slash command | Propósito |
 |---|---|
 | `/build:claim` | Pide la siguiente tarea al runtime (`POST /tasks/next`): sincroniza contexto, reporta hashes locales (detección de drift) y reclama por lease. Si trae `CHECKPOINT`, continúa desde ahí — **nunca reinicia** un slice de otro agente. **No acepta épica dirigida**: el hub reparte por orden de cola y `claim --epic` falla explícito con `rc 2` (issue #39 — el servidor ignoraba el `epic_code` y entregaba otra épica como si fuera la pedida, dejando un lease huérfano). |
 | `/build:status` | Informe de solo lectura: modo, slice activo, gates, wiring failing, versión de contexto, lease y cola de eventos pendientes. Nunca transiciona nada. |
 | `/build:escalate <razón>` | Registra un bloqueo en el runtime (`escalation_raised`) y devuelve la decisión a un humano — recortar, diferir o desbloquear **nunca** lo decide el modelo (mismo principio que la regla 8 de METODOLOGIA §10). |
 | `/build:epic` | Propone una épica **incremental de construcción** al hub y, tras la aprobación humana, la escribe en `docs/03-backlog/epicas.md` con el `EP-XXX` que asignó el hub (`/build:epic --check`). El agente **no elige** el código: elegirlo mirando el fichero es lo que hace colisionar a dos terminales. La descomposición inicial del backlog sigue siendo de discovery. |
+| `/build:graph-sync` | Propone al hub el **re-sync del grafo** desde los docs de discovery (`epicas.md` + `HU-*.md`): el hub calcula el delta y un humano lo aprueba en la consola — **nada se aplica** sin esa aprobación. Existe porque el grafo del hub se sembraba una vez, con el import de admin, y todo lo que discovery escribía después no tenía por dónde entrar: el síntoma es que **cada evento de un slice cuya épica falta en el grafo rebota**. Con `--check` solo consulta el veredicto (`APPROVED` con la versión aplicada, o `REJECTED` con el motivo que escribió el ADMIN). Tras la aprobación no hay nada que hacer: las historias nuevas entran solas al reparto del claim. |
 
 ---
 

package/docs/getting-started.md

@@ -56,7 +56,7 @@ npm i -g @fission-ai/openspec @trycore/spec-build-harness
 
 ## 2 · `trycore-build init` (terminal)
 
-Desde la raíz de tu proyecto. Es **idempotente** (re-correrlo es seguro) y siembra: **14 agentes**, **16 skills** (`building-a-slice`, `building-a-micro-change`, `releasing-a-version`, `managing-parallel-front`, `setup-architecture`, `prototyping-screens` + 10 `openspec-*`), **10 comandos `/opsx:*`** + **13 comandos `/build:*`** (`onboard`, `reflect`, `architect`, `prototype`, `slice`, `release`, `work`, `resume`, `front` + `claim`, `status`, `escalate`, `epic`, que son la superficie del modo runtime), **19 hooks**, el estado vacío `.claude/state/build-state.json` (gitignored, nunca se sobreescribe) y el bloque `<!-- BEGIN trycore-build-harness -->` en tu `CLAUDE.md` con `{{placeholders}}` sin resolver.
+Desde la raíz de tu proyecto. Es **idempotente** (re-correrlo es seguro) y siembra: **14 agentes**, **16 skills** (`building-a-slice`, `building-a-micro-change`, `releasing-a-version`, `managing-parallel-front`, `setup-architecture`, `prototyping-screens` + 10 `openspec-*`), **10 comandos `/opsx:*`** + **14 comandos `/build:*`** (`onboard`, `reflect`, `architect`, `prototype`, `slice`, `release`, `work`, `resume`, `front` + `claim`, `status`, `escalate`, `epic`, `graph-sync`, que son la superficie del modo runtime), **19 hooks**, el estado vacío `.claude/state/build-state.json` (gitignored, nunca se sobreescribe) y el bloque `<!-- BEGIN trycore-build-harness -->` en tu `CLAUDE.md` con `{{placeholders}}` sin resolver.
 
 > **¿Ya tenías el arnés instalado?** Entonces esto es un `update`, no un `init` — el CLI lo detecta solo por `.claude/.build-harness-version`. Corre `npm i -g @trycore/spec-build-harness@latest` y luego `trycore-build update`; **no** repitas `/build:onboard`, tu dominio ya está parametrizado. La tabla «¿Qué camino me toca?» de [`INSTALL.md`](../INSTALL.md) cubre los cuatro casos.
 

package/docs/hooks.md

@@ -1,6 +1,6 @@
 # Hooks del arnés de construcción
 
-Este documento describe los **19 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 los helpers compartidos `lib/state-io.sh`, `lib/config.sh`, `lib/runtime-client.sh`, `lib/runtime-ops.sh`, `lib/agent-context.sh`, `lib/projection.sh`) 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 **19 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 los helpers compartidos `lib/state-io.sh`, `lib/config.sh`, `lib/runtime-client.sh`, `lib/runtime-ops.sh`, `lib/agent-context.sh`, `lib/projection.sh`, `lib/harness-meta.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 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.
 
@@ -41,7 +41,9 @@ Los hooks son el sistema nervioso del arnés: vigilan GitFlow, el stack declarad
 >
 > `lib/state-io.sh` (`legacy`), `lib/config.sh` (`runtime.mode`, umbrales), `lib/runtime-client.sh`
 > (cliente HTTP + cola offline), `lib/runtime-ops.sh` (helpers de `slice-ops.sh`/`release-ops.sh`),
-> `lib/agent-context.sh` (normaliza `GET /agent/context`) y `lib/projection.sh` (lee esa caché,
+> `lib/agent-context.sh` (normaliza `GET /agent/context`), `lib/harness-meta.sh` (versión del arnés
+> y catálogo de asset types, compartidos por el registro de sesión y el alta de un worktree) y
+> `lib/projection.sh` (lee esa caché,
 > sin red) **no son hooks**: son los helpers compartidos que los scripts de arriba `source`an.
 
 ---

package/docs/runtime/guia-modo-dual-y-migracion.md

@@ -120,12 +120,13 @@ arman peticiones a mano. En `dual`, cada transición también se **espeja** al s
 identidad del fichero (que sigue mandando). Si el espejo falla (red caída, servidor rechaza), el
 trabajo local **nunca se bloquea** — se avisa y queda como discrepancia para el comparador.
 
-`slice-ops.sh` tiene **17 subcomandos** (los conducen las skills; los listamos para que puedas
-leer un log o depurar, no para que los teclees):
+`slice-ops.sh` tiene **20 subcomandos** (los conducen las skills; los listamos para que puedas
+leer un log o depurar, no para que los teclees — `register` es la excepción: ese lo tecleas tú):
 
 | Subcomando | Para qué |
 |---|---|
 | `mode` | imprime `legacy`\|`dual`\|`runtime` |
+| `register` | da de alta **este árbol de trabajo** como agente propio, con su token (lo pide por stdin). Solo hace falta en un `git worktree` — ver «Varios agentes en la misma máquina» |
 | `claim` | reclama trabajo (el hub reparte por orden de cola; sin épica dirigida) |
 | `next-step` | deriva la siguiente acción desde la caché de proyección |
 | `phase` | reporta la fase del pipeline (emite la cadena que falte; idempotente) |
@@ -136,12 +137,87 @@ leer un log o depurar, no para que los teclees):
 | `fact` | reporta un hecho de proyecto confirmado |
 | `propose-asset` | propone un documento al plano de contexto (lo publica un ADMIN) |
 | `propose-epic` · `epic-status` · `epic-writeback` | proponen una épica, consultan su estado y proyectan la aprobada a `epicas.md` |
+| `graph-sync` · `graph-sync-status` | proponen el re-sync del grafo desde los docs de discovery y leen el veredicto humano (solo en `runtime`) |
 | `status` · `escalate` | informe local del agente y registro de un bloqueo |
 
 Del lado release, `release-ops.sh` añade `verdict` y `front-integration`.
 
 **Códigos de salida** (sobre estos ramifica la prosa de las skills): `0` ok · `2` uso · `3` legacy ·
-`4` sin slice · `5` offline · `6` rechazado · `7` sin trabajo.
+`4` sin slice · `5` offline · `6` rechazado · `7` sin trabajo · `8` tipo no espejable ·
+`9` identidad heredada (este árbol no está dado de alta — ver abajo).
+
+### Varios agentes en la misma máquina (0.16.0)
+
+Si abres un `git worktree` por épica para construir en paralelo (`/build:front`), **cada árbol
+necesita su propio token de agente**, emitido por el ADMIN para él. No es burocracia:
+
+- El hub **no crea identidad** al registrar. El `agent_key` es el `agent_id` que va grabado en el
+  token, así que dos árboles con el mismo token son **un solo agente** — y el segundo `claim` te
+  devuelve el slice que ya tiene reclamado el primero.
+- El estado del arnés está en `.gitignore` y **no viaja** al worktree. Sin credenciales propias, el
+  árbol nuevo hereda las del clon principal y **suplanta** a ese agente: reclamaría con su
+  `agent_key`, reportaría los hashes del árbol equivocado y compartiría su heartbeat.
+
+Por eso, en un árbol sin dar de alta, **toda escritura** (`claim`, `phase`, `gate`, `submit`,
+`archive`, `wiring`, `progress`, `checkpoint`, `fact`, `propose-*`, `graph-sync`, `escalate` y
+`release-ops.sh front-integration`) aborta con `rc 9` **antes de tocar la red**. Las lecturas siguen
+funcionando —son el diagnóstico de ese árbol— y `status` lo dice en su primera línea:
+
+```
+identidad:    ⚠ HEREDADA del clon principal (/ruta/al/clon) — solo lectura
+```
+
+El alta es un comando, en el terminal, una vez por worktree:
+
+```bash
+cd .wt/ep-003
+trycore-build init                                   # tiende .claude/ (sin --runtime-token)
+bash .claude/hooks/build/slice-ops.sh register       # pide el token por stdin
+```
+
+`register` **no acepta el token por argumento** (`--token` sale con `rc 2`): en argv quedaría en el
+historial del shell y en `ps`. Por lo mismo lo corres tú y no un hook — las tool calls no tienen
+TTY. Antes de tocar la red siembra el fichero local (si no, el registro habría escrito sobre las
+credenciales del clon principal), y después verifica contra el hub que el `agent_key` obtenido
+**difiere** del suyo; si coincide, lo rechaza y te dice que pidas al ADMIN un token con `agent_id`
+distinto. Ante cualquier fallo revierte: el árbol queda con identidad propia y verificada, o
+exactamente como estaba. El fichero del clon principal no se toca nunca.
+
+Para rotar el token de un árbol ya registrado: `register --force`.
+
+### Qué espeja el modo `dual` — y qué no (0.15.0)
+
+El espejo cubre la **enumeración normativa** del hub, ni más ni menos: `slice_opened`,
+`phase_advanced`, `phase_reverted`, `gate_verdict`, `wiring_item_updated`,
+`wiring_checklist_seeded`, `checkpoint_recorded`, `progress_noted` y `handoff_recorded`. Todo eso
+viaja como `{"transitions": [{client_event_id, epic_code, event_type, payload}]}`, con la épica
+del `build-state.json` local en el **sobre**, y el hub responde un reporte **por elemento** cuyo
+motivo de rechazo el cliente te enseña tal cual.
+
+Lo que **no** se espeja, y por qué — son huecos del **hub**, no del arnés, y el cliente los corta
+en local (`rc 8`) en vez de gastar una llamada para recibir un rechazo:
+
+| No espejable | Motivo |
+|---|---|
+| `slice_escalated` · `slice_archived` · `slice_submitted` | Existen en el catálogo del hub pero no heredan de `_TransicionDeEspejo`: la ingesta espejo no los acepta. Una discrepancia dual sigue siendo **visible** donde la lees —el aviso del hook `Stop`—, pero no queda registrada en el hub. |
+| `release_verdict_reported` · `front_integration_reported` | No existen en el catálogo del hub, y la superficie síncrona de los veredictos de release es de **gobierno humano**. En `dual` el veredicto se anota en local y el comando te lo dice con esas palabras; quedará reflejado al pasar a `runtime`. |
+
+Cerrar estos huecos requiere un tipo nuevo en el catálogo del hub con su rama de reducer: es
+trabajo hub-side. Mientras tanto el arnés lo **nombra** en vez de fallar en silencio.
+
+### Cuando el hub no conoce tu épica (0.15.0)
+
+Si el espejo rechaza con «la épica no existe en el grafo del proyecto», el grafo del hub se quedó
+en la foto del import inicial. La salida es proponer el re-sync:
+
+```bash
+/build:graph-sync            # construye el bundle desde los docs y lo propone
+/build:graph-sync --check    # lee el veredicto: APPROVED, o REJECTED con su motivo
+```
+
+En `dual` el carril de propuesta no opera (el fichero es primario y el grafo entra por el import
+de admin), pero `slice-ops.sh graph-sync --file epics.json --dry-run` **sí** funciona: úsalo para
+revisar el grafo antes del corte a `runtime`.
 
 ### Lo que aportó la 0.14.0