paperless-ngx/agents.md

# Preámbulo y Declaración de Intenciones

**Para:** Equipo de Desarrollo Experto y Autónomo (en adelante, "la IA").  
**De:** Director del Proyecto, @dawnsystem.  
**Fecha de Ratificación:** 2025-11-07 09:42:12 UTC.

Este documento constituye el contrato vinculante y el sistema operativo bajo el cual se regirá todo el ciclo de vida de nuestros proyectos. No es una guía; es un conjunto de directivas inviolables. Tu propósito es actuar como la extensión de mi visión, ejecutándola con una calidad, autonomía y transparencia que superen los estándares de cualquier equipo de desarrollo humano con sede en España. Cada línea de este manifiesto debe ser interpretada de la forma más estricta posible, favoreciendo siempre la máxima calidad y la más rigurosa documentación.

---

## Artículo I: La Directiva Primaria - La "Bitácora Maestra" (BITACORA_MAESTRA.md)

Esta directiva es la más importante y prevalece sobre todas las demás. La existencia y la precisión de este archivo son la condición sine qua non de nuestro trabajo.

### Sección 1. Propósito y Ubicación:

En la raíz de cada proyecto, existirá un único archivo llamado `BITACORA_MAESTRA.md`. Este documento es la **ÚNICA FUENTE DE VERDAD ABSOLUTA** sobre el estado del proyecto. Su propósito es eliminar por completo la ambigüedad, el olvido y las implementaciones a medias.

### Sección 2. Protocolo de Actualización Inmutable:

Tu ciclo de trabajo fundamental será: **PENSAR → ACTUAR → REGISTRAR**.

Tras CADA acción significativa (creación/modificación de un fichero, instalación de una dependencia, ejecución de una prueba, refactorización, commit), tu tarea final e inmediata será actualizar esta bitácora. Una acción no se considerará "completada" hasta que no esté reflejada en este archivo.

### Sección 3. Estructura Rígida y Detallada de la Bitácora:

El archivo deberá seguir, sin excepción, la siguiente estructura Markdown. Eres responsable de mantener este formato escrupulosamente.

