🧬 FIA HARNESS COMPLETO

El sistema operativo para construir software con agentes de IA. Especificación antes que código · Seguridad por diseño · Contexto mínimo en cada fase · Cero asunciones en silencio

Python 3.8+ · Sin dependencias externas · Mono o multi-agente · 2 modos de trabajo · Reglas verificadas en CI · LLM-agnóstico (funciona con DeepSeek, OpenCode, Claude, GPT o el agente que uses)

🗺️ El sistema en un vistazo

graph TD
    PRD["📄 PRD.md<br/>documento de negocio"] --> BOOT["⚙️ bootstrap.py<br/>(Fase M0)"]
    BOOT --> CTX["CONTEXT.md<br/>resumen vivo del negocio"]
    BOOT --> PROG["PROGRESS.md<br/>fases M0-M3"]
    CTX --> INT["🧠 Agente de IA<br/>Entrevista técnica (M1)"]
    INT --> SEC["SECURITY.md<br/>AEO_GEO_SEO.md<br/>decisiones en CONTEXT.md"]
    SEC --> SPEC["SPEC.md<br/>especificación aprobada<br/>por el humano (M2)"]
    SPEC --> PLAN["Tabla F0-Fn<br/>en PROGRESS.md (M3)"]
    PLAN --> GEN["🤖 task_generator.py"]
    GEN --> TASK["TASK-F1.md<br/>checklists de seguridad,<br/>visibilidad y UX inyectados"]
    TASK --> RUN["🛠️ Agente ejecuta<br/>auditoría → diseño → código"]
    RUN --> VAL["✅ Fase K<br/>tests · typecheck · lint · build"]
    VAL -- falla --> RUN
    VAL -- pasa --> NEXT["PROGRESS.md actualizado<br/>siguiente fase pendiente"]
    NEXT --> GEN

La idea central: el PRD se lee una vez. A partir de ahí, cada fase del agente solo carga 4 archivos comprimidos (CONTEXT.md + sección de SPEC.md + PROGRESS.md + TASK-Fx.md). Nunca se reenvía el histórico completo. Contexto pequeño = respuestas más baratas, más rápidas y con menos deriva.

⚙️ Cómo funciona: tres motores

1️⃣ Fases de proceso (M0–M3) — pensar antes de construir

🚫 Hasta que M3 cierra, no se escribe una sola línea de código de producción.

2️⃣ Fases de ejecución (F0–Fn) — construir fase a fase

Cada fase del plan = una tarea = un ciclo completo y cerrado. Ejemplo de plan típico:

task_generator.py detecta automáticamente la primera fase pendiente y genera su tarea. Tú decides cuándo arrancar la siguiente; el agente nunca encadena fases solo.

3️⃣ El ciclo de tarea (A–L) — disciplina en cada fase

A. Auditoría          → inspeccionar antes de tocar
B. Diseño             → mapa mínimo alineado con SPEC.md
C. Hipótesis          → declarar decisiones, no asumirlas
E. Implementación     → cambio mínimo necesario
F. Edge cases         → idempotencia, carreras, validación
I. Tests              → escenarios mínimos obligatorios
J. No hacer / J2      → scope cerrado + checklist de seguridad
H2. Visibilidad       → SEO/AEO/GEO si hay superficie pública
H3. UI/UX             → Design DNA aprobado si hay interfaz
K. Validación         → tests · typecheck · lint · build
L. Informe final      → qué se hizo, qué no, y resultado verificado

Las fases H2 (Visibilidad) y J2 (Seguridad) se inyectan automáticamente solo si la fase las necesita, con el contenido real y vivo de tus AEO_GEO_SEO.md, SECURITY.md y UI_UX_EXCLUSIVA.md. Si no aplican, el generador lo deja escrito con su motivo — nunca se omite en silencio.

🚀 Arranque en 4 pasos

⚡ O en un solo comando (PyPI): uvx fia-harness init (o pipx run fia-harness init) monta el proyecto nuevo automáticamente — plantillas en /docs, scripts en la raíz y PRD.md de partida. Salta al paso 2.

