feat: cerebro reactivo del meta-orquestador (flow 0012, fase 2)

Primitivas (python/functions/infra):
- drain_fleet_events: consume la cola del watcher (~/.claude/fleet/
  events.jsonl) desde un cursor, agrupa por clasificacion, marca
  urgentes. 7 tests.
- set_dod_contract: escribe el DoD-contrato fijo (dod_contract/dod_status)
  en el goal.json de un agente sin pisar el resto (escritura atomica).
  5 tests.

Skill /orquestador evolucionado (sin romper lo existente): vigila la
flota por su DoD (no por 'esta vivo'). Nueva seccion 'Consumo de la cola
de la flota': DoD-contrato obligatorio al lanzar, drenar la cola,
politicas por clasificacion (RECLAMA escala / DICE_TERMINADO verifica /
ESTANCADO nudge / MAL_LANZADO re-DoD), verificador independiente del
ejecutor (lee el report vs dod_contract), splitter con tope de fan-out,
y cadencia (drain al actuar + heartbeat).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

python/functions/infra/drain_fleet_events.md

@@ -0,0 +1,82 @@
+---
+name: drain_fleet_events
+kind: function
+lang: py
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "def drain_fleet_events(events_path: str | None = None, cursor_path: str | None = None, advance: bool = True) -> dict"
+description: "Drena la cola JSONL de eventos de la flota desde un cursor persistente. Lee los eventos nuevos (desde la linea del cursor hasta el final), los parsea saltando lineas en blanco o JSON invalido, los agrupa por su campo `to` (RECLAMA, MAL_LANZADO, DICE_TERMINADO, ESTANCADO, TRABAJANDO, GONE), aisla los urgentes y avanza el cursor para no reprocesar. Pensado para que el orquestador-Claude de flota consuma eventos nuevos cada vez que despierta."
+tags: [fleet, claude-fleet, jsonl, cursor, queue, drain, watcher, orchestrator]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: ["os", "json"]
+params:
+  - name: events_path
+    desc: "ruta a la cola JSONL append-only de eventos. Default: ~/.claude/fleet/events.jsonl"
+  - name: cursor_path
+    desc: "ruta al archivo de cursor (numero de lineas ya procesadas, entero en texto plano). Default: ~/.claude/fleet/cursor"
+  - name: advance
+    desc: "si True avanza el cursor al total de lineas para no reprocesar; si False hace peek sin mover el cursor (inspeccion)"
+output: "dict con total_new (int), events (lista de eventos nuevos en orden), by_classification (dict agrupado por campo `to`), urgent (lista de eventos con urgent==True), cursor (nueva posicion) y opcionalmente reset==True si la cola estaba truncada/rotada y el cursor se reinicio a 0"
+tested: true
+tests:
+  - "cola con eventos cursor cero devuelve todos y avanza"
+  - "segunda llamada cero nuevos"
+  - "advance false no mueve cursor"
+  - "archivo ausente vacio sin crash"
+  - "json invalido se salta"
+  - "agrupacion por to y urgent"
+  - "cursor mayor que lineas reinicia"
+test_file_path: "python/functions/infra/drain_fleet_events_test.py"
+file_path: "python/functions/infra/drain_fleet_events.py"
+---
+
+## Ejemplo
+
+```python
+from infra.drain_fleet_events import drain_fleet_events
+
+# El orquestador despierta y consume los eventos nuevos de la flota.
+drained = drain_fleet_events()  # usa ~/.claude/fleet/events.jsonl y ~/.claude/fleet/cursor
+
+print(f"{drained['total_new']} eventos nuevos")
+for ev in drained["by_classification"].get("RECLAMA", []):
+    print("RECLAMA:", ev["session_id"], ev["goal"])
+
+# Eventos urgentes primero.
+for ev in drained["urgent"]:
+    print("URGENTE:", ev["to"], ev["session_id"])
+
+# Peek sin avanzar el cursor (no consume): util para inspeccionar antes de actuar.
+peek = drain_fleet_events(advance=False)
+```
+
+## Cuando usarla
+
+Usala en el orquestador-Claude de flota cada vez que despierta y necesita ver
+las transiciones de estado producidas DESDE la ultima vez sin reprocesar las ya
+vistas. Tambien para diagnostico con `advance=False` cuando quieres mirar la
+cola sin consumirla.
+
+## Gotchas
+
+- **Impura**: lee la cola JSONL del disco y, con `advance=True`, sobrescribe el
+  archivo de cursor. Pasa `advance=False` para peek puro sin efectos en cursor.
+- **Cursor por lineas, no por bytes**: el cursor cuenta lineas procesadas. Las
+  lineas en blanco e invalidas tambien avanzan el cursor (se cuentan en el
+  total de lineas) aunque no produzcan eventos, de modo que nunca se re-leen.
+- **Cola rotada/truncada**: si el cursor guardado es mayor que el numero de
+  lineas actual (la cola se trunco o rota), el drain reinicia desde 0 y marca
+  `reset: True` en el dict de salida — devolvera de nuevo todos los eventos
+  presentes. Diseñado asi para no perder eventos silenciosamente.
+- **JSON invalido o lineas en blanco**: se saltan sin romper el drain. Solo los
+  objetos JSON validos entran en `events`.
+- **`by_classification`**: agrupa por el campo `to`. Un evento sin campo `to`
+  (raro) entra en `events` pero no en ningun grupo.
+- **Fallo al persistir el cursor**: si `advance=True` pero no se puede escribir
+  el cursor (permisos, FS), el drain sigue siendo valido pero la proxima llamada
+  reprocesara estos eventos (at-least-once, no at-most-once).

