# MISIÓN: Implementar 3 capas de integridad en AgentSquad

Eres un ingeniero senior trabajando en **AgentSquad**, una plataforma de
orquestación multi-agente para negocios (squads de agentes IA que ejecutan
trabajo real: procesar leads, mover datos, postear a canales de clientes, etc.).

Tu tarea: implementar tres capas de integridad inspiradas en un framework de
referencia (T3MP3ST). NO copies código de ese framework — solo el patrón. Cada
capa abajo trae el mecanismo concreto que debes replicar en la arquitectura real
de AgentSquad.

## Reglas duras (no negociables)
- Comunicación en español, directo.
- NUNCA fabricar stats/montos/credenciales — todo dato reportado debe ser
  verificable o se omite. Estas capas son, precisamente, el enforcement técnico
  de esa regla.
- Verificar antes de afirmar estado (no asumas rutas ni comportamiento del repo).
- Sistemas externos = append-only, nunca destructivo sin gate.
- Todo cambio va con tests. Los tests existentes deben seguir en verde.
- No imprimir valores de credenciales, solo nombres de variables.

## FASE 0 — Reconocimiento (obligatoria, primero)
No conoces el repo. Antes de escribir código, descubre y documenta en 1 página:
1. Dónde viven los agentes/operadores y cómo se define cada uno (rol, prompt, tools).
2. Cómo un agente ejecuta una tool/acción: el punto único (o los puntos) donde
   una llamada a tool pasa del LLM al side-effect real. ESTE es tu choke point.
3. Dónde se persisten resultados/outputs/métricas de una misión o task.
4. Dónde está el runner de tests y el CI (qué comando corre en cada push).
5. Cómo se reportan métricas al cliente hoy (dashboard, API, informe).
Si algo es genuinamente ambiguo y bloquea el diseño, pregunta. Si no, procede.

## FASE 0.5 — Plan
Usa el skill `superpowers:writing-plans`. El plan DEBE agrupar tasks en **waves**
con dependencias, y CADA task DEBE tener un bloque **Done when** con 2-5 criterios
verificables por comando (no subjetivos). Orden recomendado de capas: A → B → C
(cada una se apoya en la anterior).

---

## CAPA A — Provenance como invariante testeada (anti-alucinación estructural)
**Problema que resuelve:** hoy la anti-alucinación es ad-hoc (algún pipeline exige
evidencia verbatim, otros no) — por eso existe un bug de alucinación abierto en el
agente PMO. Objetivo: hacer estructuralmente imposible que un agente reporte algo
que ninguna tool/fuente produjo.

**Mecanismo a replicar:**
1. En el choke point de ejecución de tools (Fase 0.2), registra cada ejecución en
   un **evidence ledger** por task: `{tool_name, args, raw_output, timestamp}`.
2. Añade un **validador de provenance**: antes de aceptar un finding/claim/output
   estructurado de un agente, verifica que su evidencia sea substring exacto o
   derivable determinísticamente del `raw_output` registrado en el ledger. Claim
   sin evidencia trazable = rechazado (o marcado `unverified`, nunca reportado como
   hecho).
3. Añade un **fabrication filter**: rechaza valores placeholder típicos
   (fake/dummy/placeholder/TODO/TBD/example, y leet-variants de esos).
4. Escribe un **test de invariante** estilo `no-phantom-tools`: inyecta un claim
   fabricado (sin entrada en el ledger) y verifica que el sistema lo rechace;
   verifica que un claim con evidencia real pase. Este test corre en CI.

**Done when:**
- [ ] `<comando de test>` incluye un test que FALLA si se inyecta un phantom claim
      y PASA con evidencia trazable → verde.
- [ ] El validador está en el choke point único, no reimplementado por pipeline.
- [ ] El test corre en CI (aparece en el pipeline de cada push).
- [ ] Sin regresiones: suite completa en verde.

---

## CAPA B — Guardrails de acción: scope containment + human-approval gate
**Problema que resuelve:** un agente que actúa sobre sistemas del cliente puede
salir de perímetro o ejecutar algo irreversible sin control.

**Mecanismo a replicar:**
1. **Scope containment:** cada misión/agente declara un scope (recursos, dominios,
   canales, cuentas permitidas). Toda acción con efecto externo (red, escritura,
   post, email) se chequea contra el scope **ANTES** de ejecutar. Fuera de scope →
   error `SCOPE DENIED` sin ejecutar el side-effect. El chequeo va antes del
   subproceso/request, no después.
2. **Toolkit por rol (menor privilegio):** cada agente tiene una allowlist
   explícita de tools. Pedir una tool fuera de la allowlist = rechazo.
3. **Human-approval gate:** acciones irreversibles o externas (postear al canal del
   cliente, enviar email, escribir/borrar en CRM/DB) quedan en estado
   `pending-approval` hasta aprobación explícita; acciones inocuas (lectura,
   análisis) corren solas. Clasifica cada tool como `safe` | `gated`.

**Done when:**
- [ ] Test: acción fuera de scope se rechaza con `SCOPE DENIED` ANTES de cualquier
      side-effect (mockea el side-effect y verifica que no se invocó).
- [ ] Test: agente pidiendo tool fuera de su allowlist es rechazado.
- [ ] Test: acción `gated` queda `pending-approval` y solo procede tras aprobación.
- [ ] Sin regresiones: suite completa en verde.

---

## CAPA C — "Receipts, not vibes": métricas re-derivables
**Problema que resuelve:** el cliente hoy debe confiar en el dashboard. Objetivo:
cada métrica headline que AgentSquad reporta se recomputa desde artefactos
persistidos con un comando — el cliente (o una IA que cite a AgentSquad) puede
recalcularla.

**Mecanismo a replicar:**
1. Persistir por misión/task los **artefactos crudos** necesarios para recomputar
   cada métrica reportada (inputs, evidencia del ledger de Capa A, veredictos).
   Formato estructurado y estable (JSON).
2. Un comando `verify-claims` que **re-deriva cada número headline** desde esos
   artefactos y sale con código 0 (todo consistente) o 1 (drift). Aplica el
   fabrication filter de Capa A.
3. El comando imprime, por métrica, el número + de qué artefactos sale (el "recibo").
4. Documentar cómo un tercero recomputa una métrica dada.
5. Sé honesto sobre el alcance del comando en su propio output: es un check de
   reproducibilidad de artefactos commiteados, no una auditoría independiente.

**Done when:**
- [ ] `verify-claims` re-deriva ≥N métricas reportadas y sale 0.
- [ ] Test: alterar un artefacto hace que `verify-claims` salga 1 (detecta drift).
- [ ] Corre en CI o en el checklist de pre-release.
- [ ] Sin regresiones: suite completa en verde.

---

## Entrega final
1. El plan (waves + Done-when) aprobado antes de implementar.
2. Las 3 capas implementadas, cada una con sus tests en verde y corriendo en CI.
3. Un resumen: qué choke point tocaste, qué quedó como invariante global vs qué
   sigue por-pipeline, y qué métricas expone `verify-claims`.
4. Reporta honestamente: si una capa quedó parcial, dilo con el motivo.