@kal-elsam/kairo-runtime 0.1.0

package/repo-template/docs/ai/loop-policy.md

@@ -0,0 +1,86 @@
+# Loop Policy
+
+## Objetivo
+
+Definir límites, escalación y condiciones de salida para loops agénticos.
+
+## Límites globales
+
+| Límite | Default |
+|---|---:|
+| Repair attempts por task | 3 |
+| Archivos modificados antes de review | 8 |
+| Iteraciones sin progreso | 2 |
+| Cambios de arquitectura sin approval | 0 |
+| Cambios de DB destructivos sin approval | 0 |
+| Cambios de seguridad/auth sin approval | 0 |
+| Evals fallidas aceptables en IA | 0 críticas |
+
+## Señales de éxito
+
+Un loop puede cerrar cuando:
+
+- spec sigue vigente
+- tests relevantes pasan
+- evals relevantes pasan
+- lint/typecheck/build pasan si aplican
+- no hay issues críticos en review
+- riesgos documentados
+- humano aprueba si el impacto es alto
+
+## Señales de fallo
+
+Detener y escalar si:
+
+- se alcanza el máximo de repair attempts
+- el agente repite el mismo cambio
+- aparecen errores nuevos no relacionados
+- aumenta el scope
+- se modifican capas no previstas
+- falla seguridad/auth/data/infra
+- evals degradan comportamiento anterior
+- el modelo reporta baja confianza
+
+## Model routing dentro del loop
+
+### DeepSeek / económico
+
+Puede ejecutar:
+
+- intake
+- task breakdown
+- scaffolding
+- tests simples
+- repair attempts 1-2
+- documentación base
+- extracción de contexto
+
+No puede aprobar:
+
+- arquitectura
+- seguridad
+- auth/pagos
+- DB destructiva
+- aceptación final crítica
+- cambios productivos de alto impacto
+
+### Modelo fuerte
+
+Debe intervenir para:
+
+- spec review crítica
+- arquitectura
+- debugging complejo
+- security review
+- eval strategy
+- acceptance review
+
+## Rollback
+
+Si el loop degrada el sistema:
+
+1. Detener ejecución.
+2. Reportar diff.
+3. Identificar último estado válido.
+4. Proponer rollback.
+5. Esperar aprobación humana si hay cambios destructivos.

package/repo-template/docs/ai/loops.md

@@ -0,0 +1,95 @@
+# Loop Engineering
+
+## Objetivo
+
+Definir ciclos controlados de trabajo agéntico para que el agente no dependa de prompts manuales en cada paso.
+
+Loop Engineering no significa dejar que el agente itere sin control. Significa diseñar:
+
+- estado inicial
+- objetivo
+- ciclo permitido
+- herramientas permitidas
+- intentos máximos
+- presupuesto de costo/tokens
+- señales de éxito
+- señales de fallo
+- escalación
+- logs
+- rollback
+- aprendizaje documentado
+
+## Relación con el harness
+
+```txt
+Harness Engineering = infraestructura de control
+Loop Engineering    = ciclos de ejecución, reparación y aprendizaje dentro de esa infraestructura
+```
+
+## Modelo base
+
+```txt
+Plan → Execute → Observe → Evaluate → Repair → Learn → Repeat
+```
+
+## Loop de feature
+
+```txt
+Spec approved
+→ select next task
+→ write failing test
+→ implement minimum change
+→ run test
+→ repair if needed
+→ run validation
+→ review
+→ checkpoint
+```
+
+## Loop de bug
+
+```txt
+Bug report
+→ reproduce
+→ isolate cause
+→ write regression test
+→ fix
+→ run test
+→ repair if needed
+→ run full validation
+→ document root cause
+```
+
+## Loop de IA
+
+```txt
+Failed conversation/eval
+→ classify failure
+→ identify prompt/tool/context issue
+→ propose minimal change
+→ run evals
+→ compare baseline
+→ accept/revert
+→ document learning
+```
+
+## Loop de documentación
+
+```txt
+Architecture/spec/code change
+→ detect stale docs
+→ update docs
+→ check contradictions
+→ update decision log
+→ checkpoint
+```
+
+## Regla central
+
+```txt
+No autonomous loop without boundaries.
+No repair loop without max attempts.
+No learning loop without evals.
+No production loop without observability.
+No critical loop without human approval.
+```

package/repo-template/docs/ai/maintainability-gates.md

