# AGENTS.md — Minka

Fuente común de instrucciones para agentes (Codex, Claude Code, Devin). El SRS (`SRS-PGDW-001`) es normativo; si hay conflicto, gana el SRS y se documenta en un ADR.

## Producto
**Minka** — *Todo conectado. Cada decisión trazable.* Plataforma de expedientes, flujos de aprobación y auditoría para procesos regulados. Idioma de interfaz: español (Perú).

## Antes de tocar código
1. Leer el SRS y `docs/deployment/perfil-stellar.md`.
2. Revisar la estructura existente y `docs/trazabilidad.md`.
3. Cambios pequeños y verificables; una pregunta o ADR si hay ambigüedad de seguridad, datos o despliegue.

## Stack
PHP 8.3+, Laravel 13.x, MariaDB 10.6+, Blade + Alpine.js, Pest, Laravel Pint. Si Laravel 13 no corre en el entorno, **documentar y proponer**; no sustituir en silencio.

## Capas
`app/Domain` (sin HTTP ni framework de vistas) → `app/Application` (casos de uso, transacciones) → `app/Infrastructure` (BD, archivos, correo, colas, proveedores) → `app/Http`. Servicios externos solo tras interfaces.

## Reglas inquebrantables
- Todo recurso de negocio lleva `tenant_id`; toda consulta y política lo verifica. Nunca confiar en un `tenant_id` del cliente.
- Autorización en backend siempre (Policies/Gates). Denegar por defecto.
- Sin `eval`, SQL concatenado, ejecución de código del usuario ni comandos desde el navegador.
- Versiones documentales y workflows publicados son **inmutables**.
- Archivos solo vía `DocumentStorage`; descarga por endpoint autorizado; hash por flujo.
- Auditoría con hash encadenado; nunca incluir contraseñas, tokens ni contenido íntegro.
- Sin secretos en el repo. `.env.example` solo con valores ficticios.
- No simular integraciones: sin proveedor, estado "no configurado".
- No desactivar CSRF ni autorización para pasar pruebas.

## Restricciones Stellar (resumen)
Sin procesos persistentes; cron ≥ 5 min; lotes de cola ≤ 10 y ≤ 45 s; subidas ≤ 10 MB por defecto; memoria objetivo 256 MB; cuota de inodos; despliegue por artefacto. Detalle en `docs/deployment/perfil-stellar.md`.

## Pruebas y calidad
`php tests/run.php` (núcleo, sin Composer) y, con Composer disponible, `./vendor/bin/pest` y `./vendor/bin/pint --test` antes de entregar. Pruebas obligatorias de aislamiento multi-tenant por recurso, concurrencia en tareas e idempotencia.
**No afirmar que una prueba se ejecutó sin evidencia.** Un requisito está terminado solo con lógica de backend, validaciones, pruebas, documentación y trazabilidad actualizada.

## Estilo de producto
Tono sobrio, preciso y confiable. Vocabulario: *expediente, flujo, decisión, trazabilidad, responsable*. No prometer certificaciones, cifrado en reposo ni validez legal sin evidencia (NFR-SEC-015).