ozali 0.1.0

package/skill/references/doc-templates.md

@@ -0,0 +1,301 @@
+# Plantillas de documentación
+
+Hay **dos** conjuntos de documentación, con propósito y ruta distintos:
+
+| Conjunto | Quién lo genera | Cuándo | Ruta |
+|----------|-----------------|--------|------|
+| **Corrida de ozali** | `ozali` | cada corrida de diagnóstico | `.ai/ozali/logs/ozali.log_{{yy-mm-dd}}/` |
+| **Hito de cdk** | `cdk` (`project-documenter`) | cada solicitud/hito del usuario | `.ozali/docs/cdk/<hito>/` |
+
+Ambos comparten el mismo **encabezado de identidad**.
+
+---
+
+## A) Documentación de corrida (ozali)
+
+Cada corrida de `ozali` produce **3 documentos** en:
+
+```
+.ai/ozali/logs/ozali.log_{{yy-mm-dd}}/
+  01-analisis.md
+  02-plan.md
+  03-mejoras.md
+```
+
+- `{{yy-mm-dd}}` = fecha local de la corrida (ej. `26-06-10`).
+- Si ya existe una carpeta del mismo día, agrega sufijo: `ozali.log_26-06-10-2/`.
+- La **fecha** va en el nombre de la carpeta; la **fecha + hora** va dentro de cada documento.
+
+---
+
+## Encabezado obligatorio (todos los documentos)
+
+Va al inicio de cada `.md`. Toma los datos de la **Fase 0** de `ozali` (identidad/git/sesión).
+
+```
+---
+ozali.log: {{yy-mm-dd}}
+documento: 01-analisis | 02-plan | 03-mejoras
+Autor: <git user.name> <<git user.email>>
+Sesión: <correo de sesión si está disponible>
+Rama: <branch actual>
+Creado: <yyyy-mm-dd HH:MM:SS> (local)
+---
+```
+
+---
+
+## 01-analisis.md — Análisis e hitos de importancia
+
+```markdown
+# Análisis — <título corto de la solicitud>
+
+## Contexto
+<qué se pidió y por qué>
+
+## Fuente de verdad usada
+- Variante: AI.md/.ai | IA.md/.ia
+- Discrepancias detectadas vs. estructura real:
+  - <lista>
+
+## Hitos de importancia
+1. <hito> — <por qué importa> — Riesgo: Alto/Medio/Bajo
+2. ...
+
+## Superficie de impacto
+- Archivos/módulos afectados: <lista>
+- Dependencias: <lista>
+```
+
+---
+
+## 02-plan.md — Plan ejecutado
+
+```markdown
+# Plan ejecutado — <título corto>
+
+## Decisión
+<enfoque elegido y alternativas descartadas>
+
+## Tareas (con estado final)
+- [x] <tarea 1>
+- [x] <tarea 2>
+- [ ] <pendiente, si aplica>
+
+## Cambios realizados
+- <archivo>: <qué cambió>
+
+## Validación
+- Pruebas ejecutadas: <comando / resultado>
+- Criterios de aceptación: cumplidos/parciales
+```
+
+---
+
+## 03-mejoras.md — Mejoras posibles (explicativo, breve)
+
+```markdown
+# Mejoras posibles — <título corto>
+
+> Solo propuestas explicativas, sin profundizar. Cada una con su grado de relevancia.
+
+## A la skill (ozali/cdk)
+- **[Alta]** <mejora> — <por qué>
+- **[Media]** <mejora> — <por qué>
+
+## Al proyecto
+- **[Alta]** <mejora> — <por qué>
+- **[Baja]** <mejora> — <por qué>
+```
+
+Grados de relevancia: **Alta** (impacto/urgencia clara), **Media** (conviene pronto),
+**Baja** (nice-to-have).
+
+---
+
+## B) Documentación por hito (cdk)
+
+La genera `cdk` (subagente `project-documenter`) **una vez por cada solicitud/hito** del
+usuario, en:
+
+```
+.ozali/docs/cdk/<hito>/
+  01-prompt-entrada.md      ← al inicio del hito
+  02-plan-aprobado.md       ← se congela al aprobar el GATE (inmutable)
+  03-resumen-tecnico.md     ← al cierre
+  04-resumen-usuario.md     ← al cierre
+  05-bitacora-ejecucion.md  ← append-only, DURANTE el ciclo
+  06-uso-tokens.md          ← al cierre
+```
+
+- `<hito>` = slug corto y descriptivo de la solicitud (ej. `alta-componente-cobranza`,
+  `fix-calculo-prima-poliza`). Si ya existe, agrega sufijo `-2`, `-3`, …
+- Cada documento usa el **mismo encabezado de identidad** de arriba (con `hito:` en lugar de
+  `ozali.log:`).
+
+### 01-prompt-entrada.md — Prompt de entrada
+
+```markdown
+# Prompt de entrada — <hito>
+
+> Captura textual de la solicitud del usuario, para evaluar el progreso de las solicitudes.
+
+## Prompt (textual)
+<pega aquí, sin editar, el prompt/solicitud exacta del usuario>
+
+## Contexto de la sesión
+- Fecha/Hora de la solicitud: <yyyy-mm-dd HH:MM:SS>
+- Hito asignado: <slug>
+- Modo de ejecución: normal | --auto
+- Solicitudes previas relacionadas: <links a otros hitos, si aplica>
+```
+
+### 02-plan-aprobado.md — Plan aprobado (snapshot congelado en el GATE)
+
+> Se escribe **al aprobarse el GATE, antes de tocar código**, y es **inmutable**: deja
+> constancia de qué se acordó y quién lo aprobó. Cualquier desvío posterior se registra en
+> `05-bitacora-ejecucion.md`, nunca editando este documento. Es el mismo Plan de Acción que
+> vio el usuario, ya con su decisión.
+
+```markdown
+# Plan aprobado — <hito>
+
+**Tipo:** feature | bugfix | hotfix | refactor      **Tamaño:** S | M | L
+**Workflow:** .ai/workflows/<archivo>.md
+**Modo:** normal | --auto
+**Aprobado por:** <usuario> — <yyyy-mm-dd HH:MM:SS>
+
+## Solicitud del usuario
+<qué pidió, en sus palabras>
+
+## Alcance aprobado
+<lo que SÍ se hará>
+
+## Hallazgos del análisis
+- Reutilización detectada: <clases/archivos existentes que se aprovechan>
+- Riesgos: ⚠ <riesgo> → <mitigación> / 🔴 <bloqueante resuelto y cómo>
+
+## Cambios aprobados (archivo por archivo)
+| Acción | Archivo / Clase | Capa | Detalle |
+| :-- | :-- | :-- | :-- |
+| crear | <X> | <capa> | <detalle> |
+| modificar | <Y> | <capa> | <detalle> |
+
+## Tareas
+- [ ] <tarea 1>
+- [ ] <tarea 2>
+
+## Plan de pruebas
+- Caso feliz: <...>
+- Casos negativos: <...>
+
+## Criterios de aceptación (definition of done)
+- <p. ej. mvn test verde + criterios del owner>
+
+## Fuera de alcance (explícito)
+- <lo que NO se hará en este hito>
+```
+
+### 03-resumen-tecnico.md — Resumen técnico
+
+```markdown
+# Resumen técnico — <hito>
+
+## Decisiones de implementación
+<enfoque, patrones, por qué>
+
+## Archivos tocados
+- <archivo>: <qué cambió>
+
+## Impacto y riesgos
+- Módulos afectados: <lista>
+- Riesgo en módulos sensibles (core/guard/services/poliza/siniestros/cobranza/models/...): <sí/no, detalle>
+
+## Validación
+- Pruebas: <comando / resultado>
+- walkthrough.md: <ruta / evidencia>
+```
+
+### 04-resumen-usuario.md — Resumen para el usuario
+
+```markdown
+# Resumen para usuario — <hito>
+
+> Lenguaje claro, sin jerga técnica.
+
+## ¿Qué se hizo y para qué sirve?
+<explicación sencilla en 2-3 frases>
+
+## ¿Cómo se usa? (casos de uso)
+1. **<caso de uso 1>** — <pasos sencillos explicados>
+2. **<caso de uso 2>** — <pasos sencillos explicados>
+
+## Qué cambia para ti
+<beneficio concreto / qué notará el usuario>
+```
+
+### 05-bitacora-ejecucion.md — Bitácora de ejecución (append-only)
+
+> Registro **cronológico y append-only** de lo que ocurre DESPUÉS de aprobar el plan y
+> DURANTE el ciclo de ejecución: dudas, decisiones, actualizaciones y desvíos respecto al
+> `02-plan-aprobado.md` (que permanece inmutable), preguntas al usuario y sus respuestas.
+> **No se reescribe**: solo se agregan entradas, en orden cronológico. Aquí vive toda la
+> diferencia entre lo planeado y lo realmente ejecutado.
+
+```markdown
+# Bitácora de ejecución — <hito>
+
+**Modo de ejecución:** normal | --auto
+**Inicio del ciclo:** <yyyy-mm-dd HH:MM:SS>
+
+## Entradas
+
+### <yyyy-mm-dd HH:MM:SS> — [duda | decisión | actualización | desvío | pregunta]
+- **Qué surgió:** <descripción concreta>
+- **Contexto:** <archivo / tarea / iteración donde apareció>
+- **Resolución:** <qué se decidió y por qué; si fue pregunta al usuario, pega su respuesta textual>
+- **Impacto en el plan:** ninguno | ajuste dentro de alcance | requirió ampliar alcance (se detuvo y preguntó)
+
+### <yyyy-mm-dd HH:MM:SS> — [tipo]
+- ...
+
+## Cierre del ciclo
+- **Fin:** <yyyy-mm-dd HH:MM:SS>
+- **Iteraciones executioner⇄tester:** <n>
+- **Desvíos relevantes vs. plan aprobado:** <resumen / "ninguno">
+```
+
+### 06-uso-tokens.md — Uso de tokens (al cierre)
+
+> Se captura **al terminar el plan**. Las métricas se rellenan en caso de que el proveedor sea
+> **Claude/Anthropic** (fuente: comando `/cost` de Claude Code). Con cualquier otro
+> proveedor verifica si puedes obtener la información y si no puedes, deja la estructura con el **nombre del proveedor** y las métricas en `N/A`
+> (data presente, sin inventar cifras).
+
+```markdown
+# Uso de tokens — <hito>
+
+**Proveedor:** Claude (Anthropic) | <otro proveedor>
+**Modelo:** <p. ej. claude-opus-4-8 / N/A>
+**Fuente de la medición:** /cost (Claude Code) | N/A
+**Capturado:** <yyyy-mm-dd HH:MM:SS>
+
+## Métricas de la sesión
+| Métrica | Valor |
+| :-- | :-- |
+| Tokens de entrada (input)   | <n / N/A> |
+| Tokens de salida (output)   | <n / N/A> |
+| Tokens de caché (lectura)   | <n / N/A> |
+| Tokens de caché (escritura) | <n / N/A> |
+| Total de tokens             | <n / N/A> |
+| Total de tiempo de sesión   | <n / N/A> |
+| Costo estimado              | <$ / N/A> |
+
+## Notas
+- <observaciones sobre el consumo del hito; deja vacío o "N/A" si no puedes encontrar información del proveedor>
+```
+
+> **Regla del proveedor:** si el proveedor **no** cuenta con estos datos, **no** intentes
+> derivar ni inventar cifras de otro sistema: solo registra el nombre del proveedor y deja
+> el resto en `N/A`. El objetivo es **mantener la estructura presente** para no perder la
+> trazabilidad del hito.

