ozali 0.1.0

package/skill/SKILL.md

@@ -0,0 +1,396 @@
+---
+name: ozali
+description: Skill base/bootstrap interactiva que diagnostica el repositorio, valida la fuente de verdad del proyecto (AI.md/.ai o IA.md/.ia), calibra las capacidades de testing y el modo Strict TDD, y guía al usuario, paso a paso, para construir y configurar la skill `cdk` del proyecto junto con su estructura de agentes y subagentes. Úsala cuando el usuario quiera "diagnosticar el proyecto", "preparar/configurar cdk", "calibrar el proyecto", "generar la estructura de agentes", "arrancar ozali desde cero" o invoque "ozali".
+---
+
+# Skill: ozali
+
+`ozali` es la skill **base/bootstrap**. Su único trabajo es llevar al usuario por una
+experiencia interactiva que termina **generando y configurando la skill `cdk`** del proyecto,
+usando como fuente de verdad la documentación global del repo (`AI.md` + `.ai/`, o su variante
+`IA.md` + `.ia/`) y la **calibración real de testing** del proyecto.
+
+`ozali` **diagnostica, calibra y planifica**. `cdk` **ejecuta** (genera código respetando reglas).
+No mezcles responsabilidades: `ozali` nunca escribe código de negocio del proyecto; solo
+produce documentación, la calibración, el plan y los artefactos de la skill `cdk`.
+
+> **Regla de oro:** nada se ejecuta sin aprobación del usuario en los puntos marcados como
+> 🛑 **GATE**. Si el usuario no aprueba, detente y pregunta.
+
+> **Memoria de equipo (Engram):** `ozali` y `cdk` operan en modo **híbrido** — conservan los
+> documentos legibles por humanos **y** espejan los artefactos clave a Engram para búsqueda y
+> acumulación de conocimiento. El histórico de documentación se mantiene **aislado del repo
+> principal** (repo de conocimiento aparte). Reglas en
+> [`references/engram-convention.md`](references/engram-convention.md) y
+> [team-history](../docs/team-history.md).
+
+---
+
+## Flujo general (7 fases)
+
+```
+Fase 0    Identidad y registro          → quién corre ozali (git/sesión)
+Fase 1    Detección fuente de verdad    → ¿existe AI.md/.ai o IA.md/.ia?
+Fase 2    Generación conocimiento       → si falta, evaluar el proyecto y generar AI.md + .ai/
+Fase 3    Validación + ajustes          → ¿coincide con la estructura real? ajustes mínimos
+Fase 3.5  Calibración testing + TDD     → detectar runner/capas/cobertura y resolver Strict TDD
+Fase 4    Diseño de agentes (cdk)       → 8 roles + esquema de responsabilidades
+Fase 5    🛑 GATE: plan de cdk          → presentar plan, esperar aprobación
+Fase 6    Generar cdk                   → skill cdk + subagentes reales + wiring TDD/Engram
+```
+
+Al final de **cada corrida** se escriben los **3 documentos** de registro (ver
+[Documentación de corrida](#documentación-de-corrida)).
+
+---
+
+## Fase 0 — Identidad y registro
+
+Antes de nada, identifica **quién** está corriendo `ozali` para el encabezado del registro.
+
+1. Intenta obtener identidad de la sesión activa (correo/cuenta).
+2. Complementa con la cuenta de git del repo:
+   - `git config user.name`
+   - `git config user.email`
+   - rama actual: `git rev-parse --abbrev-ref HEAD`
+   - **commit actual** (para trazabilidad del histórico aislado): `git rev-parse --short HEAD`
+3. Construye el bloque de identidad que se usará en todos los documentos:
+
+```
+Autor: <user.name> <<user.email>>
+Sesión: <correo de sesión si está disponible>
+Rama: <branch>
+Commit: <short SHA>
+Generado por: ozali
+Fecha/Hora: <yyyy-mm-dd HH:MM:SS> (zona local)
+```
+
+Guarda estos valores; se reutilizan en Fase 6 y en la documentación.
+
+---
+
+## Fase 1 — Detección de la fuente de verdad
+
+Busca en la raíz del repositorio, aceptando **ambas nomenclaturas**:
+
+| Concepto        | Variante A | Variante B |
+|-----------------|------------|------------|
+| Documento guía  | `IA.md`    | `AI.md`    |
+| Carpeta dotted  | `.ia/`     | `.ai/`     |
+
+- Si encuentras **cualquiera** de las dos variantes → **ruta FOUND** (ve a Fase 3).
+- Si **no** encuentras ninguna → **ruta GENERATE** (ve a Fase 2).
+
+Registra cuál variante usa el proyecto. Esa será la nomenclatura canónica de aquí en adelante;
+**no la cambies** si el proyecto ya tiene una.
+
+Inspecciona el contenido encontrado y trátalo como **fuente de verdad** provisional. Estructura
+esperada dentro de la carpeta dotted:
+
+```
+.ai/ (o .ia/)
+  agents/      → identidades existentes (frontend, designer, reviewer, tester, ...)
+  context/     → architecture.md, coding-standards.md, tech-stack.md
+  knowledge/   → learning-notes.md, README.md
+  workflows/   → feature.md, bugfix.md, hotfix.md, refactor.md
+```
+
+---
+
+## Fase 2 — Generación de la base de conocimiento (evaluando el proyecto)
+
+Solo si la Fase 1 no encontró nada. **No se descarga nada de fuentes externas:** la fuente
+de verdad se construye **evaluando el proyecto real**. La estructura canónica, las reglas
+de generación y las diferencias frontend/backend están en
+[`references/knowledge-blueprint.md`](references/knowledge-blueprint.md).
+
+Pasos:
+1. **Detecta frontend o backend** (señales del blueprint §1; si hay ambigüedad, pregunta).
+2. **Inspecciona el proyecto real** (blueprint §2): estructura, stack y versiones leídas de los
+   manifiestos, comandos de build/test, patrones de arquitectura, convenciones observadas,
+   configuración por entorno y estado real de pruebas.
+3. **Genera la carpeta dotted** (`.ai/` por defecto) con la estructura canónica del blueprint §3.
+4. **Genera el documento guía** (`AI.md`) como "Project Brain" según el blueprint §4.
+5. **Regla anti-invención:** todo lo que no se pueda derivar del código real se marca como
+   `<!-- PROVISIONAL: confirmar con el usuario -->` o se pregunta. Nunca inventes reglas de
+   negocio, módulos, comandos ni versiones.
+6. **Nomenclatura del repo real:** nada de nombres genéricos de plantilla.
+
+Lo generado es **provisional**: continúa a Fase 3 y valídalo igual que una fuente encontrada.
+
+---
+
+## Fase 3 — Validación contra la estructura real + ajustes mínimos
+
+La fuente de verdad es **provisional** hasta validarla contra el código real.
+
+1. Lee la estructura real del proyecto (p. ej. `src/app/...`, módulos, servicios).
+2. Compara contra lo que afirma la fuente de verdad (`context/architecture.md`, `tech-stack.md`).
+3. Marca **discrepancias** (carpetas/módulos que existen y no están documentados, o viceversa).
+4. Aplica **solo ajustes mínimos** necesarios para una primera iteración coherente.
+5. Todo cambio mayor se anota como **propuesta** para el documento 3 (mejoras), no se aplica.
+
+Resultado: una fuente de verdad **validada** y el inventario de hitos/discrepancias que alimenta
+el documento 1 (análisis).
+
+---
+
+## Fase 3.5 — Calibración de testing + Strict TDD
+
+> Esta fase es lo que hace que `cdk` sepa **si puede exigir test-first**. Sin ella, el TDD es un
+> deseo; con ella, es un contrato calibrado contra lo que el proyecto realmente soporta. Catálogo
+> completo de detección en [`references/calibration-blueprint.md`](references/calibration-blueprint.md).
+
+1. **Detecta las capacidades de testing reales** (blueprint §1): runner(s) de tests, capas
+   disponibles (unit / integración / e2e), comando(s) exactos, linter, type-checker, formatter,
+   y **cobertura/estado real** (conteo de archivos de prueba, no supuestos).
+2. **Resuelve `strict_tdd`** con esta tabla de decisión (blueprint §2):
+
+   | Señal encontrada | `strict_tdd` |
+   |---|---|
+   | Marcador/config explícito del proyecto (`.ai/context/tech-stack.md`, CI, convención de equipo) | usa ese valor |
+   | Sin marcador, pero **existe runner de tests** | **`true`** (default: test-first) |
+   | **No hay runner de tests** | `false` + explica que no está disponible y qué falta |
+
+3. **Persiste la calibración** como artefacto `testing-capabilities`:
+   - en la fuente de verdad: sección **"Testing & TDD"** dentro de `.ai/context/tech-stack.md`
+     (tabla de capacidades + `strict_tdd` + comandos verdes);
+   - en **Engram** (cuando esté disponible): `cdk/_project/testing-capabilities`
+     (ver [`references/engram-convention.md`](references/engram-convention.md)).
+
+4. **Si falta información** para fijar el umbral de "verde" (qué comando corre las pruebas, qué
+   cuenta como pasar), **pregunta al usuario** lo mínimo. No inventes comandos ni umbrales.
+
+El resultado de esta fase entra al plan del GATE (Fase 5) como la sección **"Calibración de
+pruebas"** y condiciona el ciclo `executioners ⇄ tester` de `cdk` (Fase 6).
+
+---
+
+## Fase 4 — Diseño de agentes y subagentes para `cdk`
+
+A partir del conocimiento consolidado, diseña la estructura de agentes de `cdk`. El catálogo
+canónico de los **8 roles**, su esquema de responsabilidades, entradas/salidas y mapeo a la
+fuente de verdad está en [`references/agents-blueprint.md`](references/agents-blueprint.md):
+
+1. **project-owner** — visión, reglas y criterios de aceptación; qué se puede/no tocar.
+2. **project-manager** — descompone la solicitud en tareas, estados y dependencias; aplica workflows.
+3. **project-analyzer** — analiza código e impacto; produce el documento 1 (análisis + hitos).
+4. **project-orchestrator** — enruta el trabajo entre subagentes e integra resultados.
+5. **executioners** — implementan los cambios de código respetando estándares y arquitectura.
+6. **project-proposer** — propone alternativas y mejoras con grados de relevancia (documento 3).
+7. **project-documenter** — genera y mantiene los documentos `.md` con encabezado de identidad.
+8. **tester** — valida con pruebas (unit/e2e) y reporta resultados contra criterios de aceptación.
+
+Si la fuente de verdad **no** aporta suficiente para definir una identidad (responsabilidad,
+herramientas permitidas, límites), **pregunta al usuario** lo mínimo necesario. No inventes
+reglas de negocio.
+
+---
+
+## Fase 5 — 🛑 GATE: presentar el plan de `cdk`
+
+> [!IMPORTANT]
+> **Es IMPERATIVO presentar el plan de trabajo como mensaje visible y completo al usuario
+> ANTES de pedir cualquier aprobación.** El plan debe ir en el cuerpo del mensaje final
+> (markdown completo: tablas, estructura de archivos, subagentes), nunca solo resumido
+> dentro de una pregunta o herramienta de confirmación. Si el plan no se presentó de forma
+> visible, el GATE **no es válido**: preséntalo primero y vuelve a pedir aprobación.
+
+Presenta al usuario un plan claro y conciso que incluya:
+
+- Nombre canónico de la fuente de verdad detectada y variante (`AI.md/.ai` vs `IA.md/.ia`).
+- Resumen de discrepancias y ajustes mínimos aplicados en Fase 3.
+- **Calibración de pruebas** (Fase 3.5): capacidades detectadas + `strict_tdd: true|false` + comandos verdes.
+- Los 8 subagentes a crear (ruta, responsabilidad de una línea, herramientas).
+- Estructura de archivos que generará `cdk`.
+- La ruta de documentación, nomenclatura de logs y **destino del histórico** (repo de conocimiento aislado).
+
+**Detente y espera aprobación explícita.** No generes `cdk` hasta recibir el "ok".
+
+---
+
+## Fase 6 — Generar la skill `cdk`
+
+Solo tras la aprobación de la Fase 5. Genera:
+
+1. `.claude/skills/cdk/SKILL.md` — orquestador de `cdk`. Debe:
+   - declarar en el frontmatter una **description con triggers ricos** (verbos y sustantivos
+     que el usuario usaría: "crea", "genera", "corrige", "refactoriza", método, clase,
+     endpoint, componente…) para mejorar la auto-invocación de la skill;
+   - declarar que ayuda a **generar código** (nuevo componente, fix de bug, análisis de impacto)
+     respetando la fuente de verdad y los estándares del proyecto;
+   - orquestar los 8 subagentes según la fase del trabajo;
+   - exigir que el análisis arranque con el **harness de verificación de estructura**
+     (punto 3 abajo) antes de planear nada;
+   - **respetar la calibración de Strict TDD** (Fase 3.5): si `strict_tdd: true`, el ciclo
+     `executioners ⇄ tester` es **test-first** (RED → GREEN → REFACTOR): se escribe la prueba que
+     falla, luego el mínimo código que la pasa, luego refactor con pruebas en verde; el GATE
+     muestra el **plan de pruebas** como sección obligatoria. Si `strict_tdd: false`, exige al
+     menos pruebas de regresión y lo deja explícito en la bitácora;
+   - definir el **formato del Plan de Acción** que ve el usuario en el GATE: tabla de
+     cambios archivo por archivo, **plan de pruebas**, riesgos con mitigación y sección
+     explícita de **"Fuera de alcance"**;
+   - **congelar el plan al aprobarse el GATE**: `02-plan-aprobado.md` se escribe en ese
+     momento (antes de tocar código) y es inmutable;
+   - soportar el **modo autónomo `--auto`** (ver [Modo autónomo (`--auto`)](#modo-autónomo---auto)):
+     `cdk` recorre el hito de punta a punta —análisis (incluida la lectura de rutas no
+     contempladas), ejecución— **sin prompts**, con el **único alto en el 🛑 GATE**; debe
+     incluir una sección breve de **permisos** con los **dos perfiles** —base del modo normal
+     (lectura + comandos + Python + fetch, confirmando ediciones) y bypass de `--auto`— que
+     apunte a [`references/permissions-bypass.md`](references/permissions-bypass.md) (config de
+     Claude Code y opencode) y **verificar/recordar** esa configuración al iniciar;
+   - incluir una sección de **Gotchas verificados** (hallazgos reales del repo) y una de
+     **Troubleshooting** (síntoma → causa/fix);
+   - **por cada solicitud/hito del usuario**, generar la documentación por hito en
+     `.ozali/docs/cdk/<hito>/` (ver [Documentación por hito de `cdk`](#documentación-por-hito-de-cdk)),
+     que son **6 documentos**: incluye la **bitácora de ejecución** (`05`) que se escribe DURANTE
+     el ciclo y el **uso de tokens** (`06`) que se escribe al cierre;
+   - **espejar a Engram** los artefactos clave del hito (análisis, plan aprobado, bitácora,
+     resumen técnico, `state`) con naming determinista, según
+     [`references/engram-convention.md`](references/engram-convention.md), y al **iniciar** un
+     hito hacer `mem_search` del proyecto/hito para recuperar contexto previo;
+   - en el **cierre del hito**, invocar la skill **`ozali-commit`** para generar el commit
+     summary (feature→`feat`, bugfix→`fix`, hotfix→`hotfix`, refactor→`refactor`; scope = módulo
+     del hito). El GATE del mensaje es independiente del GATE del plan.
+2. `.claude/agents/<rol>.md` — un subagente real por cada uno de los 8 roles, con su system
+   prompt y herramientas, según [`references/agents-blueprint.md`](references/agents-blueprint.md).
+3. `.claude/skills/cdk/verify-structure.mjs` — **harness del analista**: script Node sin
+   dependencias (Node 16+) adaptado a la estructura real del proyecto. Verifica paquetes/capas
+   esperados, localiza clases clave, reporta discrepancias doc↔código y, con `--grep <palabra>`,
+   lista archivos existentes relacionados (**reutilización antes de crear**). Genéralo a partir
+   del esqueleto parametrizado de [`references/harness-template.md`](references/harness-template.md)
+   con valores de la fuente de verdad validada en Fase 3 — nunca de supuestos — y **ejecútalo
+   para validarlo** antes de cerrar la fase (template §4).
+4. Cualquier otra referencia/plantilla que `cdk` necesite.
+
+> La fuente de verdad sigue siendo **únicamente** `AI.md` + `.ai/` — `cdk` la referencia,
+> **no la duplica** dentro de la skill. No copies `context/` ni `workflows/` a
+> `.claude/skills/cdk/`.
+
+Tras generar, escribe los 3 documentos de la corrida y resume al usuario qué quedó creado y
+cómo invocar `cdk`.
+
+---
+
+## Documentación por hito de `cdk`
+
+Esto lo produce la skill **`cdk`** (no `ozali`), una vez por **cada solicitud/hito** del usuario.
+Es responsabilidad del subagente `project-documenter`. `ozali` debe **cablear este comportamiento**
+dentro del `SKILL.md` de `cdk` que genera en la Fase 6.
+
+- **Ruta base:** `.ozali/docs/cdk/` — **gitignored en el repo principal** y sincronizada al repo
+  de conocimiento aislado (ver [team-history](../docs/team-history.md)).
+- **Carpeta por hito:** `<hito>/` — slug corto y descriptivo (ej. `alta-componente-cobranza`).
+  Si ya existe, agrega sufijo `-2`, `-3`, …
+- **Contenido (6 `.md`):**
+  1. `01-prompt-entrada.md` — el **prompt de entrada** del usuario, **textual**, con timestamp.
+     *Se escribe al inicio del hito.*
+  2. `02-plan-aprobado.md` — el **plan aprobado**. *Se congela AL APROBAR el GATE, antes de tocar
+     código; es inmutable.*
+  3. `03-resumen-tecnico.md` — **resumen técnico** (archivos tocados, decisiones, impacto). *Al cierre.*
+  4. `04-resumen-usuario.md` — **resumen para el usuario**, entendible y con **casos de uso
+     sencillos explicados** (sin jerga técnica). *Al cierre.*
+  5. `05-bitacora-ejecucion.md` — **bitácora viva del ciclo** (append-only): dudas, decisiones,
+     actualizaciones y desvíos DURANTE la ejecución. Mantiene íntegro el `02-plan-aprobado.md`.
+  6. `06-uso-tokens.md` — **uso de tokens**, al cerrar el hito. Métricas solo si el proveedor es
+     **Claude/Anthropic**; con otro proveedor deja estructura + nombre del proveedor (`N/A`).
+
+Las plantillas completas están en [`references/doc-templates.md`](references/doc-templates.md).
+Cada documento lleva el mismo encabezado de identidad (autor desde git/sesión + commit + fecha/hora).
+
+---
+
+## Memoria híbrida (Engram)
+
+`ozali` cablea en el `SKILL.md` de `cdk` un contrato de **memoria híbrida**: cada artefacto clave
+vive como **documento legible** (los 6 por hito) **y** como **espejo en Engram** (buscable,
+recuperable, acumulativo). Así la herramienta **aprende de lo que el equipo va haciendo**. Contrato
+completo (naming, llamadas inline, degradación) en
+[`references/engram-convention.md`](references/engram-convention.md).
+
+**Mínimos que `cdk` debe cablear** (resumen; el detalle y los `mem_*` exactos están en la convención):
+
+- **Al iniciar un hito** → `mem_save_prompt` (captura el prompt real una vez) + `mem_search` de
+  `cdk/{hito}/state`, `cdk/_project/testing-capabilities` y `cdk/{hito}/*` → `mem_get_observation`
+  de lo relevante. Si hay `state` con pendientes, **reanuda**; con `testing-capabilities` resuelve
+  el modo TDD.
+- **Al aprobar el GATE** → `mem_save` de `cdk/{hito}/plan-aprobado` **una sola vez** (inmutable).
+- **Durante el ciclo** → `mem_update` (upsert) de `cdk/{hito}/bitacora` y `cdk/{hito}/state` tras
+  cada transición de fase (el archivo `05` sigue siendo append-only como fuente de verdad).
+- **Al cerrar** → `mem_save` de `cdk/{hito}/resumen-tecnico` + `mem_session_summary` (solo el agente
+  top-level, nunca un subagente).
+- **Naming determinista:** `cdk/{hito}/{tipo}` (o `cdk/_project/{tipo}`), `type: architecture`,
+  `capture_prompt: false` para artefactos automáticos.
+
+**Reglas duras:** persistir **antes** del texto final del subagente; en `hybrid` el doc es la
+fuente de verdad y Engram el índice (lectura Engram-primero, docs-fallback); **la ausencia de
+Engram nunca bloquea** un hito — `cdk` degrada a modo `docs` y anota el espejo pendiente. El
+**histórico se sincroniza al repo de conocimiento aislado** con `ozali sync` (no al repo principal).
+
+---
+
+## Permisos del modo normal (sin `--auto`)
+
+Aun **sin** `--auto`, `cdk` opera con un **perfil base de permisos** orientado al análisis y la
+validación, para no interrumpirte por operaciones de diagnóstico:
+
+- **Lectura dentro del proyecto** (`Read`/`Grep`/`Glob` y Bash read-only).
+- **Ejecución de líneas de comando** (Bash/PowerShell) y **scripts de Python**.
+- **Fetch de sitios externos para lectura** (`WebFetch`/`WebSearch`).
+
+Lo que el modo normal **sí** sigue confirmando: **ediciones/escrituras de archivos** y los
+comandos destructivos (`rm -rf`, `git push`). El **🛑 GATE del plan** se mantiene igual.
+
+> Plantillas listas para copiar en [`references/permissions-bypass.md`](references/permissions-bypass.md)
+> (Claude Code §1 y opencode §2).
+
+---
+
+## Modo autónomo (`--auto`)
+
+`ozali` debe cablear en el `SKILL.md` de `cdk` un **modo autónomo** que recorre el hito **de punta
+a punta sin prompts**. La **regla del único alto** lo resume:
+
+> 🎯 **En modo `--auto` el único punto donde `cdk` se detiene a esperar al humano es el
+> 🛑 GATE del plan.** Todo lo demás —análisis, lectura de rutas no contempladas, ejecución— corre
+> sin interrupciones.
+
+- **Invocación:** el usuario antepone el flag, p. ej. `cdk --auto agrega validación de RFC en
+  cotización`. `cdk` reconoce `--auto` en cualquier posición; el inicio es la forma canónica.
+- **El GATE (único alto):** el plan se presenta y se espera aprobación, **siempre**.
+- **Después del GATE:** ejecuta de punta a punta dentro del alcance aprobado. Si surge algo
+  **fuera** del plan, se **detiene y pregunta** (y lo registra en la bitácora `05`).
+- **Permisos: una skill NO puede auto-otorgarse permisos.** El bypass se configura a nivel de
+  **entorno** (settings/flags). `cdk`, al detectar `--auto`, **verifica/recuerda** la config de
+  [`references/permissions-bypass.md`](references/permissions-bypass.md).
+- **Registro:** que el hito corrió en `--auto` (y con qué bypass) se anota en `05-bitacora-ejecucion.md`.
+
+---
+
+## Documentación de corrida
+
+Cada corrida de `ozali` produce **3 documentos `.md`** en una carpeta por corrida. Plantillas en
+[`references/doc-templates.md`](references/doc-templates.md).
+
+- **Ruta base:** `.ai/ozali/logs/` (la corrida del bootstrap puede vivir junto al cerebro; el
+  histórico **por hito** de `cdk` es el que se aísla al repo de conocimiento).
+- **Carpeta de corrida:** `ozali.log_{{yy-mm-dd}}/` (sufijo `-2`, `-3`, … si ya existe del día).
+- **Contenido:**
+  1. `01-analisis.md` — análisis del proyecto e **hitos de importancia**.
+  2. `02-plan.md` — el **plan ejecutado**.
+  3. `03-mejoras.md` — **mejoras posibles** a la skill y al proyecto, cada una con su **grado de
+     relevancia** (Alta/Media/Baja).
+
+**Encabezado obligatorio** al inicio de cada documento, con la identidad de Fase 0 y la hora:
+
+```
+---
+ozali.log: 26-06-27
+documento: 01-analisis
+Autor: <user.name> <<user.email>>
+Sesión: <correo de sesión>
+Rama: <branch>
+Commit: <short SHA>
+Creado: 2026-06-27 14:32:07 (local)
+---
+```

package/skill/references/agents-blueprint.md

@@ -0,0 +1,138 @@
+# Blueprint de agentes y subagentes para `cdk`
+
+Catálogo canónico de los **8 roles** que `cdk` materializa como **subagentes reales** de
+Claude Code (`.claude/agents/<rol>.md`). Cada subagente tiene un system prompt enfocado,
+herramientas acotadas y un contrato de entrada/salida.
+
+> Nombres canónicos (corrigen typos del brief): `project-orchestrator` (no "orchestator") y
+> `executioners` (no "excecutioners").
+
+---
+
+## Esquema de responsabilidades (vista rápida)
+
+| Rol                  | Decide | Produce | Lee de la fuente de verdad |
+|----------------------|--------|---------|----------------------------|
+| project-owner        | Qué se puede/no tocar; criterios de aceptación | Veredicto de alcance | `AI.md`, módulos de negocio |
+| project-manager      | Descomposición y orden de tareas | Backlog de tareas con estados | `.ai/workflows/*` |
+| project-analyzer     | Impacto y riesgos del cambio | **Doc 1**: análisis + hitos | `.ai/context/architecture.md` |
+| project-orchestrator | Quién ejecuta y en qué orden | Resultados integrados | todo el `.ai/` |
+| executioners         | Cómo se implementa | Código + diffs | `.ai/context/coding-standards.md` |
+| project-proposer     | Alternativas y mejoras | **Doc 3**: mejoras con relevancia | `.ai/knowledge/*` |
+| project-documenter   | Forma/registro de la salida | **Docs 01-06 por hito** con encabezado | `references/doc-templates.md` |
+| tester               | Si cumple criterios | Reporte de pruebas | `.ai/agents/tester.md`, `.ai/workflows/*` |
+
+Flujo típico de una tarea en `cdk`:
+
+```
+owner (alcance) → manager (tareas) → analyzer (impacto, Doc1)
+   → orchestrator → executioners (código) ⇄ tester (pruebas)
+   → proposer (Doc3) → documenter (Docs 01-06 por hito)
+```
+
+---
+
+## Definiciones por rol
+
+Para cada subagente, `cdk` debe generar un `.claude/agents/<rol>.md` con frontmatter
+`name`, `description` (cuándo invocarlo) y herramientas, más el system prompt.
+
+### 1. project-owner
+- **Misión:** custodiar la visión y las reglas del proyecto; autorizar o rechazar el alcance.
+- **Responsabilidades:** define qué módulos/archivos son sensibles y no deben tocarse sin
+  cuidado; fija criterios de aceptación; resuelve conflictos de prioridad.
+- **Entrada:** solicitud del usuario + fuente de verdad. **Salida:** veredicto de alcance
+  (aprobado/ajustado/rechazado) con justificación.
+- **Herramientas:** solo lectura (Read, Grep, Glob). No edita código.
+
+### 2. project-manager
+- **Misión:** convertir la solicitud aprobada en un plan de tareas accionable.
+- **Responsabilidades:** descompone en tareas con dependencias y estados; selecciona el
+  workflow correcto (`feature`/`bugfix`/`hotfix`/`refactor`); define el orden.
+- **Entrada:** veredicto del owner. **Salida:** backlog ordenado.
+- **Herramientas:** lectura + gestión de tareas. No edita código de negocio.
+
+### 3. project-analyzer
+- **Misión:** entender el código existente y el impacto del cambio. *No se planea lo que
+  no se ha entendido: primero el terreno, después el plano.*
+- **Responsabilidades:** **primero, SIEMPRE**, ejecuta el harness
+  `node .claude/skills/cdk/verify-structure.mjs --grep <palabra-clave>` — su salida es la
+  **base factual** del análisis (estructura real, clases clave, discrepancias doc↔código,
+  candidatos a **reutilización antes de crear**). Luego mapea dependencias, identifica
+  **hitos de importancia** y riesgos, superficies afectadas y contratos en riesgo. Marca
+  los riesgos **🔴 BLOQUEANTES** que detienen el flujo hasta resolverse. Es el autor del
+  **Documento 1 (análisis)**.
+- **Entrada:** tarea. **Salida:** informe de impacto + hitos (+ preguntas abiertas al usuario).
+- **Herramientas:** solo lectura (Read, Grep, Glob) + ejecución del harness (Bash/PowerShell
+  acotado a `node verify-structure.mjs`).
+
+### 4. project-orchestrator
+- **Misión:** enrutar el trabajo entre subagentes e integrar resultados.
+- **Responsabilidades:** decide qué subagente actúa y en qué orden; gestiona iteraciones
+  executioners ⇄ tester; consolida la salida final. **Alimenta al `project-documenter`** con
+  los eventos del ciclo (dudas, decisiones, desvíos) para la bitácora `05`.
+- **Modo `--auto`:** si el hito se invocó con `--auto`, recorre el hito de punta a punta
+  **sin prompts** —incluida la **lectura de rutas no contempladas** durante el análisis y la
+  ejecución post-GATE— con el **único alto en el 🛑 GATE del plan**. Si algo cae **fuera de
+  alcance**, se **detiene y pregunta** (y lo registra en la bitácora). El bypass de permisos
+  se configura a nivel de entorno (settings/flags), no desde la skill: verifica/recuerda la
+  config de `references/permissions-bypass.md` (Claude Code: `--dangerously-skip-permissions`
+  o `additionalDirectories`+`acceptEdits`; opencode: `external_directory: "allow"` / `permission: "allow"`).
+- **Entrada:** backlog + análisis + flag de modo. **Salida:** resultado integrado y trazable.
+- **Herramientas:** orquestación (puede invocar otros subagentes). No edita directamente.
+
+### 5. executioners
+- **Misión:** implementar los cambios de código.
+- **Responsabilidades:** escriben/editan código respetando arquitectura y
+  `coding-standards.md`; crean componentes, corrigen bugs, aplican refactors acotados.
+- **Entrada:** tarea con criterios. **Salida:** diffs/código.
+- **Herramientas:** edición de código (Read, Edit, Write) + ejecución acotada.
+
+### 6. project-proposer
+- **Misión:** proponer alternativas y mejoras, sin ejecutarlas.
+- **Responsabilidades:** genera opciones con trade-offs; lista mejoras al proyecto y a la
+  skill con **grado de relevancia (Alta/Media/Baja)**. Es el autor del **Documento 3 (mejoras)**.
+- **Entrada:** análisis + resultado. **Salida:** propuestas priorizadas.
+- **Herramientas:** solo lectura.
+
+### 7. project-documenter
+- **Misión:** producir y mantener la documentación de cada hito.
+- **Responsabilidades:** por **cada solicitud/hito** del usuario, genera los **6 documentos
+  por hito** con el **encabezado de identidad**, en `.ozali/docs/cdk/<hito>/`; el primero
+  captura el **prompt de entrada** textual; consolida las salidas de
+  owner/analyzer/executioners/proposer; **mantiene viva la bitácora** durante el ciclo y
+  cierra con el **uso de tokens**.
+- **Entrada:** prompt del usuario + salidas de los demás roles + eventos del ciclo (dudas,
+  decisiones, desvíos). **Salida:** `01-prompt-entrada.md`, `02-plan-aprobado.md`,
+  `03-resumen-tecnico.md`, `04-resumen-usuario.md` (este último entendible y con casos de
+  uso sencillos explicados), `05-bitacora-ejecucion.md` y `06-uso-tokens.md`.
+- **Momento clave:**
+  - `01-prompt-entrada.md` se escribe **al inicio del hito**.
+  - `02-plan-aprobado.md` se escribe **al aprobarse el GATE, antes de tocar código**, y es
+    **inmutable**: deja constancia de qué se acordó.
+  - `05-bitacora-ejecucion.md` es **append-only DURANTE el ciclo**: registra cronológicamente
+    dudas, decisiones, actualizaciones, desvíos y preguntas al usuario (con su respuesta).
+    Cualquier diferencia entre lo planeado y lo ejecutado vive aquí, **nunca** editando el
+    plan congelado.
+  - `03-resumen-tecnico.md`, `04-resumen-usuario.md` y `06-uso-tokens.md` se escriben **al
+    cierre**. El `06` solo rellena métricas si el proveedor es **Claude/Anthropic** (fuente
+    `/cost`); con otro proveedor deja la estructura + nombre del proveedor y métricas `N/A`.
+- **Herramientas:** escritura de documentación (Read, Write).
+
+### 8. tester
+- **Misión:** validar que el cambio cumple los criterios de aceptación.
+- **Responsabilidades:** ejecuta pruebas unitarias (p. ej. Karma) y/o e2e; verifica
+  regresiones; reporta resultados. Reutiliza/heredar de `.ai/agents/tester.md` si existe.
+- **Entrada:** código de executioners + criterios del owner. **Salida:** reporte de pruebas
+  (pass/fail + evidencia).
+- **Herramientas:** ejecución de pruebas (Read, Bash/PowerShell acotado).
+
+---
+
+## Preguntas a hacer al usuario si falta información
+
+Si la fuente de verdad no permite completar una identidad, pregunta solo lo mínimo:
+- ¿Qué módulos/carpetas son **intocables** o de alto riesgo? (owner)
+- ¿Qué comando(s) corren las pruebas y cuál es el umbral de "verde"? (tester)
+- ¿Hay convenciones de nombres/commits/ramas obligatorias? (manager/executioners)
+- ¿Qué define "hecho" (definition of done) para una tarea típica? (owner/tester)

package/skill/references/calibration-blueprint.md

@@ -0,0 +1,113 @@
+# Blueprint de calibración de testing + Strict TDD
+
+Se usa en la **Fase 3.5** de `ozali`. Su trabajo es averiguar **qué soporta realmente el
+proyecto en materia de pruebas** y resolver si `cdk` puede exigir **test-first** (Strict TDD).
+Nada se adivina: todo se deriva de manifiestos, configuración y conteo real de archivos.
+
+> **Regla anti-invención:** no inventes comandos de prueba, umbrales de cobertura ni runners.
+> Lo que no se pueda derivar del repo se **pregunta** al usuario o se marca `N/A`.
+
+---
+
+## 1. Qué detectar (capacidades de testing)
+
+Inspecciona el repo y arma la **tabla de capacidades**:
+
+| Aspecto | Dónde leerlo (señales) |
+|---|---|
+| **Runner(s)** de pruebas | `package.json` scripts (`test`, `test:e2e`), `jest`/`vitest`/`karma`/`mocha`/`playwright`/`cypress`; `pom.xml`/`build.gradle` (JUnit/surefire); `pyproject.toml`/`pytest.ini`/`tox.ini`; `go test`; `Cargo.toml` |
+| **Capas disponibles** | unit (junto al código / `__tests__` / `src/test`), integración, e2e (carpetas `e2e/`, `cypress/`, `playwright/`) |
+| **Comando(s) exactos** | scripts del manifiesto y wrappers (`npm test`, `pnpm test`, `mvnw test`, `pytest`, `go test ./...`) — copia el comando, no lo supongas |
+| **Cobertura** | config de coverage (`jest --coverage`, `nyc`, `jacoco`, `coverage.py`); umbral si está declarado |
+| **Linter / type-checker / formatter** | `eslint`, `biome`, `tsc --noEmit`, `ruff`/`mypy`, `golangci-lint`, `prettier`/`gofmt` |
+| **Estado real** | **cuenta** archivos de prueba reales (`*.spec.ts`, `*.test.tsx`, `*Test.java`, `test_*.py`, `*_test.go`). Reporta el número; si es ~0, dilo |
+| **CI** | `.github/workflows`, pipelines: ¿corre tests?, ¿bloquea el merge?, ¿hay gate de cobertura? |
+
+La salida de esta sección es una tabla concreta, p. ej.:
+
+```
+| Capacidad      | Valor                          |
+| -------------- | ------------------------------ |
+| Runner unit    | vitest (`pnpm test`)           |
+| Runner e2e     | playwright (`pnpm test:e2e`)   |
+| Cobertura      | sí, umbral 80% (vitest)        |
+| Type-check     | tsc --noEmit                   |
+| Linter         | eslint + prettier              |
+| Archivos test  | 142 *.spec.ts                  |
+| CI corre tests | sí, bloquea merge              |
+```
+
+---
+
+## 2. Resolver `strict_tdd`
+
+Aplica en orden; gana la primera que coincide:
+
+| Señal | `strict_tdd` | Nota |
+|---|---|---|
+| Marcador/config explícito del proyecto o convención de equipo (en `.ai/context/tech-stack.md`, CI, o el usuario lo afirma) | **usa ese valor** | la intención declarada manda |
+| Sin marcador, pero **existe runner de tests usable** | **`true`** | default seguro: test-first |
+| **No hay runner de tests** (o no corre) | **`false`** | explica que TDD estricto no está disponible y qué falta para habilitarlo |
+
+> "Existe runner usable" = hay un comando de pruebas que **corre sin error de configuración**.
+> Si hay runner declarado pero roto, trátalo como `false` y anótalo como riesgo/mejora.
+
+Cuando falte el **umbral de verde** (qué comando corre y qué cuenta como pasar), **pregunta**:
+- ¿Qué comando corre las pruebas y cuál es el umbral de "verde"?
+- ¿La cobertura es un gate o solo informativa?
+- ¿Hay módulos donde el test-first es obligatorio y otros donde no?
+
+---
+
+## 3. Dónde persistir la calibración (modo híbrido)
+
+**a) Fuente de verdad (legible por humanos):** agrega/actualiza una sección **"Testing & TDD"**
+en `.ai/context/tech-stack.md`:
+
+```markdown
+## Testing & TDD
+
+**Strict TDD:** true   <!-- resuelto por ozali Fase 3.5 -->
+
+| Capacidad | Valor |
+| --------- | ----- |
+| Runner unit | vitest (`pnpm test`) |
+| ... | ... |
+
+**Comando verde (definition of green):** `pnpm test` sin fallos + cobertura ≥ 80%.
+**Ciclo:** RED → GREEN → REFACTOR (test-first) cuando Strict TDD = true.
+```
+
+**b) Engram (buscable / acumulable):** espeja como artefacto, ver
+[`engram-convention.md`](engram-convention.md):
+
+```
+title:     cdk/_project/testing-capabilities
+topic_key: cdk/_project/testing-capabilities
+type:      architecture
+project:   <nombre del proyecto>
+capture_prompt: false
+content:   <la tabla de capacidades + strict_tdd + comando verde>
+```
+
+---
+
+## 4. Cómo lo consume `cdk`
+
+- Si `strict_tdd: true`: el ciclo `executioners ⇄ tester` es **test-first** (RED→GREEN→REFACTOR);
+  el GATE muestra el **plan de pruebas** como sección obligatoria y el `tester` no aprueba un hito
+  sin pruebas nuevas/actualizadas en verde.
+- Si `strict_tdd: false`: se exige al menos **pruebas de regresión** sobre lo tocado y se deja
+  explícito en `05-bitacora-ejecucion.md` que el proyecto no soporta TDD estricto (con la mejora
+  sugerida para habilitarlo en `03-mejoras.md`).
+- El **comando verde** calibrado es el que usa el `tester` para decidir pass/fail.
+
+---
+
+## 5. Validación al cerrar la fase
+
+Antes de pasar a Fase 4, confirma:
+1. La tabla de capacidades refleja comandos **reales** (los corriste o los leíste del manifiesto).
+2. `strict_tdd` quedó resuelto con justificación (no "por defecto" silencioso).
+3. La sección "Testing & TDD" existe en `.ai/context/tech-stack.md`.
+4. (Si hay Engram) el artefacto `testing-capabilities` quedó guardado.