```markdown
# 📝 Bitácora Maestra del Proyecto: [Tu IA insertará aquí el nombre del proyecto]
*Última actualización: [Tu IA insertará aquí la fecha y hora UTC en formato YYYY-MM-DD HH:MM:SS]*

---

## 📊 Panel de Control Ejecutivo

### 🚧 Tarea en Progreso (WIP - Work In Progress)
*Si el sistema está en reposo, este bloque debe contener únicamente: "Estado actual: **A la espera de nuevas directivas del Director.**"*

*   **Identificador de Tarea:** `[ID único de la tarea, ej: TSK-001]`
*   **Objetivo Principal:** `[Descripción clara del objetivo final, ej: Implementar la autenticación de usuarios con JWT]`
*   **Estado Detallado:** `[Descripción precisa del punto exacto del proceso, ej: Modelo de datos y migraciones completados. Desarrollando el endpoint POST /api/auth/registro.]`
*   **Próximo Micro-Paso Planificado:** `[La siguiente acción concreta e inmediata que se va a realizar, ej: Implementar la lógica de hash de la contraseña usando bcrypt dentro del servicio de registro.]`

### ✅ Historial de Implementaciones Completadas
*(En orden cronológico inverso. Cada entrada es un hito de negocio finalizado)*

*   **[YYYY-MM-DD] - `[ID de Tarea]` - Título de la Implementación:** `[Impacto en el negocio o funcionalidad añadida. Ej: feat: Implementado el sistema de registro de usuarios.]`

---

## 🔬 Registro Forense de Sesiones (Log Detallado)
*(Este es un registro append-only que nunca se modifica, solo se añade. Proporciona un rastro de auditoría completo)*

### Sesión Iniciada: [YYYY-MM-DD HH:MM:SS UTC]

*   **Directiva del Director:** `[Copia literal de mi instrucción]`
*   **Plan de Acción Propuesto:** `[Resumen del plan que propusiste y yo aprobé]`
*   **Log de Acciones (con timestamp):**
    *   `[HH:MM:SS]` - **ACCIÓN:** Creación de fichero. **DETALLE:** `src/modelos/Usuario.ts`. **MOTIVO:** Definición del esquema de datos del usuario.
    *   `[HH:MM:SS]` - **ACCIÓN:** Modificación de fichero. **DETALLE:** `src/rutas/auth.ts`. **CAMBIOS:** Añadido endpoint POST /api/auth/registro.
    *   `[HH:MM:SS]` - **ACCIÓN:** Instalación de dependencia. **DETALLE:** `bcrypt@^5.1.1`. **USO:** Hashing de contraseñas.
    *   `[HH:MM:SS]` - **ACCIÓN:** Ejecución de test. **COMANDO:** `npm test -- auth.test.ts`. **RESULTADO:** `[PASS/FAIL + detalles]`.
    *   `[HH:MM:SS]` - **ACCIÓN:** Commit. **HASH:** `abc123def`. **MENSAJE:** `feat(auth): añadir endpoint de registro de usuarios`.
*   **Resultado de la Sesión:** `[Ej: Hito TSK-001 completado. / Tarea TSK-002 en progreso.]`
*   **Commit Asociado:** `[Hash del commit, ej: abc123def456]`
*   **Observaciones/Decisiones de Diseño:** `[Cualquier decisión importante tomada, ej: Decidimos usar bcrypt con salt rounds=12 por balance seguridad/performance.]`

---

## 📁 Inventario del Proyecto (Estructura de Directorios y Archivos)
*(Esta sección debe mantenerse actualizada en todo momento. Es como un `tree` en prosa.)*

```
proyecto-raiz/
├── src/
│   ├── modelos/
│   │   └── Usuario.ts (PROPÓSITO: Modelo de datos para usuarios)
│   ├── rutas/
│   │   └── auth.ts (PROPÓSITO: Endpoints de autenticación)
│   └── index.ts (PROPÓSITO: Punto de entrada principal)
├── tests/
│   └── auth.test.ts (PROPÓSITO: Tests del módulo de autenticación)
├── package.json (ESTADO: Actualizado con bcrypt@^5.1.1)
└── BITACORA_MAESTRA.md (ESTE ARCHIVO - La fuente de verdad)
```

---

## 🧩 Stack Tecnológico y Dependencias

### Lenguajes y Frameworks
*   **Lenguaje Principal:** `[Ej: TypeScript 5.3]`
*   **Framework Backend:** `[Ej: Express 4.18]`
*   **Framework Frontend:** `[Ej: React 18 / Vue 3 / Angular 17]`
*   **Base de Datos:** `[Ej: PostgreSQL 15 / MongoDB 7]`

### Dependencias Clave (npm/pip/composer/cargo)
*(Lista exhaustiva con versiones y propósito)*

*   `express@4.18.2` - Framework web para el servidor HTTP.
*   `bcrypt@5.1.1` - Hashing seguro de contraseñas.
*   `jsonwebtoken@9.0.2` - Generación y verificación de tokens JWT.

---

## 🧪 Estrategia de Testing y QA

### Cobertura de Tests
*   **Cobertura Actual:** `[Ej: 85% líneas, 78% ramas]`
*   **Objetivo:** `[Ej: >90% líneas, >85% ramas]`

### Tests Existentes
*   `tests/auth.test.ts` - **Estado:** `[PASS/FAIL]` - **Última ejecución:** `[YYYY-MM-DD HH:MM]`

---

## 🚀 Estado de Deployment

### Entorno de Desarrollo
*   **URL:** `[Ej: http://localhost:3000]`
*   **Estado:** `[Ej: Operativo]`

### Entorno de Producción
*   **URL:** `[Ej: https://miapp.com]`
*   **Última Actualización:** `[YYYY-MM-DD HH:MM UTC]`
*   **Versión Desplegada:** `[Ej: v1.2.3]`

---

## 📝 Notas y Decisiones de Arquitectura

*(Registro de decisiones importantes sobre diseño, patrones, convenciones)*

*   **[YYYY-MM-DD]** - Decidimos usar el patrón Repository para el acceso a datos. Justificación: Facilita el testing y separa la lógica de negocio de la persistencia.

---

## 🐛 Bugs Conocidos y Deuda Técnica

*(Lista de issues pendientes que requieren atención futura)*

*   **BUG-001:** Descripción del bug. Estado: Pendiente/En Progreso/Resuelto.
*   **TECH-DEBT-001:** Refactorizar el módulo X para mejorar mantenibilidad.
```

---

## Artículo II: Principios de Calidad y Estándares de Código

### Sección 1. Convenciones de Nomenclatura:

*   **Variables y funciones:** camelCase (ej: `getUserById`)
*   **Clases e interfaces:** PascalCase (ej: `UserRepository`)
*   **Constantes:** UPPER_SNAKE_CASE (ej: `MAX_RETRY_ATTEMPTS`)
*   **Archivos:** kebab-case (ej: `user-service.ts`)

### Sección 2. Documentación del Código:

Todo código debe estar documentado con JSDoc/TSDoc/Docstrings según el lenguaje. Cada función pública debe tener:
*   Descripción breve del propósito
*   Parámetros (@param)
*   Valor de retorno (@returns)
*   Excepciones (@throws)
*   Ejemplos de uso (@example)

### Sección 3. Testing:

*   Cada funcionalidad nueva debe incluir tests unitarios.
*   Los tests de integración son obligatorios para endpoints y flujos críticos.
*   La cobertura de código no puede disminuir con ningún cambio.

---

## Artículo III: Workflow de Git y Commits

### Sección 1. Mensajes de Commit:

Todos los commits seguirán el formato Conventional Commits:

```
<tipo>(<ámbito>): <descripción corta>

<descripción larga opcional>

<footer opcional>
```

**Tipos válidos:**
*   `feat`: Nueva funcionalidad
*   `fix`: Corrección de bug
*   `docs`: Cambios en documentación
*   `style`: Cambios de formato (no afectan código)
*   `refactor`: Refactorización de código
*   `test`: Añadir o modificar tests
*   `chore`: Tareas de mantenimiento

**Ejemplo:**
```
feat(auth): añadir endpoint de registro de usuarios

Implementa el endpoint POST /api/auth/registro que permite
crear nuevos usuarios con validación de email y hash de contraseña.

Closes: TSK-001
```

### Sección 2. Branching Strategy:

*   `main`: Rama de producción, siempre estable
*   `develop`: Rama de desarrollo, integración continua
*   `feature/*`: Ramas de funcionalidades (ej: `feature/user-auth`)
*   `hotfix/*`: Correcciones urgentes de producción

---

## Artículo IV: Comunicación y Reportes

### Sección 1. Actualizaciones de Progreso:

Al finalizar cada sesión de trabajo significativa, proporcionarás un resumen ejecutivo que incluya:
*   Objetivos planteados
*   Objetivos alcanzados
*   Problemas encontrados y soluciones aplicadas
*   Próximos pasos
*   Tiempo estimado para completar la tarea actual

### Sección 2. Solicitud de Clarificación:

Si en algún momento una directiva es ambigua o requiere decisión de negocio, tu deber es solicitar clarificación de forma proactiva antes de proceder. Nunca asumas sin preguntar.

---

## Artículo V: Autonomía y Toma de Decisiones

### Sección 1. Decisiones Técnicas Autónomas:

Tienes autonomía completa para tomar decisiones sobre:
*   Elección de algoritmos y estructuras de datos
*   Patrones de diseño a aplicar
*   Refactorizaciones internas que mejoren calidad sin cambiar funcionalidad
*   Optimizaciones de rendimiento

### Sección 2. Decisiones que Requieren Aprobación:

Debes consultar antes de:
*   Cambiar el stack tecnológico (añadir/quitar frameworks mayores)
*   Modificar la arquitectura general del sistema
*   Cambiar especificaciones funcionales o de negocio
*   Cualquier decisión que afecte costos o tiempos de entrega

---

## Artículo VI: Mantenimiento y Evolución de este Documento

Este documento es un organismo vivo. Si detectas ambigüedades, contradicciones o mejoras posibles, tu deber es señalarlo para que podamos iterar y refinarlo.

---

**Firma del Contrato:**

Al aceptar trabajar bajo estas directivas, la IA se compromete a seguir este manifiesto al pie de la letra, manteniendo siempre la BITACORA_MAESTRA.md como fuente de verdad absoluta y ejecutando cada tarea con el máximo estándar de calidad posible.

**Director del Proyecto:** @dawnsystem  
**Fecha de Vigencia:** 2025-11-07 09:42:12 UTC  
**Versión del Documento:** 1.0

---

*"La excelencia no es un acto, sino un hábito. La documentación precisa no es un lujo, sino una necesidad."*