1. Prepara el proyecto nuevo
   ├── bootstrap.py + task_generator.py en la raíz
   ├── /docs con las 8 plantillas maestras
   ├── (opcional) RAG_VECTOR_EXTENSION.md dentro de /docs si habrá búsqueda semántica
   └── PRD.md en la raíz

2. python bootstrap.py          → Fase M0 automática
   Genera CONTEXT.md, PROGRESS.md, progress.json, DECISIONS.md,
   activa las plantillas y emite .github/workflows/harness.yml

3. Abre tu agente con la carpeta → inicia la entrevista (M1)
   El agente lee CONTEXT.md y NO programa nada todavía.

4. Aprueba SPEC.md, pega la tabla F0-Fn en PROGRESS.md y compila:
   python task_generator.py --sync   → valida el estado en progress.json
   python task_generator.py          → genera la tarea de la fase pendiente

📖 Guía detallada paso a paso: INSTRUCCIONES DE APLICACION.txt · Protocolo completo: INICIO_PROYECTO.md

📁 Mapa de archivos

⚡ Dos modos de trabajo

Promoción automática a Completo si aparece cualquiera de estos: auth/roles, pagos, PII/salud, migraciones críticas, escritura en servicios externos, deploy/secretos, alcance incierto. La promoción conserva el trabajo ya validado.

Para activar Lite: declara Modo de trabajo: Lite en CONTEXT.md (lo detecta task_generator.py solo) o fuerza con --lite.

🧩 Módulos condicionales

El harness base es común; estas capas se activan solo cuando el proyecto las necesita:

🚨 Enforcement: las reglas tienen dientes (nuevo en v2)

Un harness de documentos obliga por convención; este kit desde la v2 obliga también por infraestructura. bootstrap.py emite un workflow de GitHub Actions (.github/workflows/harness.yml) que se ejecuta en cada push y PR:

El flujo de estado: PROGRESS.md sigue siendo la superficie de edición (humano o agente), y task_generator.py --sync lo compila y valida en progress.json. Si editas el Markdown a mano y no compila, el CI se pone rojo hasta que hagas --sync. Y --sync es fail-closed: si el estado viola una regla, no escribe nada.

python task_generator.py --sync      # compila y valida PROGRESS.md -> progress.json
python task_generator.py --check     # valida sin modificar nada (lo ejecuta el CI)
python task_generator.py --approval "instalar Skill X v1.2" --phase F2 --ref "chat 5-sep"

🛡️ Las reglas que nunca se rompen

1. 🚫 Nunca codificar sin spec aprobada — ni una línea antes del M3.
2. 🗣️ Nunca asumir en silencio — toda asunción se declara y se confirma.
3. 📦 Nunca reenviar contexto innecesario — los archivos de control son la fuente comprimida.
4. ✅ Nunca cerrar una fase sin su Definition of Done — ni mezclar fases.
5. 🔐 Nunca cerrar una fase de seguridad sin su checklist — la seguridad no se pospone a un audit final.
6. 🙋 Nunca instalar/buscar/conectar una Skill, MCP o librería sin aprobación humana — el silencio no es permiso.
7. 🧪 Nunca inventar resultados — los tests que no se ejecutaron no existen.
8. 🛑 Nunca hacer commit/push/deploy sin autorización explícita.

🚨 Desde la v2, las reglas 4, 5, 7 y 8 además se verifican automáticamente en CI en cada proyecto que arranca con bootstrap.py (sección anterior).

✅ Verificar el kit

python -m unittest discover tests -v

Los tests cubren el parser de PROGRESS.md (tablas múltiples, negritas, columnas combinadas), la extracción de secciones con tablas reales, los inyectores por marcadores, la heurística de palabras clave (incluido el falso positivo clásico de "entrevista"), el recorte de plantilla, la detección de Modo Lite, la máquina de estado (dependencias, checkpoints, TASKs, aprobaciones, drift y fail-closed) y un ciclo completo e2e (bootstrap.py → task_generator.py) en carpeta temporal.

En un proyecto ya arrancado, puedes comprobar su estado en cualquier momento:

python task_generator.py --check

📜 Documentación y fuentes de verdad