# Capability group: agents

Funciones para orquestar agentes Claude headless en git worktrees con DoD (Definition of Done) evidence schema.

Cubre el ciclo de vida completo de un run autonomo: crear sandbox (worktree + rama), lanzar `claude -p` headless, redirigir logs, hacer cleanup ordenado tras terminar/abortar, y auditar el frontmatter `dod_evidence_schema` que valida que cada run dejo evidencia trazable.

## Funciones

| ID | Firma corta | Que hace |
|---|---|---|
| `agent_launch_worktree_go_infra` | `AgentLaunchWorktree(cfg) WorktreeLaunchResult` | crear worktree + spawn claude headless en background |
| `agent_cleanup_worktree_go_infra` | `AgentCleanupWorktree(repo, branch, path, pid) error` | kill PID + remove worktree + delete branch (best-effort) |
| `audit_dod_schema_go_infra` | `AuditDodSchema(issuesDir, flowsDir) Report` | escanea `.md` y valida bloque `dod_evidence_schema` del frontmatter |

## Ejemplo canonico end-to-end

```go
package main

import (
    "fmt"
    "log"

    "fn-registry/functions/infra"
)

func main() {
    cfg := infra.WorktreeLaunchConfig{
        RepoRoot:      "/home/lucas/fn_registry",
        Branch:        "auto/0115-worktree-launcher-fn",
        WorktreePath:  "/home/lucas/fn_registry/worktrees/0115-worktree-launcher-fn",
        Prompt:        "Implement issue 0115 — worktree launcher Go function",
        LogPath:       "/tmp/claude-0115.log",
        SkipPerms:     true,
        ResetIfExists: true,
    }

    res := infra.AgentLaunchWorktree(cfg)
    if res.Error != "" {
        log.Fatal(res.Error)
    }
    fmt.Printf("claude PID=%d log=%s\n", res.PID, res.LogPath)

    // ... agente trabaja, tail del log, polling /proc/<pid>, etc ...

    // Cleanup tras terminar/abortar
    if err := infra.AgentCleanupWorktree(cfg.RepoRoot, cfg.Branch, cfg.WorktreePath, res.PID); err != nil {
        log.Printf("partial cleanup: %v", err)
    }

    // Validar DoD del issue antes de cerrarlo
    report, _ := infra.AuditDodSchema("/home/lucas/fn_registry/dev/issues", "")
    fmt.Printf("dod: %d items, %d invalid\n", report.TotalItems, report.InvalidItems)
}
```

## Fronteras

- **NO maneja merge a master** — eso es responsabilidad de `apps/agent_runner_api` (issue 0113).
- **NO persiste runs** — la tabla `agent_runs.db` vive en `agent_runner_api`, no aqui.
- **NO valida DoD** — `audit_dod_schema_go_infra` solo lee `dod_evidence_schema` y comprueba que cada item tenga id/kind/expected validos. La evidencia real (screenshots, logs, urls) se valida en otra capa.
- **NO genera el prompt** — el caller compone el prompt antes de pasarlo. Para integraciones con `dev/issues/<NNNN>.md`, usar funciones de `dev/` directamente.
- **NO maneja Windows**: `agent_cleanup_worktree` usa `syscall.Kill` (Linux/Darwin). En Windows compila pero el kill no hace nada — documentado en `agent_cleanup_worktree.md`.

## Prerequisitos

- `git` >= 2.5 (worktrees).
- Rama `master` (no `main`) en el repo principal — `AgentLaunchWorktree` hace `git worktree add ... -b <branch> master`.
- Opcional: binario `claude` en PATH. Si falta, la funcion hace fallback a un `echo` stub que termina inmediatamente — util para tests CI, no para produccion.

## Notas

- Las dos funciones operativas (`launch`/`cleanup`) son simetricas — siempre que se llame a una se debe llamar a la otra. `agent_runner_api` lo encadena en un defer.
- `audit_dod_schema` se invoca tambien desde `fn doctor dod` (issue 0114) — la dependencia es bidireccional logicamente, pero del registry no hay imports entre ellas.