@@ -0,0 +1,26 @@
+# Maintainability Gates
+
+## Reglas
+
+- Preferir cambios pequeños y localizados.
+- No mezclar refactor + feature + bugfix.
+- No duplicar lógica de dominio.
+- No introducir abstracciones prematuras.
+- No crear helpers genéricos sin casos reales.
+- No modificar arquitectura sin ADR.
+- No aumentar acoplamiento innecesario.
+- No cambiar contratos públicos sin tests.
+- No esconder errores con catch silencioso.
+- No usar any/unknown sin justificación en TypeScript.
+
+## Checklist
+
+- [ ] cumple el spec
+- [ ] diff mínimo
+- [ ] nombres claros
+- [ ] no hay dead code
+- [ ] no hay duplicación innecesaria
+- [ ] no hay cambios no relacionados
+- [ ] tests cubren comportamiento
+- [ ] diseño escalable
+- [ ] mantenible por otro humano/agente

package/repo-template/docs/ai/memory.md

@@ -0,0 +1,71 @@
+# Memory
+
+## Objetivo
+
+Definir cómo se maneja memoria persistente del proyecto y cuándo Engram debe intervenir.
+
+## Fuentes
+
+| Fuente | Rol |
+|---|---|
+| Repo | Fuente primaria |
+| AGENTS.md | Instrucciones universales |
+| docs/ai | Documentación técnica |
+| docs/specs | Intención/versionado de features |
+| Engram | Memoria/indexación externa |
+| Graphify | Grafo contextual externo |
+
+## Qué guardar en Engram
+
+Guardar:
+
+- Decisiones de arquitectura y su razonamiento, no solo el resultado.
+- Bugs recurrentes y su causa raíz.
+- Convenciones descubiertas que no estaban documentadas.
+- Aprendizajes de retrospectivas de loops (`docs/ai/loop-log.md`).
+- Enfoques descartados y por qué se descartaron.
+- Contexto de decisiones de modelo/routing que resultaron caras o incorrectas.
+
+No guardar:
+
+- Secrets, tokens, credenciales o datos personales.
+- Volcados completos de código fuente; el repo ya es la fuente.
+- Output de debug efímero sin valor de largo plazo.
+- Cualquier cosa que ya esté documentada en `AGENTS.md` o `docs/ai/`. No dupliques la fuente de verdad.
+
+## Cuándo buscar memoria
+
+Buscar en Engram antes de:
+
+- Iniciar una tarea no trivial o una spec `standard`/`complex`.
+- Diagnosticar un bug que "se siente familiar".
+- Proponer una decisión de arquitectura o convención nueva.
+- Retomar trabajo después de una compactación de contexto o nueva sesión.
+- Repetir una tarea de loop (ver `docs/ai/loop-retrospective.md`).
+
+No es necesario buscar memoria para:
+
+- Cambios triviales (typos, formato, comentarios).
+- Tareas ya completamente especificadas en una spec activa.
+
+## Cuándo el repo gana sobre la memoria externa
+
+```txt
+Current user instruction
+→ AGENTS.md
+→ docs/ai/
+→ docs/specs/
+→ Engram (memoria)
+→ Graphify (grafo)
+```
+
+Reglas explícitas:
+
+- Si Engram contradice `AGENTS.md` o `docs/ai/`, gana el archivo del repo. Actualizar o descartar la memoria obsoleta.
+- Si Engram sugiere una convención que el código actual ya no sigue, verificar el código primero: la memoria puede estar desactualizada.
+- Si Graphify contradice código o documentación, reportar la discrepancia y regenerar el grafo; no editar el grafo a mano.
+- Ninguna memoria externa autoriza saltarse SDD, TDD, evals o aprobación humana.
+
+## Registro de decisiones
+
+Las decisiones importantes deben quedar trazables en `docs/ai/decision-log.md` o un ADR, no solo en Engram. Engram indexa; el repo certifica.

package/repo-template/docs/ai/model-policy.md