package/skill/references/engram-convention.md

@@ -0,0 +1,186 @@
+# Convención de memoria híbrida (docs + Engram)
+
+Contrato de persistencia que `ozali` cablea dentro del `SKILL.md` de `cdk` (Fase 6). Define
+**qué se guarda, dónde, cuándo y con qué nombre** para que la herramienta **aprenda de lo que el
+equipo va haciendo** sin sobrecargar el repo principal.
+
+> **Principio híbrido:** cada artefacto clave vive en **dos** lugares — un **documento legible**
+> (para humanos, auditable, versionable en el repo de conocimiento) **y** un **espejo en Engram**
+> (buscable, recuperable tras compactación, base de la memoria acumulativa del equipo).
+
+---
+
+## 1. Modo de persistencia y degradación
+
+`cdk` resuelve el modo **al iniciar cada hito**:
+
+| Modo | Lee de | Escribe en | Cuándo |
+|---|---|---|---|
+| **`hybrid`** (default) | Engram primero, docs como fallback | docs **y** Engram | Engram disponible |
+| **`docs`** | docs | docs | Engram **no** instalado/alcanzable |
+| **`none`** | contexto del prompt | nada | el usuario lo pide explícito (efímero) |
+
+**Detección de Engram:** el MCP de Engram expone `mem_*`. Si las herramientas no están disponibles
+(o `mem_context` falla), `cdk` **degrada a `docs`** sin romper: escribe los 6 documentos por hito
+igual y anota en la bitácora que el espejo Engram quedó pendiente. `ozali init` (CLI) **verifica/
+guía la instalación de Engram**; mientras no esté, todo funciona en modo `docs`.
+
+> Regla: la **ausencia de Engram nunca bloquea** un hito. Solo se pierde la capa buscable, que se
+> rellena al sincronizar cuando Engram esté disponible.
+
+**Nombre de proyecto:** usa el que Engram autodetecta del remoto git (normalizado a minúsculas).
+Sin remoto, el nombre de carpeta. Mantén UN nombre por proyecto (evita drift `my-app` vs `My-App`).
+
+---
+
+## 2. Naming determinista
+
+Todos los artefactos de `cdk` en Engram siguen:
+
+```
+title:           cdk/{hito}/{artifact-type}
+topic_key:       cdk/{hito}/{artifact-type}
+type:            architecture
+project:         {nombre del proyecto detectado}
+scope:           project
+capture_prompt:  false        # artefactos automáticos: NO capturan el prompt del usuario
+```
+
+Para artefactos a nivel de proyecto (no de hito): `cdk/_project/{artifact-type}`.
+
+> `capture_prompt: false` es **explícito y obligatorio** para artefactos automáticos cuando el
+> esquema lo soporta (Engram v1.15.3+ lo pone `true` por defecto en saves humanos). Si un esquema
+> viejo no expone el campo, **omítelo** en lugar de fallar. El **prompt del usuario** se captura
+> aparte, una sola vez, con `mem_save_prompt` al inicio del hito (artefacto `01`).
+
+### Mapa doc ↔ Engram
+
+| Doc por hito (archivo) | artifact-type (Engram) | Momento | Operación |
+|---|---|---|---|
+| `01-prompt-entrada.md` | — (usa `mem_save_prompt`) | inicio del hito | `mem_save_prompt` |
+| (análisis del analyzer) | `analisis` | tras el análisis | `mem_save` |
+| `02-plan-aprobado.md` | `plan-aprobado` | al aprobar el GATE | `mem_save` **una vez** (inmutable) |
+| `05-bitacora-ejecucion.md` | `bitacora` | checkpoints del ciclo | `mem_update` (upsert) |
+| `03-resumen-tecnico.md` | `resumen-tecnico` | al cierre | `mem_save` |
+| (estado del orchestrator) | `state` | tras cada transición de fase | `mem_update` (upsert) |
+| calibración (Fase 3.5 de ozali) | `_project/testing-capabilities` | en el bootstrap | `mem_save` |
+
+> `04-resumen-usuario.md` y `06-uso-tokens.md` se quedan como **docs legibles** (no necesitan
+> espejo buscable); opcional mirror si el equipo lo quiere.
+
+---
+
+## 3. Llamadas inline (lo que cdk debe ejecutar)
+
+### Al INICIAR un hito (contrato de arranque — así aprende del equipo)
+
+```
+# 1) Capturar el prompt real, una vez:
+mem_save_prompt(prompt: "{prompt textual del usuario}", project: "{project}")
+
+# 2) Traer contexto previo (búsquedas primero, luego recuperar full):
+mem_search(query: "cdk/{hito}/state", project: "{project}")            → ¿hito en curso? (reanudar)
+mem_search(query: "cdk/_project/testing-capabilities", project: "{project}")  → strict_tdd + comando verde
+mem_search(query: "cdk/{hito}", project: "{project}")                 → artefactos relacionados
+mem_context(project: "{project}")                                      → historia reciente de sesión
+
+# 3) Recuperar contenido completo de lo relevante (search devuelve preview truncado):
+mem_get_observation(id: {state_id})                  → restaurar fase + tareas done/pending
+mem_get_observation(id: {testing_capabilities_id})   → resolver modo TDD
+```
+
+Si `state` existe con tareas pendientes → **reanuda** desde la primera pendiente (no rehagas lo
+hecho). Si `testing-capabilities` da `strict_tdd: true` → ciclo **test-first** (RED→GREEN→REFACTOR).
+
+### Al CONGELAR el plan (GATE aprobado)
+
+```
+mem_save(
+  title: "cdk/{hito}/plan-aprobado", topic_key: "cdk/{hito}/plan-aprobado",
+  type: "architecture", project: "{project}", capture_prompt: false,
+  content: "{markdown completo del plan aprobado}"
+)
+```
+Inmutable: **no** se vuelve a guardar este topic_key. Los desvíos van a `bitacora`.
+
+### DURANTE el ciclo (bitácora + estado, append-only en archivo, upsert en Engram)
+
+```
+# bitácora: el archivo 05 es append-only (fuente de verdad); el espejo se upserta con el full actual
+mem_update(id: {bitacora_id}, content: "{contenido completo y actualizado de la bitácora}")
+#   (si aún no existe: mem_save con topic_key cdk/{hito}/bitacora)
+
+# estado recuperable: upsert tras CADA transición de fase
+mem_update(id: {state_id}, content: "{ver §4}")
+#   (si aún no existe: mem_save con topic_key cdk/{hito}/state)
+```
+
+### Al CERRAR el hito
+
+```
+mem_save(title: "cdk/{hito}/resumen-tecnico", topic_key: "cdk/{hito}/resumen-tecnico",
+         type: "architecture", project: "{project}", capture_prompt: false,
+         content: "{resumen técnico}")
+# y un cierre de sesión (solo el agente top-level, NUNCA un subagente):
+mem_session_summary(project: "{project}", content: "{qué se logró en el hito}")
+```
+
+---
+
+## 4. Artefacto `state` (recuperable tras compactación)
+
+Lo mantiene el `project-orchestrator`. Permite que un hito sobreviva a una compactación de
+contexto o a cerrar/abrir la sesión.
+
+```
+title:     cdk/{hito}/state
+topic_key: cdk/{hito}/state
+content: |
+  hito: {hito}
+  fase: {analisis | plan-aprobado | ejecucion | cierre}
+  strict_tdd: {true|false}
+  modo: {normal | --auto}
+  tareas:
+    completadas: [t1, t2]
+    pendientes: [t3, t4]
+  ultimo_commit: {short SHA}
+  last_updated: {ISO-8601}
+```
+
+**Recuperación (2 pasos):** `mem_search("cdk/{hito}/state")` → `mem_get_observation(id)` → parsear
+YAML → restaurar. Si no hay `state`, es un hito nuevo.
+
+---
+
+## 5. Reglas duras
+
+- **Persistir ANTES de responder:** cuando un subagente guarda en Engram o escribe docs, la llamada
+  va **antes** de su texto final. La última salida del subagente debe ser **texto**, nunca un
+  tool-call (si no, el orquestador solo recibe `"Observation saved"` y se pierde el análisis).
+- **Subagentes NO llaman `mem_session_summary`** — reservado para el agente top-level.
+- **Modo `hybrid`: ambas escrituras deben tener éxito.** Si Engram falla a media operación, el doc
+  ya quedó (fuente de verdad) y se anota el espejo pendiente en la bitácora; no se aborta el hito.
+- **Lectura `hybrid`: Engram primero, docs como fallback.** Si `mem_search` no devuelve, lee el
+  archivo correspondiente en `.ozali/docs/cdk/{hito}/`.
+- **Nunca inventes el prompt:** si no hay contexto de prompt, `mem_save` no fabrica texto.
+
+---
+
+## 6. Sincronización al repo de conocimiento (`ozali sync`)
+
+Engram guarda en su **store local**; el histórico (docs + export Engram) se aísla en el repo de
+conocimiento de equipo (ver [team-history](../../docs/team-history.md)). El CLI lo orquesta:
+
+```
+ozali sync            # export del proyecto → repo de conocimiento, commit + push
+ozali sync --import   # pull del repo de conocimiento → import a Engram local (onboarding)
+```
+
+Internamente (Fase C lo implementa):
+1. `engram sync` exporta las memorias del proyecto a `.engram/` (chunks + manifest).
+2. Copia `.engram/` y `.ozali/docs/cdk/` a `ozali-knowledge/{engram,projects/<project>/...}`.
+3. Commit + push del repo de conocimiento (no del repo principal, que los tiene gitignored).
+4. `--import` hace lo inverso: clona/pull del repo de conocimiento y `engram sync --import`.
+
+> Trazabilidad: cada doc lleva `ultimo_commit`/`Commit:` del repo principal en su encabezado, así
+> el histórico aislado siempre apunta al código exacto que documenta.