python/functions/infra/drain_fleet_events.py

@@ -0,0 +1,129 @@
+"""Drena la cola JSONL de eventos de la flota desde un cursor persistente.
+
+El watcher embebido en fleetview escribe transiciones de estado de la flota a
+una cola JSONL append-only. El orquestador-Claude se despierta periodicamente y
+consume los eventos NUEVOS desde la ultima vez (sin reprocesar los ya vistos)
+agrupados por clasificacion para decidir.
+"""
+
+import json
+import os
+
+
+def drain_fleet_events(
+    events_path: str | None = None,
+    cursor_path: str | None = None,
+    advance: bool = True,
+) -> dict:
+    """Lee los eventos nuevos de la cola de la flota desde un cursor persistente.
+
+    El cursor es el numero de lineas ya procesadas (entero en texto plano).
+    Se leen las lineas desde la posicion del cursor hasta el final, se parsean
+    como JSON (saltando lineas en blanco o invalidas), se agrupan por el campo
+    `to` y se aisla la lista de eventos urgentes.
+
+    Args:
+        events_path: ruta a la cola JSONL. Default: ~/.claude/fleet/events.jsonl.
+        cursor_path: ruta al archivo de cursor. Default: ~/.claude/fleet/cursor.
+        advance: si True, escribe el nuevo cursor (= total de lineas) para no
+            reprocesar. Si False, no mueve el cursor (peek/inspeccion).
+
+    Returns:
+        dict con:
+          - total_new: numero de eventos nuevos validos parseados.
+          - events: lista de los eventos nuevos parseados, en orden.
+          - by_classification: dict que agrupa los eventos por su campo `to`.
+          - urgent: lista de eventos nuevos con urgent == True.
+          - cursor: nueva posicion del cursor (total de lineas de la cola).
+          - reset: presente y True solo si el cursor previo era mayor que el
+            numero de lineas de la cola (cola truncada/rotada): se reinicio
+            desde 0.
+    """
+    home = os.path.expanduser("~")
+    if events_path is None:
+        events_path = os.path.join(home, ".claude", "fleet", "events.jsonl")
+    if cursor_path is None:
+        cursor_path = os.path.join(home, ".claude", "fleet", "cursor")
+
+    # Cola ausente -> drain vacio sin crash.
+    if not os.path.exists(events_path):
+        return {
+            "total_new": 0,
+            "events": [],
+            "by_classification": {},
+            "urgent": [],
+            "cursor": 0,
+        }
+
+    # Leer el cursor previo (0 si no existe o es ilegible).
+    prev_cursor = 0
+    if os.path.exists(cursor_path):
+        try:
+            with open(cursor_path, "r", encoding="utf-8") as fh:
+                prev_cursor = int(fh.read().strip() or "0")
+        except (ValueError, OSError):
+            prev_cursor = 0
+    if prev_cursor < 0:
+        prev_cursor = 0
+
+    # Leer todas las lineas de la cola.
+    with open(events_path, "r", encoding="utf-8") as fh:
+        lines = fh.readlines()
+    total_lines = len(lines)
+
+    # Cursor mayor que el numero de lineas (cola truncada/rotada) -> reinicia.
+    reset = False
+    if prev_cursor > total_lines:
+        prev_cursor = 0
+        reset = True
+
+    new_lines = lines[prev_cursor:]
+
+    events: list[dict] = []
+    by_classification: dict[str, list[dict]] = {}
+    urgent: list[dict] = []
+
+    for raw in new_lines:
+        stripped = raw.strip()
+        if not stripped:
+            # Linea en blanco: saltar sin romper el drain.
+            continue
+        try:
+            event = json.loads(stripped)
+        except (json.JSONDecodeError, ValueError):
+            # JSON invalido: saltar sin romper el drain.
+            continue
+        if not isinstance(event, dict):
+            # No es un objeto JSON: saltar.
+            continue
+
+        events.append(event)
+
+        classification = event.get("to")
+        if classification is not None:
+            by_classification.setdefault(classification, []).append(event)
+
+        if event.get("urgent") is True:
+            urgent.append(event)
+
+    # Avanzar el cursor al total de lineas si advance=True.
+    if advance:
+        try:
+            os.makedirs(os.path.dirname(cursor_path) or ".", exist_ok=True)
+            with open(cursor_path, "w", encoding="utf-8") as fh:
+                fh.write(str(total_lines))
+        except OSError:
+            # No se pudo persistir el cursor: el drain sigue siendo valido,
+            # pero la proxima llamada reprocesara estos eventos.
+            pass
+
+    result = {
+        "total_new": len(events),
+        "events": events,
+        "by_classification": by_classification,
+        "urgent": urgent,
+        "cursor": total_lines,
+    }
+    if reset:
+        result["reset"] = True
+    return result