@@ -0,0 +1,105 @@
+# Model Policy
+
+## Objetivo
+
+Definir qué tipo de modelo debe ejecutar cada clase de tarea.
+
+El harness debe funcionar con cualquier proveedor: DeepSeek, OpenAI/Codex, Claude, Gemini, modelos locales u otros modelos vía Gentle AI/OpenRouter.
+
+## Principio
+
+```txt
+Use the cheapest model that can safely complete the task.
+Escalate when ambiguity, risk, architecture, security or multi-file reasoning increases.
+```
+
+## Clases de modelos
+
+| Clase | Uso recomendado |
+|---|---|
+| Economic | Scaffolding, docs, tests simples, tareas mecánicas |
+| Standard | Implementación normal, refactors moderados, análisis local |
+| Strong | Arquitectura, debugging complejo, specs críticas, review |
+| Specialist | Seguridad, performance, evals, RAG, data, infra |
+| Local/private | Análisis sensible, privacidad, preprocesamiento |
+
+## Modelos económicos
+
+Ejemplos: DeepSeek u otros modelos de bajo costo.
+
+Usar para:
+
+- scaffolding
+- task breakdown
+- documentación base
+- generación de tests simples
+- extracción de contexto
+- refactors mecánicos
+- limpieza de archivos
+- primeras hipótesis de debugging
+
+No usar sin revisión para:
+
+- decisiones arquitectónicas críticas
+- seguridad
+- auth/payment/data loss
+- cambios de DB sin migration plan
+- specs críticas de negocio
+- debugging multiarchivo de alto riesgo
+- cierre final de cambios importantes
+
+## Modelos fuertes
+
+Usar para:
+
+- arquitectura
+- diseño de specs críticas
+- revisión de seguridad
+- debugging complejo
+- razonamiento multiarchivo
+- diseño de evals complejas
+- aceptación final de cambios críticos
+
+## Escalation policy
+
+Escalar a modelo fuerte o humano si:
+
+- hay contradicciones entre docs y código
+- el cambio afecta auth, pagos, datos, seguridad o infra
+- hay más de 5 archivos críticos involucrados
+- el agente propone nueva arquitectura
+- tests/evals fallan repetidamente
+- el modelo reporta baja confianza
+- hay riesgo de pérdida de datos
+- se requiere decisión de producto
+
+## Regla final
+
+El modelo ejecuta. El harness controla. El humano aprueba impacto.
+
+## Loop-aware model policy
+
+Los modelos económicos pueden iterar dentro de loops solo si:
+
+- hay max attempts
+- hay tests/evals
+- el scope está definido
+- el rollback es posible
+- no hay impacto crítico
+
+Los modelos fuertes deben cerrar o revisar loops de alto impacto.
+
+## Adapter-independent model policy
+
+This policy applies regardless of where the model is used:
+
+- OpenCode
+- Cursor
+- Codex
+- Claude
+- Gemini
+- Pi
+- any future CLI or IDE agent
+
+Do not encode model safety rules only inside one adapter.
+The source must live here and be referenced by adapters.

package/repo-template/docs/ai/observability-runtime.md

@@ -0,0 +1,48 @@
+# Runtime Observability
+
+## Eventos mínimos
+
+```txt
+agent_run_started
+agent_run_finished
+loop_started
+loop_iteration
+loop_escalated
+loop_stopped
+quality_gate_failed
+quality_gate_passed
+eval_run_finished
+human_approval_required
+rollback_created
+rollback_executed
+```
+
+## Campos mínimos
+
+```txt
+run_id
+timestamp
+adapter
+agent
+model
+task
+spec
+files_changed
+commands_run
+tests_run
+evals_run
+token_estimate
+cost_estimate
+status
+risk_level
+approval_status
+```
+
+## Archivos locales
+
+```txt
+.harness/logs/runs.jsonl
+.harness/logs/evals.jsonl
+.harness/logs/quality-gates.jsonl
+.harness/logs/approvals.jsonl
+```

package/repo-template/docs/ai/provider-routing.md