package/skill/references/harness-template.md

@@ -0,0 +1,214 @@
+# Plantilla del harness `verify-structure.mjs`
+
+Esqueleto parametrizado del **harness del analista** que `ozali` genera en la Fase 6
+(punto 3) como `.claude/skills/cdk/verify-structure.mjs`. El script es el paso 1
+obligatorio del `project-analyzer`: verifica la estructura REAL del repo contra la
+arquitectura documentada — no confía en la doc.
+
+> **Regla:** los valores de los parámetros salen de la **fuente de verdad validada en la
+> Fase 3** (`.ai/context/architecture.md`) y de la inspección real del repo — nunca de
+> supuestos. Cero dependencias, Node 16+.
+
+---
+
+## 1. Parámetros a sustituir
+
+| Parámetro | Qué es | Ejemplo backend (Java) | Ejemplo frontend (Angular) |
+|---|---|---|---|
+| `{{PROJECT_NAME}}` | Nombre real del repo | `quattro-auto-mtto` | `biibiic` |
+| `{{ROOT_MARKER}}` | Archivo que identifica la raíz (para subir buscándolo) | `pom.xml` | `angular.json` (o `package.json`) |
+| `{{BASE_PATH}}` | Carpeta base del código, como array de segmentos | `["src","main","java","com","acme"]` | `["src","app"]` |
+| `{{EXT}}` | Extensión de archivos a contar | `.java` | `.ts` |
+| `{{EXPECTED}}` | Capas/carpetas esperadas + rol de una línea (de `architecture.md`) | `controllers`, `services/strategies/impl`, … | `components`, `services`, `guards`, `pages`, … |
+| `{{KEY_CLASSES}}` | Clases/archivos clave que los agentes referencian (sin extensión) | `ApiResponse`, `ErrorCode` | `auth.guard`, `api.service` |
+| `{{CONSISTENCY_CHECKS}}` | Gotchas verificados del repo (ver §3) | context-path, typos de nombres | rutas lazy, config de entornos |
+| `{{TEST_DIR}}` | Carpeta(s) de pruebas a contar | `src/test` | `src` con sufijo `.spec.ts` |
+
+---
+
+## 2. Esqueleto del script
+
+```javascript
+#!/usr/bin/env node
+// CDK — {{PROJECT_NAME}}
+// Harness del analista: verifica la estructura real del proyecto contra la
+// arquitectura documentada (.ai/context/architecture.md), localiza archivos clave
+// y reporta discrepancias + candidatos a reutilizacion.
+//
+// Uso (desde cualquier carpeta dentro del repo):
+//   node .claude/skills/cdk/verify-structure.mjs              # reporte completo
+//   node .claude/skills/cdk/verify-structure.mjs --grep <palabra>
+//
+// Cero dependencias. Node 16+.
+
+import fs from "node:fs";
+import path from "node:path";
+
+// ---- localizar la raiz del proyecto (sube buscando {{ROOT_MARKER}}) ---------
+function findRoot(start) {
+  let dir = start;
+  for (let i = 0; i < 30; i++) {
+    if (fs.existsSync(path.join(dir, "{{ROOT_MARKER}}"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return start;
+}
+
+const ROOT = findRoot(process.cwd());
+const BASE = path.join(ROOT, ...{{BASE_PATH}});
+const EXT = "{{EXT}}";
+
+// ---- capas esperadas (lo que promete .ai/context/architecture.md) -----------
+const EXPECTED = [
+  // { pkg: "<carpeta relativa a BASE>", role: "<rol de una linea>" },
+  {{EXPECTED}}
+];
+
+// ---- archivos clave que referencian los agentes -----------------------------
+const KEY_CLASSES = [
+  {{KEY_CLASSES}}
+];
+
+function countFiles(dir) {
+  let n = 0;
+  if (!fs.existsSync(dir)) return -1;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.isDirectory()) {
+      const c = countFiles(path.join(dir, e.name));
+      if (c > 0) n += c;
+    } else if (e.name.endsWith(EXT)) {
+      n++;
+    }
+  }
+  return n;
+}
+
+function findFile(dir, name) {
+  if (!fs.existsSync(dir)) return null;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      const hit = findFile(full, name);
+      if (hit) return hit;
+    } else if (e.name === name + EXT) {
+      return path.relative(ROOT, full);
+    }
+  }
+  return null;
+}
+
+function grepFiles(dir, term, out, limit = 40) {
+  if (out.length >= limit || !fs.existsSync(dir)) return;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (out.length >= limit) return;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      grepFiles(full, term, out, limit);
+    } else if (e.name.endsWith(EXT) && e.name.toLowerCase().includes(term.toLowerCase())) {
+      out.push(path.relative(ROOT, full));
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+console.log("============================================================");
+console.log(" CDK · {{PROJECT_NAME}} — Verificacion de estructura");
+console.log("============================================================");
+console.log("Root:", ROOT);
+console.log("Base:", fs.existsSync(BASE) ? path.relative(ROOT, BASE) : "(!) NO ENCONTRADO");
+console.log("");
+
+const risks = [];
+
+console.log("-- Capas / carpetas ---------------------------------------");
+for (const { pkg, role } of EXPECTED) {
+  const dir = path.join(BASE, ...pkg.split("/"));
+  const c = countFiles(dir);
+  const status = c < 0 ? "FALTA " : String(c).padStart(4) + " ";
+  console.log(`  [${c < 0 ? "X" : "ok"}] ${pkg.padEnd(26)} ${status}files  — ${role}`);
+  if (c < 0) risks.push(`Carpeta esperada ausente: ${pkg}`);
+}
+console.log("");
+
+console.log("-- Archivos clave -----------------------------------------");
+for (const cls of KEY_CLASSES) {
+  const loc = findFile(BASE, cls);
+  console.log(`  [${loc ? "ok" : "X"}] ${cls.padEnd(28)} ${loc || "(!) NO ENCONTRADO"}`);
+  if (!loc) risks.push(`Archivo clave no encontrado: ${cls}`);
+}
+console.log("");
+
+console.log("-- Chequeos de consistencia doc<->codigo -----------------");
+// {{CONSISTENCY_CHECKS}}: gotchas VERIFICADOS del repo. Cada uno imprime [i] con el
+// hallazgo y la regla practica. Si dejan de aparecer, actualizar tambien la seccion
+// Gotchas del SKILL.md de cdk y .ai/knowledge/learning-notes.md. Ejemplos:
+//  - typos en nombres reales de clases (no "corregirlos" sin refactor aprobado)
+//  - prefijos globales (context-path / baseHref) que no van en el codigo
+//  - donde vive cada propiedad de configuracion por entorno
+//  - conteo de pruebas reales ({{TEST_DIR}}) → advertir si la cobertura es minima
+{{CONSISTENCY_CHECKS}}
+console.log("");
+
+// ---- busqueda opcional de reutilizacion (busca antes de crear) --------------
+const gi = process.argv.indexOf("--grep");
+if (gi !== -1 && process.argv[gi + 1]) {
+  const term = process.argv[gi + 1];
+  console.log(`-- Reutilizacion: archivos que ya mencionan "${term}" ----`);
+  const hits = [];
+  grepFiles(BASE, term, hits);
+  if (hits.length === 0) console.log("  (sin coincidencias por nombre de archivo)");
+  for (const h of hits) console.log("  •", h);
+  console.log("");
+  console.log(`  >> Antes de crear codigo nuevo, revisa estos ${hits.length} archivo(s).`);
+  console.log("");
+}
+
+console.log("============================================================");
+if (risks.length) {
+  console.log(` RIESGOS / HALLAZGOS (${risks.length}):`);
+  for (const r of risks) console.log("  ⚠  " + r);
+} else {
+  console.log(" Estructura coherente con la arquitectura documentada.");
+}
+console.log("============================================================");
+```
+
+---
+
+## 3. Secciones específicas por tipo de proyecto
+
+Además del esqueleto, agrega los chequeos que apliquen:
+
+**Backend (Java/Spring)**
+- Sección extra de **dominio** si hay un patrón central (p. ej. en quattro-auto-mtto:
+  listar carpetas bajo `services/strategies/impl/` y verificar que cada aseguradora tenga
+  su `*Strategy`). Replica la idea para el patrón central del proyecto.
+- Leer `context-path` de `application.properties`/`application.yml` y advertir que no se
+  incluye en `@RequestMapping`.
+- Contar `.java` en `src/test`.
+
+**Frontend (Angular/React/Vue)**
+- Verificar módulos/rutas declarados vs carpetas reales (lazy loading roto = riesgo).
+- Leer `baseHref`/`deploy` de `angular.json` o equivalente.
+- Contar `*.spec.ts` (o `*.test.tsx`) para reportar cobertura real.
+
+**Ambos**
+- El bloque de consistencia **siembra** `learning-notes.md`: todo gotcha que el harness
+  detecte en su primera corrida debe quedar registrado ahí y en el SKILL.md de `cdk`.
+
+---
+
+## 4. Validación obligatoria al generarlo
+
+Tras escribir el script, `ozali` **debe ejecutarlo** y verificar:
+1. Corre sin errores con Node 16+ (`node .claude/skills/cdk/verify-structure.mjs`).
+2. Todas las capas de `EXPECTED` reportan `[ok]` (si algo reporta `FALTA`, o la doc está
+   mal o el parámetro está mal — corrígelo antes de cerrar la Fase 6).
+3. Todos los `KEY_CLASSES` se localizan.
+4. `--grep <término-conocido>` devuelve hits razonables.
+
+La salida real de esta corrida se cita en el `02-plan.md` de la corrida de ozali como
+evidencia. Ejemplo de referencia ya funcionando: el `verify-structure.mjs` de este repo
+(`.claude/skills/cdk/verify-structure.mjs`).