python/functions/infra/drain_fleet_events_test.py

@@ -0,0 +1,147 @@
+"""Tests para drain_fleet_events."""
+
+import json
+
+from drain_fleet_events import drain_fleet_events
+
+
+def _write_queue(path, events):
+    """Escribe una lista de eventos como JSONL en path."""
+    with open(path, "w", encoding="utf-8") as fh:
+        for ev in events:
+            fh.write(json.dumps(ev) + "\n")
+
+
+def _make_event(to, urgent=False, session_id="uuid", from_state="TRABAJANDO"):
+    return {
+        "ts": 1750445000000,
+        "session_id": session_id,
+        "pid": 1234,
+        "from": from_state,
+        "to": to,
+        "goal": "objetivo de prueba",
+        "phase": "preguntando",
+        "urgent": urgent,
+    }
+
+
+def test_cola_con_eventos_cursor_cero_devuelve_todos_y_avanza(tmp_path):
+    events_path = tmp_path / "events.jsonl"
+    cursor_path = tmp_path / "cursor"
+    eventos = [
+        _make_event("RECLAMA", urgent=True),
+        _make_event("DICE_TERMINADO"),
+        _make_event("ESTANCADO"),
+    ]
+    _write_queue(events_path, eventos)
+
+    result = drain_fleet_events(str(events_path), str(cursor_path))
+
+    assert result["total_new"] == 3
+    assert len(result["events"]) == 3
+    assert result["cursor"] == 3
+    assert "reset" not in result
+    # El cursor se persistio en disco.
+    assert cursor_path.read_text().strip() == "3"
+
+
+def test_segunda_llamada_cero_nuevos(tmp_path):
+    events_path = tmp_path / "events.jsonl"
+    cursor_path = tmp_path / "cursor"
+    _write_queue(events_path, [_make_event("RECLAMA"), _make_event("ESTANCADO")])
+
+    first = drain_fleet_events(str(events_path), str(cursor_path))
+    assert first["total_new"] == 2
+
+    second = drain_fleet_events(str(events_path), str(cursor_path))
+    assert second["total_new"] == 0
+    assert second["events"] == []
+    assert second["by_classification"] == {}
+    assert second["urgent"] == []
+    assert second["cursor"] == 2
+
+
+def test_advance_false_no_mueve_cursor(tmp_path):
+    events_path = tmp_path / "events.jsonl"
+    cursor_path = tmp_path / "cursor"
+    _write_queue(events_path, [_make_event("RECLAMA"), _make_event("GONE")])
+
+    peek1 = drain_fleet_events(str(events_path), str(cursor_path), advance=False)
+    assert peek1["total_new"] == 2
+    # No se creo archivo de cursor.
+    assert not cursor_path.exists()
+
+    # Una segunda lectura con peek vuelve a ver los mismos eventos.
+    peek2 = drain_fleet_events(str(events_path), str(cursor_path), advance=False)
+    assert peek2["total_new"] == 2
+    assert not cursor_path.exists()
+
+
+def test_archivo_ausente_vacio_sin_crash(tmp_path):
+    events_path = tmp_path / "no_existe.jsonl"
+    cursor_path = tmp_path / "cursor"
+
+    result = drain_fleet_events(str(events_path), str(cursor_path))
+
+    assert result["total_new"] == 0
+    assert result["events"] == []
+    assert result["by_classification"] == {}
+    assert result["urgent"] == []
+    assert result["cursor"] == 0
+
+
+def test_json_invalido_se_salta(tmp_path):
+    events_path = tmp_path / "events.jsonl"
+    cursor_path = tmp_path / "cursor"
+    with open(events_path, "w", encoding="utf-8") as fh:
+        fh.write(json.dumps(_make_event("RECLAMA")) + "\n")
+        fh.write("esto no es json valido {{{\n")
+        fh.write("\n")  # linea en blanco
+        fh.write("   \n")  # linea solo espacios
+        fh.write(json.dumps(_make_event("ESTANCADO")) + "\n")
+
+    result = drain_fleet_events(str(events_path), str(cursor_path))
+
+    # Solo 2 eventos validos, pero el cursor avanza al total de lineas (5).
+    assert result["total_new"] == 2
+    assert result["cursor"] == 5
+    assert [e["to"] for e in result["events"]] == ["RECLAMA", "ESTANCADO"]
+
+
+def test_agrupacion_por_to_y_urgent(tmp_path):
+    events_path = tmp_path / "events.jsonl"
+    cursor_path = tmp_path / "cursor"
+    eventos = [
+        _make_event("RECLAMA", urgent=True, session_id="a"),
+        _make_event("RECLAMA", urgent=False, session_id="b"),
+        _make_event("DICE_TERMINADO", urgent=False, session_id="c"),
+        _make_event("ESTANCADO", urgent=True, session_id="d"),
+    ]
+    _write_queue(events_path, eventos)
+
+    result = drain_fleet_events(str(events_path), str(cursor_path))
+
+    bc = result["by_classification"]
+    assert set(bc.keys()) == {"RECLAMA", "DICE_TERMINADO", "ESTANCADO"}
+    assert len(bc["RECLAMA"]) == 2
+    assert len(bc["DICE_TERMINADO"]) == 1
+    assert len(bc["ESTANCADO"]) == 1
+
+    assert len(result["urgent"]) == 2
+    urgent_sessions = {e["session_id"] for e in result["urgent"]}
+    assert urgent_sessions == {"a", "d"}
+
+
+def test_cursor_mayor_que_lineas_reinicia(tmp_path):
+    events_path = tmp_path / "events.jsonl"
+    cursor_path = tmp_path / "cursor"
+    # Cola con 2 lineas pero cursor apuntando a 99 (cola rotada/truncada).
+    _write_queue(events_path, [_make_event("RECLAMA"), _make_event("GONE")])
+    cursor_path.write_text("99")
+
+    result = drain_fleet_events(str(events_path), str(cursor_path))
+
+    assert result.get("reset") is True
+    assert result["total_new"] == 2
+    assert result["cursor"] == 2
+    assert cursor_path.read_text().strip() == "2"

