💾 State — Persistencia y Continuidad entre Sesiones

Objetivo: Entender por qué los agentes "olvidan" lo que hicieron en sesiones anteriores y cómo diseñar un sistema de estado que lo mitigue.

Los agentes de IA operan dentro de una ventana de contexto finita. Cuando una tarea dura más de una sesión, el agente pierde:

• Qué archivos modificó y por qué
• Decisiones técnicas tomadas durante la implementación
• Errores encontrados y cómo se resolvieron
• El progreso exacto de cada feature

Consecuencias: rework innecesario, inconsistencias, regresiones y demoras. Un agente sin estado persistente puede gastar el 30-40% de sus tokens redescubriendo lo que ya sabía.

"Un agente sin estado es como un desarrollador que empieza desde cero cada mañana sin notas, sin commits descriptivos y sin tickets."

Objetivo: Diseñar un archivo de tareas que funcione como fuente única de verdad sobre qué se está construyendo, qué viene después y qué ya está hecho.

Estructura:

• Milestone Actual: ámbito de la iteración actual
• En Progreso: exactamente una tarea. Si hay dos, el agente multitarea y empeora.
• Pendiente: cola priorizada de próximas tareas
• Completado: historial con fechas o referencias a commits
• Descubiertos durante el trabajo: problemas, ideas, deuda técnica encontrada

# 📋 Task Tracking

> Última actualización: 2026-05-10

## 🎯 Milestone Actual: v0.2.0 — Autenticación

### En Progreso
- [ ] Implementar OAuth2 con GitHub
  - Branch: `feat/oauth`
  - Notas: usar `authlib`, callback en `/auth/github`

### Pendiente
- [ ] Página de login con branding
- [ ] Middleware de protección de rutas

### Completado
- [x] Estructura base de usuarios (commit `a1b2c3d`)
- [x] Modelo User en base de datos (commit `e4f5g6h`)

### 💡 Descubiertos durante el trabajo
- El rate limit de GitHub requiere caché local
- Considerar JWT en lugar de sessions para API

Objetivo: Al final de cada sesión, dejar un resumen que permita a un agente (o a ti mismo) continuar exactamente donde se quedó.

5 pasos del handoff:

1. Estado actual: ¿Qué se logró? ¿Qué quedó a medias?
2. Archivos modificados: lista con paths exactos y qué cambió en cada uno
3. Decisiones tomadas: por qué se eligió A en lugar de B
4. Próximo paso: instrucción explícita de cómo continuar
5. Comandos para verificar: cómo ejecutar tests o levantar el proyecto

# 📝 Session Handoff — 2026-05-10 22:00 UTC

## Estado Actual
- Implementado el módulo de escaneo en `src/harness/scanner.py`
- Faltan 2 checks de verificación (checks 3.4 y 3.5)
- Tests pasan: 18/20

## Archivos Modificados
- `src/harness/scanner.py` — lógica de escaneo recursivo
- `tests/test_scanner.py` — tests unitarios nuevos
- `pyproject.toml` — dependencia `pathspec` añadida

## Decisiones
- Usar `pathspec` en lugar de `fnmatch` para .gitignore matching
  más robusto.

## Próximo Paso
- Implementar checks 3.4 (existencia de tests) y 3.5 (coverage)
- Ejecutar: `pytest tests/test_scanner.py -v`

## Verificación
```bash
harness scan . --json
pytest
```

Objetivo: Trackear el progreso de múltiples features sin necesidad de cargar párrafos de texto en el contexto del agente.

Un archivo feature_list.json (o YAML) es ideal porque:

• Es parseable por máquina y legible por humanos
• Ocupa pocas líneas por feature
• Puede ser consumido por scripts de CI para reportes

{
  "version": "1.0",
  "last_updated": "2026-05-10",
  "features": [
    {
      "id": "auth-oauth",
      "title": "Autenticación OAuth2",
      "status": "in_progress",
      "progress_percent": 65,
      "owner": "agent",
      "branch": "feat/oauth",
      "blocked_by": []
    },
    {
      "id": "ci-pipeline",
      "title": "Pipeline CI/CD",
      "status": "pending",
      "progress_percent": 0,
      "owner": "agent",
      "branch": "feat/ci",
      "blocked_by": ["auth-oauth"]
    }
  ]
}

Patrón de Heartbeat: Cada 30 minutos de trabajo, el agente actualiza last_updated y progress_percent. Esto crea un "pulso" visible de actividad y permite detectar sesiones abandonadas.