@@ -0,0 +1,138 @@
+# Provider Routing
+
+## Objetivo
+
+Definir cómo enrutar tareas entre modelos/proveedores.
+
+## Matriz de routing
+
+| Tarea | Economic / DeepSeek | Strong / GPT-Claude-Gemini | Humano |
+|---|---|---|---|
+| Intake inicial | Sí | Opcional | No |
+| Spec simple | Sí | Review opcional | No |
+| Spec crítica | Borrador | Sí | Aprobación |
+| Plan técnico simple | Sí | Opcional | No |
+| Arquitectura | No | Sí | Aprobación |
+| Task breakdown | Sí | Opcional | No |
+| Tests simples | Sí | Opcional | No |
+| Tests críticos | Borrador | Sí | No |
+| Evals IA | Borrador | Sí | Aprobación si negocio |
+| Scaffolding | Sí | Opcional | No |
+| Refactor mecánico | Sí | Review | No |
+| Debugging complejo | Hipótesis | Sí | Si riesgo |
+| Security review | No | Sí | Sí si crítico |
+| Checkpoint final | No | Sí | Sí |
+
+## Gentle AI
+
+Gentle AI puede usar modelos económicos para fases de bajo riesgo.
+
+Recomendación:
+
+```txt
+DeepSeek:
+- intake
+- task breakdown
+- scaffolding
+- tests simples
+- docs base
+
+Modelo fuerte:
+- spec review
+- architecture
+- eval strategy
+- security review
+- acceptance review
+```
+
+## Codex App / Codex CLI
+
+Usar Codex para:
+
+- ejecución puntual con `AGENTS.md`
+- refactors acotados
+- generación de tests
+- revisión con skills
+- checkpoints
+
+Codex debe respetar `AGENTS.md` y skills en `.codex/skills/` cuando existan.
+
+## Cursor
+
+Usar Cursor para:
+
+- edición interactiva
+- navegación del repo
+- subagentes por fase
+- comandos de workflow
+- integración rápida con reglas del editor
+
+## Claude/Gemini
+
+Usar para:
+
+- razonamiento fuerte
+- arquitectura
+- review
+- debugging complejo
+- análisis de ambigüedad
+- redacción/refinamiento de specs críticas
+
+## Regla de costo
+
+Preferir modelo económico cuando el output sea verificable con tests/evals.  
+Preferir modelo fuerte cuando el output sea una decisión difícil de verificar automáticamente.
+
+## OpenCode + Gentle AI + DeepSeek
+
+Este es el execution path principal recomendado.
+
+```txt
+OpenCode session
+→ Gentle AI SDD/TDD workflow
+→ DeepSeek for low-risk iterations
+→ Strong model/human for critical review
+```
+
+### DeepSeek dentro del loop
+
+Permitido:
+
+- intake
+- task breakdown
+- scaffolding
+- tests simples
+- repair attempts 1-2
+- documentación base
+
+Escalar después de:
+
+- 2 intentos sin progreso
+- scope creep
+- fallo de arquitectura
+- fallo de seguridad
+- error de auth/pagos/DB/infra
+- eval crítica fallida
+
+## Provider routing is adapter-independent
+
+Model routing must not depend on one tool.
+
+The same model policy applies in:
+
+```txt
+OpenCode
+Cursor
+Codex
+Claude
+Gemini
+Pi
+```
+
+Adapter-specific syntax may change, but routing policy does not.
+
+```txt
+Economic models = low-risk, verifiable execution.
+Strong models = ambiguous, high-risk, architectural or security-sensitive work.
+Human = impact approval.
+```

package/repo-template/docs/ai/quality-gates.md

@@ -0,0 +1,48 @@
+# Quality Gates
+
+## Gates mínimos
+
+| Gate | Required | Bloqueante |
+|---|---:|---:|
+| format check | yes | yes |
+| lint | yes | yes |
+| typecheck | yes | yes |
+| unit tests | yes | yes |
+| integration tests | when applicable | yes |
+| E2E smoke | when UI/API critical | yes |
+| AI evals | when AI behavior changes | yes |
+| build | yes | yes |
+| dependency review | yes | yes |
+| secret scan | yes | yes |
+| license policy | yes | yes |
+| architecture review | high-impact | yes |
+| human approval | critical impact | yes |
+
+## Definition of Done
+
+Un cambio está listo solo si:
+
+- cumple el spec
+- no expande scope silenciosamente
+- incluye pruebas o evals relevantes
+- pasa quality gates
+- documenta tradeoffs relevantes
+- actualiza ADRs si cambia arquitectura
+- no introduce dependencias inseguras o no aprobadas
+- tiene rollback path si toca producción
+
+## Reglas
+
+```txt
+Every fixed bug must add or update a regression test.
+Every AI behavior change must add or update evals.
+Every architecture-changing decision must add or update an ADR.
+```
+
+## Spec-level quality gates
+
+| Spec level | Required gates |
+|---|---|
+| basic | lint/typecheck/relevant test or manual check |
+| standard | lint/typecheck/unit/integration/build/checkpoint |
+| complex | all standard gates + ADR/security/evals/rollback/human approval when applicable |

package/repo-template/docs/ai/rollback-runtime.md

@@ -0,0 +1,25 @@
+# Rollback Runtime
+
+## Snapshot policy
+
+Crear snapshot antes de:
+
+- loop autónomo
+- cambios multiarchivo
+- migraciones
+- cambios de auth
+- cambios de infraestructura
+- cambios IA productivos
+- actualizaciones de dependencias
+
+## Git policy
+
+Antes de cambios grandes:
+
+```bash
+git status
+git diff
+git branch --show-current
+```
+
+Preferir worktrees/branches aisladas para agentes.

package/repo-template/docs/ai/security.md

@@ -0,0 +1,12 @@
+# Security
+
+## Reglas no negociables
+
+- No commitear secretos.
+- No exponer tokens en logs.
+- No copiar valores reales de `.env`.
+- Validar input en fronteras de sistema.
+- Validar response de APIs externas.
+- Aplicar principio de mínimo privilegio.
+- Revisar authz además de authn.
+- Documentar riesgos de seguridad en specs.