python/functions/infra/set_dod_contract.md

@@ -0,0 +1,68 @@
+---
+name: set_dod_contract
+kind: function
+lang: py
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "def set_dod_contract(session_id: str, contract: str, status: str = 'pending', goals_dir: str | None = None) -> dict"
+description: "Escribe un DoD-contrato fijo y su estado en el sidecar goal.json de una sesion Claude (~/.claude/goals/<session_id>.json). Preserva TODOS los campos existentes (goal, phase, dod, history, prompts) y solo actualiza dod_contract y dod_status. Usado por el meta-orquestador de flota para fijar el criterio de aceptacion estable contra el que se evalua la terminacion de un agente. Escritura atomica via tmp + os.replace."
+tags: [fleet, claude-fleet, dod, goals, orchestrator, sidecar, json]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: ["os", "json"]
+params:
+  - name: session_id
+    desc: "ID de la sesion Claude; da nombre al archivo <session_id>.json dentro de goals_dir"
+  - name: contract
+    desc: "criterio de aceptacion estable (DoD-contrato) contra el que se evalua la terminacion del agente; no puede ser vacio"
+  - name: status
+    desc: "estado del contrato; uno de 'pending' | 'met' | 'failed' (default 'pending'); otro valor -> ValueError"
+  - name: goals_dir
+    desc: "directorio de sidecars de goal; default ~/.claude/goals; en tests apuntar a tmp_path para no tocar el real"
+output: "dict con session_id, path (ruta del goal.json escrito), dod_contract, dod_status y written=True"
+tested: true
+tests:
+  - "Escribe contrato en goal.json existente y preserva otros campos"
+  - "Crea el archivo si no existe"
+  - "Status invalido lanza ValueError sin escribir"
+  - "Contract vacio lanza ValueError sin escribir"
+  - "Re-escribir actualiza sin duplicar claves"
+test_file_path: "python/functions/infra/set_dod_contract_test.py"
+file_path: "python/functions/infra/set_dod_contract.py"
+---
+
+## Ejemplo
+
+```python
+from infra.set_dod_contract import set_dod_contract
+
+# El meta-orquestador fija el criterio de aceptacion al lanzar un agente.
+res = set_dod_contract(
+    session_id="a1b2c3d4-5678-90ab-cdef-1234567890ab",
+    contract="Los tests de python/functions/infra/ pasan en verde y fn doctor uses-functions no reporta drift",
+    status="pending",
+)
+print(res)
+# {'session_id': 'a1b2c3d4-...', 'path': '/home/enmanuel/.claude/goals/a1b2c3d4-....json',
+#  'dod_contract': '...', 'dod_status': 'pending', 'written': True}
+
+# Mas tarde, al evaluar la terminacion: marcar el contrato cumplido (preserva goal/phase/dod).
+set_dod_contract("a1b2c3d4-5678-90ab-cdef-1234567890ab", res["dod_contract"], status="met")
+```
+
+## Cuando usarla
+
+Usala cuando el meta-orquestador de flota lance un agente y necesite fijar el DoD-contrato estable, y cada vez que reevalue la terminacion para mover `dod_status` a `met` o `failed`. Es la unica via correcta para tocar `dod_contract`/`dod_status` sin pisar el resto del sidecar goal.json.
+
+## Gotchas
+
+- El hook GOAL-TRACKER reescribe la clave `dod` del goal.json (el DoD de trabajo, volatil) en cada turno, pero NO debe tocar `dod_contract` ni `dod_status` (el contrato FIJO de aceptacion). Esta funcion solo escribe esas dos claves y preserva `dod` tal cual la dejo el hook.
+- `status` solo acepta "pending" | "met" | "failed". Cualquier otro valor lanza ValueError ANTES de escribir: el archivo en disco queda intacto.
+- `contract` vacio o solo whitespace lanza ValueError sin escribir.
+- Escritura atomica (tmp + os.fsync + os.replace): si el proceso muere a mitad, el goal.json original no se corrompe.
+- Si el goal.json existente es JSON corrupto o ilegible, se parte de un dict vacio (no se aborta) — se pierde el contenido viejo ilegible pero se preserva el contrato nuevo. Es deliberado: un sidecar ya roto no debe bloquear al orquestador.
+- `goals_dir` default es `~/.claude/goals` (real). En tests SIEMPRE pasar `goals_dir=str(tmp_path)` para no tocar las sesiones vivas.

python/functions/infra/set_dod_contract.py

@@ -0,0 +1,79 @@
+"""Escribe un DoD-contrato fijo y su estado en el sidecar goal.json de una sesion Claude."""
+
+import json
+import os
+
+_VALID_STATUS = ("pending", "met", "failed")
+
+
+def set_dod_contract(
+    session_id: str,
+    contract: str,
+    status: str = "pending",
+    goals_dir: str | None = None,
+) -> dict:
+    """Escribe el DoD-contrato y su estado en el goal.json de una sesion Claude.
+
+    Lee el sidecar `<goals_dir>/<session_id>.json` si existe, preservando
+    TODOS sus campos (goal, phase, dod, history, prompts, etc.), y actualiza
+    solo las claves `dod_contract` y `dod_status`. La escritura es atomica
+    (tmp + os.replace) para no corromper el archivo si el proceso muere a mitad.
+
+    Args:
+        session_id: ID de la sesion Claude. Da nombre al archivo
+            `<session_id>.json` dentro de goals_dir.
+        contract: Criterio de aceptacion estable contra el que se evalua la
+            terminacion del agente. No puede ser vacio.
+        status: Estado del contrato. Uno de "pending", "met" o "failed".
+        goals_dir: Directorio de sidecars de goal. Por defecto
+            `~/.claude/goals`.
+
+    Returns:
+        dict con session_id, path, dod_contract, dod_status y written.
+
+    Raises:
+        ValueError: si contract es vacio o status no es valido. No escribe nada.
+    """
+    if not contract or not contract.strip():
+        raise ValueError("contract no puede ser vacio: un DoD-contrato vacio no tiene sentido")
+    if status not in _VALID_STATUS:
+        raise ValueError(
+            f"status invalido: {status!r}. Debe ser uno de {_VALID_STATUS}"
+        )
+
+    if goals_dir is None:
+        goals_dir = os.path.join(os.path.expanduser("~"), ".claude", "goals")
+
+    os.makedirs(goals_dir, exist_ok=True)
+    path = os.path.join(goals_dir, f"{session_id}.json")
+
+    data: dict = {}
+    if os.path.exists(path):
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                loaded = json.load(f)
+            if isinstance(loaded, dict):
+                data = loaded
+        except (json.JSONDecodeError, OSError):
+            # Archivo corrupto o ilegible: no se pierde lo nuevo, se parte limpio.
+            data = {}
+
+    # Solo se tocan estas dos claves; el resto del dict se preserva intacto.
+    data["dod_contract"] = contract
+    data["dod_status"] = status
+
+    tmp_path = f"{path}.tmp"
+    with open(tmp_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+        f.flush()
+        os.fsync(f.fileno())
+    os.replace(tmp_path, path)
+
+    return {
+        "session_id": session_id,
+        "path": path,
+        "dod_contract": contract,
+        "dod_status": status,
+        "written": True,
+    }

python/functions/infra/set_dod_contract_test.py

@@ -0,0 +1,101 @@
+"""Tests para set_dod_contract."""
+
+import json
+import os
+
+import pytest
+
+from .set_dod_contract import set_dod_contract
+
+
+def _read(path: str) -> dict:
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def test_escribe_contrato_en_goal_json_existente_y_preserva_otros_campos(tmp_path):
+    sid = "sess-existente"
+    path = os.path.join(str(tmp_path), f"{sid}.json")
+    existing = {
+        "goal": "implementar la fase 2",
+        "phase": "build",
+        "dod": "tests verdes (volatil, lo escribe el hook)",
+        "history": [{"turn": 1, "action": "init"}],
+        "prompts": ["primer prompt"],
+        "emojis": "🚀",
+    }
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(existing, f)
+
+    res = set_dod_contract(sid, "criterio fijo de aceptacion", status="pending", goals_dir=str(tmp_path))
+
+    assert res["written"] is True
+    assert res["session_id"] == sid
+    assert res["path"] == path
+    assert res["dod_contract"] == "criterio fijo de aceptacion"
+    assert res["dod_status"] == "pending"
+
+    data = _read(path)
+    # Las dos claves nuevas estan.
+    assert data["dod_contract"] == "criterio fijo de aceptacion"
+    assert data["dod_status"] == "pending"
+    # TODO el resto se preserva intacto.
+    assert data["goal"] == "implementar la fase 2"
+    assert data["phase"] == "build"
+    assert data["dod"] == "tests verdes (volatil, lo escribe el hook)"
+    assert data["history"] == [{"turn": 1, "action": "init"}]
+    assert data["prompts"] == ["primer prompt"]
+    assert data["emojis"] == "🚀"
+
+
+def test_crea_el_archivo_si_no_existe(tmp_path):
+    sid = "sess-nueva"
+    path = os.path.join(str(tmp_path), f"{sid}.json")
+    assert not os.path.exists(path)
+
+    res = set_dod_contract(sid, "contrato nuevo", goals_dir=str(tmp_path))
+
+    assert os.path.exists(path)
+    assert res["dod_status"] == "pending"  # default
+    data = _read(path)
+    assert data == {"dod_contract": "contrato nuevo", "dod_status": "pending"}
+
+
+def test_status_invalido_lanza_valueerror_sin_escribir(tmp_path):
+    sid = "sess-bad-status"
+    path = os.path.join(str(tmp_path), f"{sid}.json")
+
+    with pytest.raises(ValueError):
+        set_dod_contract(sid, "un contrato", status="done", goals_dir=str(tmp_path))
+
+    assert not os.path.exists(path)
+
+
+def test_contract_vacio_lanza_valueerror_sin_escribir(tmp_path):
+    sid = "sess-empty"
+    path = os.path.join(str(tmp_path), f"{sid}.json")
+
+    with pytest.raises(ValueError):
+        set_dod_contract(sid, "", goals_dir=str(tmp_path))
+    with pytest.raises(ValueError):
+        set_dod_contract(sid, "   ", goals_dir=str(tmp_path))
+
+    assert not os.path.exists(path)
+
+
+def test_reescribir_actualiza_sin_duplicar(tmp_path):
+    sid = "sess-reescribe"
+    path = os.path.join(str(tmp_path), f"{sid}.json")
+
+    set_dod_contract(sid, "contrato v1", status="pending", goals_dir=str(tmp_path))
+    set_dod_contract(sid, "contrato v2", status="met", goals_dir=str(tmp_path))
+
+    data = _read(path)
+    assert data["dod_contract"] == "contrato v2"
+    assert data["dod_status"] == "met"
+    # Solo dos claves, ninguna duplicada ni residual.
+    assert sorted(data.keys()) == ["dod_contract", "dod_status"]
+    # El archivo es JSON valido unico (no concatenado).
+    raw = open(path, "r", encoding="utf-8").read()
+    assert raw.count('"dod_contract"') == 1
+    assert raw.count('"dod_status"') == 1