ozali 0.5.0 → 0.6.1

package/README.md

@@ -59,9 +59,9 @@ git clone <repo> && node ozali/cli/bin/ozali.mjs init
 ### Uso del CLI
 
 ```bash
-ozali init      # detecta agente, instala la skill, aísla el histórico, instala+configura Engram
-ozali doctor    # health-check read-only (fuente de verdad, Engram, Cloud, Strict TDD, runner…)
-ozali update    # actualiza la instalación (skill ozali + ozali-jarvis + permisos) al paquete
+ozali init      # detecta agente, instala skills ozali + ozali-commit, aísla histórico, configura Engram
+ozali doctor    # health-check read-only (fuente de verdad, Engram, Cloud, versión de cdk, Strict TDD…)
+ozali update    # actualiza skills ozali + ozali-commit + ozali-jarvis + permisos; avisa si cdk quedó atrás
 ozali sync      # lleva el histórico (docs + Engram) al repo de conocimiento de equipo
 ozali audit     # navega/audita la memoria de Engram del proyecto (o general)
 ```
@@ -78,10 +78,17 @@ pnpm add -g ozali@<versión>   # actualiza el CLI global (pinea la versión por
 ozali update                  # en cada repo: refresca skill ozali + ozali-jarvis + permisos
 ```
 
-`ozali update` también **crea ozali-jarvis** en repos inicializados con versiones anteriores. La skill
-`cdk` la **regenera tu agente** (no el CLI): tras `ozali update`, abre el agente y vuelve a correr la
-skill `ozali` para regenerar `cdk` con el contrato nuevo — tus docs por hito y el plan congelado se
-conservan.
+`ozali update` también **crea ozali-jarvis** y **instala la skill `ozali-commit`** en repos
+inicializados con versiones anteriores. La skill `cdk` la **regenera/migra tu agente** (no el CLI):
+`ozali update` **detecta la versión de contrato** de `cdk` y, si quedó atrás (o aún referencia
+`copsis-commit` de versiones viejas), te avisa y te da los pasos manuales. Tras `ozali update`, abre
+el agente y vuelve a correr la skill `ozali`: su **pre-flight** detecta el `cdk` existente, lo **migra
+automáticamente** al contrato vigente (eliminando `copsis-commit` y cableando `ozali-commit`) y
+estampa la versión — tus docs por hito y el plan congelado se conservan.
+
+> **Commit del hito (`ozali-commit`):** `init`/`update` instalan la skill `ozali-commit`
+> (`.claude/skills/ozali-commit/`). `cdk` la invoca al cerrar cada hito
+> para generar el commit convencional (feat/fix/hotfix/refactor + scope) tras tu aprobación.
 
 `init` también escribe un **perfil base de permisos** (`.claude/settings.json` para Claude Code,
 `opencode.json` para opencode) para reducir confirmaciones: deja libres comandos seguros y bloquea
@@ -125,6 +132,7 @@ Claude Code y opencode (perfiles de permisos para ambos en
 | Desplegar Engram Cloud (Google Cloud) | [docs/deploy-cloud-gcloud.md](docs/deploy-cloud-gcloud.md) |
 | Skill bootstrap | [skill/SKILL.md](skill/SKILL.md) |
 | Calibración de testing + TDD | [skill/references/calibration-blueprint.md](skill/references/calibration-blueprint.md) |
+| Contrato y versión de `cdk` | [skill/references/cdk-contract.md](skill/references/cdk-contract.md) |
 | Blueprint de agentes | [skill/references/agents-blueprint.md](skill/references/agents-blueprint.md) |
 | Memoria híbrida (docs + Engram) | [skill/references/engram-convention.md](skill/references/engram-convention.md) |
 
@@ -137,7 +145,7 @@ Claude Code y opencode (perfiles de permisos para ambos en
 
 > Siguiente paso natural: crear el repo en GitHub y publicar la primera versión (`pnpm publish` vía tag), más probar el bootstrap en un repo real del equipo.
 
-> Linaje: `ozali` evoluciona la skill `copsis-doctor`, nutrida con conceptos de
+> Linaje: `ozali` se nutre de conceptos de
 > [gentle-ai](https://github.com/Gentleman-Programming/gentle-ai) (Engram, calibración SDD/TDD,
 > distribución plug-n-play).
 

package/cli/bin/ozali.mjs

@@ -12,10 +12,11 @@ ${c.bold("Uso:")}
   ozali <comando> [opciones]
 
 ${c.bold("Comandos:")}
-  init      Detecta el agente (Claude Code/opencode), instala la skill ozali,
-            aísla el histórico, configura Engram y el repo de conocimiento.
-  doctor    Health-check read-only del proyecto (fuente de verdad, Engram, TDD…).
-  update    Actualiza la instalación (skill ozali + ozali-jarvis + permisos) al paquete.
+  init      Detecta el agente (Claude Code/opencode), instala las skills ozali y
+            ozali-commit, aísla el histórico, configura Engram y el repo de conocimiento.
+  doctor    Health-check read-only del proyecto (fuente de verdad, Engram, versión de cdk, TDD…).
+  update    Actualiza la instalación (skills ozali + ozali-commit + ozali-jarvis + permisos)
+            al paquete y avisa si la skill cdk quedó desactualizada.
   sync      Sincroniza el histórico (docs + Engram) con el repo de conocimiento.
   audit     Navega/audita la memoria de Engram del proyecto (o general).
   cloud     Gestiona Engram Cloud: status, upgrade, repair, dashboard, config.

package/cli/lib/commands.mjs

@@ -4,7 +4,7 @@ import path from "node:path";
 import os from "node:os";
 import {
   c, ok, warn, err, info, step,
-  SKILL_SRC, TEMPLATES_SRC, exists, ensureDir, copyDir, readJSON, writeJSON,
+  SKILL_SRC, COMMIT_SKILL_SRC, TEMPLATES_SRC, exists, ensureDir, copyDir, readJSON, writeJSON,
   ensureGitignore, tryExec, spawnCmd, which, engramAssetName,
   projectName, pkgVersion, DEFAULT_KNOWLEDGE, HOME, openURL,
 } from "./util.mjs";
@@ -23,6 +23,11 @@ function skillTarget(cwd, scope) {
   return path.join(base, "skills", "ozali");
 }
 
+function commitSkillTarget(cwd, scope) {
+  const base = scope === "global" ? path.join(process.env.HOME || "", ".claude") : path.join(cwd, ".claude");
+  return path.join(base, "skills", "ozali-commit");
+}
+
 function readTeamCloud(cwd) {
   return readJSON(TEAM_CLOUD_PATH(cwd));
 }
@@ -166,11 +171,14 @@ export async function init(cwd, opts) {
 
   // --- acciones ---
   step("Aplicando");
-  // 1) copiar skill
+  // 1) copiar skill ozali (bootstrap) + ozali-commit (commit convencional)
   const target = skillTarget(cwd, scope);
   ensureDir(path.dirname(target));
   copyDir(SKILL_SRC, target);
   ok(`Skill instalada en ${c.bold(path.relative(cwd, target) || target)}.`);
+  const commitTarget = commitSkillTarget(cwd, scope);
+  copyDir(COMMIT_SKILL_SRC, commitTarget);
+  ok(`Skill ${c.bold("ozali-commit")} instalada en ${c.bold(path.relative(cwd, commitTarget) || commitTarget)}.`);
 
   // 2) perfiles base de permisos (idempotentes, merge mínimo) por agente
   if (agent === "claude-code" || agent === "both") {
@@ -761,6 +769,19 @@ export function doctor(cwd) {
   add("Node ≥ 16", env.node.ok, env.node.version);
   add("Fuente de verdad", env.sot.found, env.sot.found ? `${env.sot.doc} + ${env.sot.dir}/` : "ausente (corre la skill 'ozali')");
   add("Skill ozali instalada", env.skill.installed, env.skill.installed ? env.skill.paths.map((p) => path.relative(cwd, p) || p).join(", ") : "no instalada (ozali init)");
+  // Skill cdk (la genera el agente): versión de contrato vs. la vigente del paquete.
+  const cdkInfo = detectCdk(cwd);
+  const cdkN = cdkCanonicalVersion();
+  if (!cdkInfo.installed) {
+    add("Skill cdk", true, "no generada aún (corre la skill 'ozali' en tu agente)");
+  } else if (cdkInfo.version != null && cdkInfo.version >= cdkN && !cdkInfo.hasCopsis) {
+    add("Skill cdk", true, `contrato v${cdkInfo.version} (al día)`);
+  } else {
+    const reason = cdkInfo.hasCopsis ? "contiene copsis-commit → migra con la skill 'ozali'"
+      : cdkInfo.version == null ? "sin versión de contrato (legado) → migra con la skill 'ozali'"
+      : `contrato v${cdkInfo.version} < v${cdkN} → migra con la skill 'ozali'`;
+    add("Skill cdk", false, reason);
+  }
   add("Engram", env.engram.available, env.engram.available ? env.engram.bin : "no instalado → modo docs");
   if (env.engram.available) {
     const online = tryExec("engram", ["doctor"], { cwd }) !== null;
@@ -899,10 +920,15 @@ export function update(cwd, opts = {}) {
   }
 
   // 1) Skill ozali (incluye las references: la base desde la que el agente regenera cdk)
+  //    + ozali-commit (commit convencional) como skill hermana — la crea en repos previos.
   if (env.skill.installed) {
     for (const p of env.skill.paths) {
       copyDir(SKILL_SRC, p);
       ok(`Skill ozali actualizada: ${path.relative(cwd, p) || p} → v${pkgVersion()}`);
+      const commitDir = path.join(path.dirname(p), "ozali-commit");
+      const freshCommit = !exists(commitDir);
+      copyDir(COMMIT_SKILL_SRC, commitDir);
+      ok(`Skill ozali-commit ${freshCommit ? "instalada" : "actualizada"}: ${path.relative(cwd, commitDir) || commitDir}`);
     }
   } else {
     warn("Skill ozali no instalada en esta ruta (corre " + c.bold("ozali init") + " para instalarla).");
@@ -926,13 +952,27 @@ export function update(cwd, opts = {}) {
     if (agent === "opencode" || agent === "both") ensureJarvisOpencode(cwd);
   }
 
-  // 4) Skill cdk: la genera el AGENTE (Fase 6), el CLI no la regenera.
+  // 4) Skill cdk: la genera/migra el AGENTE (Fase 0.5/6); el CLI solo detecta versión y guía.
   const cdk = detectCdk(cwd);
+  const cdkN = cdkCanonicalVersion();
   if (cdk.installed) {
     step("Skill cdk (generada por el agente)");
-    warn("cdk no se actualiza desde el CLI: la regenera tu agente con el contrato nuevo.");
-    info("Abre tu agente y vuelve a correr la skill " + c.bold("ozali") + " para regenerar cdk (ozali-jarvis, recall-first §7, telemetría).");
-    info("Tus docs por hito (" + c.bold(".ozali/docs/cdk/") + ") y el plan congelado se conservan.");
+    const upToDate = cdk.version != null && cdk.version >= cdkN && !cdk.hasCopsis;
+    if (upToDate) {
+      ok(`cdk al día (contrato v${cdk.version}).`);
+    } else {
+      const reason = cdk.version == null ? "sin versión de contrato (cdk legado)"
+        : cdk.version < cdkN ? `contrato v${cdk.version} < v${cdkN} (desactualizado)`
+        : "contiene referencias a copsis-commit";
+      warn(`cdk desactualizada: ${reason}.`);
+      if (cdk.hasCopsis) warn("Detectadas referencias a " + c.bold("copsis-commit") + " (heredadas de versiones anteriores).");
+      info("El CLI no regenera cdk. Actualízala manualmente desde tu agente:");
+      info("  1. Abre tu agente en este proyecto.");
+      info("  2. Corre la skill " + c.bold("ozali") + " (escribe " + c.bold('"ozali"') + "): el pre-flight migra cdk al contrato " + c.bold("v" + cdkN) + ", elimina copsis-commit y cablea ozali-commit.");
+      info("Tus docs por hito (" + c.bold(".ozali/docs/cdk/") + ") y el plan congelado se conservan.");
+    }
+  } else {
+    info("cdk aún no generada en este repo. Corre la skill " + c.bold("ozali") + " en tu agente para crearla.");
   }
 
   // 5) versión del config
@@ -941,13 +981,39 @@ export function update(cwd, opts = {}) {
   return 0;
 }
 
-/** ¿Existe la skill cdk (generada por el agente)? */
+/**
+ * ¿Existe la skill cdk (generada por el agente)? Devuelve además la versión de contrato
+ * estampada en su frontmatter (`cdk_contract_version`) y si aún referencia `copsis-commit`.
+ * version === null ⇒ cdk legado (sin marcador de versión).
+ */
 function detectCdk(cwd) {
   const paths = [
     path.join(cwd, ".claude", "skills", "cdk", "SKILL.md"),
     path.join(HOME, ".claude", "skills", "cdk", "SKILL.md"),
   ].filter(exists);
-  return { installed: paths.length > 0, paths };
+  if (paths.length === 0) return { installed: false, paths: [], version: null, hasCopsis: false };
+  let version = null;
+  let hasCopsis = false;
+  for (const f of paths) {
+    const txt = fs.readFileSync(f, "utf8");
+    if (version === null) {
+      const m = txt.match(/cdk_contract_version:\s*(\d+)/i);
+      if (m) version = parseInt(m[1], 10);
+    }
+    if (/copsis-commit/i.test(txt)) hasCopsis = true;
+  }
+  return { installed: true, paths, version, hasCopsis };
+}
+
+/** Versión de contrato vigente de cdk (fuente única: skill/references/cdk-contract.md del paquete). */
+function cdkCanonicalVersion() {
+  try {
+    const txt = fs.readFileSync(path.join(SKILL_SRC, "references", "cdk-contract.md"), "utf8");
+    const m = txt.match(/CDK_CONTRACT_VERSION:\s*(\d+)/i);
+    return m ? parseInt(m[1], 10) : 1;
+  } catch {
+    return 1;
+  }
 }
 
 // ============================================================= sync ===========

package/cli/lib/util.mjs

@@ -10,6 +10,7 @@ import { execFileSync } from "node:child_process";
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const PKG_ROOT = path.resolve(HERE, "..", "..");
 export const SKILL_SRC = path.join(PKG_ROOT, "skill");
+export const COMMIT_SKILL_SRC = path.join(PKG_ROOT, "skill-commit");
 export const TEMPLATES_SRC = path.join(PKG_ROOT, "templates");
 
 export function pkgVersion() {

package/cli/test/smoke.test.mjs

@@ -133,6 +133,80 @@ test("update agrega ozali-jarvis en un repo que no lo tenía", () => {
   }
 });
 
+function initRepo(dir) {
+  run(["init", "--yes", "--no-engram", "--no-trust", "--no-jarvis", "--agent", "claude-code", "--scope", "project", "--knowledge-repo", path.join(dir, ".k")], dir);
+}
+
+function writeCdkStub(dir, body) {
+  const f = path.join(dir, ".claude", "skills", "cdk", "SKILL.md");
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  fs.writeFileSync(f, body);
+  return f;
+}
+
+test("init instala la skill ozali-commit", () => {
+  const dir = tmpProject();
+  try {
+    initRepo(dir);
+    assert.ok(fs.existsSync(path.join(dir, ".claude", "skills", "ozali-commit", "SKILL.md")), "ozali-commit SKILL.md instalada");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("doctor marca cdk al día cuando la versión de contrato coincide", () => {
+  const dir = tmpProject();
+  try {
+    initRepo(dir);
+    writeCdkStub(dir, "---\nname: cdk\ncdk_contract_version: 1\n---\n# cdk\n");
+    const { stdout } = run(["doctor"], dir, true);
+    assert.match(stdout, /Skill cdk/, "doctor reporta la fila Skill cdk");
+    assert.match(stdout, /contrato v1 \(al día\)/, "doctor marca cdk al día");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("doctor marca cdk desactualizada si referencia copsis-commit", () => {
+  const dir = tmpProject();
+  try {
+    initRepo(dir);
+    writeCdkStub(dir, "---\nname: cdk\ncdk_contract_version: 1\n---\n# cdk\ninvoca copsis-commit al cierre del hito\n");
+    const { stdout } = run(["doctor"], dir, true);
+    assert.match(stdout, /copsis-commit/, "doctor avisa de copsis-commit");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("update avisa y da pasos manuales si cdk está desactualizada (legado)", () => {
+  const dir = tmpProject();
+  try {
+    initRepo(dir);
+    writeCdkStub(dir, "---\nname: cdk\n---\n# cdk legado que invoca copsis-commit\n");
+    const { stdout } = run(["update"], dir);
+    assert.match(stdout, /cdk desactualizada/, "update avisa de cdk desactualizada");
+    assert.match(stdout, /copsis-commit/, "update menciona la migración de copsis-commit");
+    assert.match(stdout, /skill ozali|pre-flight|migra/i, "update da pasos manuales");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("update también instala ozali-commit en repos previos", () => {
+  const dir = tmpProject();
+  try {
+    initRepo(dir);
+    // Simula instalación previa sin ozali-commit.
+    fs.rmSync(path.join(dir, ".claude", "skills", "ozali-commit"), { recursive: true, force: true });
+    assert.ok(!fs.existsSync(path.join(dir, ".claude", "skills", "ozali-commit", "SKILL.md")), "precondición: sin ozali-commit");
+    run(["update"], dir);
+    assert.ok(fs.existsSync(path.join(dir, ".claude", "skills", "ozali-commit", "SKILL.md")), "update instala ozali-commit");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test("init --dry-run no escribe nada", () => {
   const dir = tmpProject();
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ozali",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Bootstrap interactivo de IA por equipo: calibra el proyecto, genera la skill de ejecución (cdk) con TDD/SDD, y mantiene memoria de equipo (Engram) con histórico aislado.",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
   "files": [
     "cli/",
     "skill/",
+    "skill-commit/",
     "templates/",
     "docs/",
     "README.md",

package/skill/SKILL.md

@@ -30,6 +30,7 @@ produce documentación, la calibración, el plan y los artefactos de la skill `c
 
 ```
 Fase 0    Identidad y registro          → quién corre ozali (git/sesión)
+Fase 0.5  Pre-flight de cdk             → ¿existe cdk? ¿versión de contrato vigente? migrar si toca
 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
@@ -69,6 +70,50 @@ Guarda estos valores; se reutilizan en Fase 6 y en la documentación.
 
 ---
 
+## Fase 0.5 — Pre-flight de `cdk` (versión de contrato + migración)
+
+> Esta fase resuelve el caso de **un repo que ya tiene `cdk` instalada**: en vez de omitirla,
+> `ozali` decide si está **al día**, **desactualizada** o **ausente**, y actúa en consecuencia.
+> La **versión de contrato vigente** y las reglas de migración están en
+> [`references/cdk-contract.md`](references/cdk-contract.md) — es la **fuente de verdad única**.
+
+1. **Lee la versión de contrato vigente `N`** del marcador `CDK_CONTRACT_VERSION` en
+   [`references/cdk-contract.md`](references/cdk-contract.md).
+2. **Busca el `cdk` instalado**: `.claude/skills/cdk/SKILL.md` (proyecto), luego
+   `~/.claude/skills/cdk/SKILL.md` (global). Si existe, lee `cdk_contract_version` de su frontmatter.
+3. **Decide y registra** la decisión (se usa en las Fases 5 y 6):
+
+   | Estado del `cdk` instalado | Decisión |
+   |---|---|
+   | **No existe** | `GENERAR` — flujo normal: continúa el bootstrap hasta el GATE (Fase 5) y genera `cdk` en la Fase 6, estampando `cdk_contract_version: N`. |
+   | **Existe sin `cdk_contract_version`** (cdk legado) o con valor **`< N`** | `MIGRAR` — **migración automática** (sin GATE), ver abajo. |
+   | **Existe con `cdk_contract_version == N`** | `AL_DÍA` — no regenerar. Infórmalo y continúa el bootstrap solo para refrescar la calibración/documentación si el usuario lo pide. |
+
+4. **Migración automática (`MIGRAR`)** — aplica los deltas del changelog de
+   [`references/cdk-contract.md`](references/cdk-contract.md) sobre el `cdk` instalado, **sin** pasar
+   por el GATE, porque preserva el `cdk` del usuario y solo actualiza el contrato:
+   - **Elimina toda referencia a la nomenclatura heredada** (`copsis-commit`, `copsis-doctor`) y
+     reemplázala por la de `ozali`: `copsis-commit` → **`ozali-commit`** (instalada en
+     `.claude/skills/ozali-commit/`); refs a plantillas o a la skill `copsis-doctor` → sus
+     equivalentes de `ozali`. No debe quedar ninguna mención a `copsis-*`.
+   - **Migra el histórico legado**: si existe `.copsis/docs/cdk/` (la ruta de `copsis-doctor`),
+     **mueve** su contenido a `.ozali/docs/cdk/` (fusiona **por hito**, **sin sobrescribir** lo ya
+     existente) y **borra** la carpeta `.copsis/` una vez vacía.
+   - Aplica el resto de deltas del changelog (recall-first, telemetría, etc. según la versión).
+   - **Estampa** `cdk_contract_version: N` en el frontmatter del `cdk`.
+   - **Preserva** intactos los docs ya en `.ozali/docs/cdk/` (histórico por hito) y los planes
+     congelados (`02-plan-aprobado.md`).
+   - **Reporta** al usuario, en texto, qué cambió (referencias migradas, docs reubicados de `.copsis/`
+     a `.ozali/`, secciones actualizadas, versión nueva).
+   - **Excepción → GATE:** si un delta exige **regeneración estructural** (reescribir subagentes,
+     cambiar el harness, rehacer el wiring de TDD), eso **no** es migración automática: preséntalo en
+     el plan del GATE (Fase 5) y regénéralo en la Fase 6.
+
+> Sin `cdk` previo, esta fase no hace nada salvo registrar `GENERAR`. La calibración (Fase 3.5) y el
+> resto del flujo continúan igual.
+
+---
+
 ## Fase 1 — Detección de la fuente de verdad
 
 Busca en la raíz del repositorio, aceptando **ambas nomenclaturas**:
@@ -217,6 +262,9 @@ Solo tras la aprobación de la Fase 5. Genera:
    - 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;
+   - **estampar en el frontmatter** `cdk_contract_version: N`, con `N` = la versión de contrato
+     vigente de [`references/cdk-contract.md`](references/cdk-contract.md). Esto permite que el
+     pre-flight (Fase 0.5) y `ozali doctor`/`ozali update` sepan si el `cdk` está al día;
    - 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;
@@ -249,9 +297,11 @@ Solo tras la aprobación de la Fase 5. Genera:
      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.
+   - en el **cierre del hito**, invocar la skill **`ozali-commit`** (instalada por el CLI en
+     `.claude/skills/ozali-commit/`; **nunca** `copsis-commit`, nombre heredado de versiones
+     anteriores) 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

package/skill/references/cdk-contract.md

@@ -0,0 +1,81 @@
+<!-- CDK_CONTRACT_VERSION: 1 -->
+
+# Contrato de la skill `cdk` — versión y migración
+
+Esta es la **fuente de verdad única** de la versión del contrato con el que `ozali` genera (y
+mantiene) la skill `cdk`. La lee el **agente** (en la Fase 0.5 y la Fase 6 de
+[`../SKILL.md`](../SKILL.md)) y la parsea el **CLI** (`ozali doctor`/`ozali update`) del paquete.
+Para subir el contrato: incrementa el número del marcador `CDK_CONTRACT_VERSION` de arriba y la
+prosa de abajo, y agrega una entrada al changelog.
+
+> **Versión de contrato vigente: `1`**
+
+El número vive en **un solo lugar** (el marcador HTML de la primera línea, formato
+`CDK_CONTRACT_VERSION: <entero>`). No lo dupliques en otros archivos.
+
+---
+
+## Cómo se usa la versión
+
+- El `cdk` generado **debe estampar** su versión de contrato en el frontmatter de su `SKILL.md`:
+
+  ```yaml
+  ---
+  name: cdk
+  description: <triggers ricos…>
+  cdk_contract_version: 1
+  ---
+  ```
+
+- En el **pre-flight** (Fase 0.5 de `ozali`), el agente compara la versión estampada en el `cdk`
+  instalado contra esta versión vigente **N**:
+
+  | Estado del `cdk` instalado | Acción |
+  |---|---|
+  | No existe | Generar `cdk` por el flujo normal (GATE Fase 5 → Fase 6), estampando `cdk_contract_version: N`. |
+  | Existe **sin** `cdk_contract_version`, o con un valor **< N** | **Desactualizado → migración automática** (sin GATE): aplica los deltas del changelog, estampa `N` y reporta los cambios. Si el delta exige **regeneración estructural** de subagentes, eso sí pasa por el GATE de la Fase 5. |
+  | Existe con `cdk_contract_version == N` | Al día → no regenerar; solo informarlo. |
+
+> Un `cdk` **sin** el campo `cdk_contract_version` es un `cdk` **legado** (generado por una versión
+> anterior de `ozali`). Trátalo como versión `0`: siempre desactualizado.
+
+---
+
+## Regla de migración (todas las versiones)
+
+Al migrar un `cdk` legado o desactualizado, **siempre**:
+
+1. **Elimina toda referencia a la nomenclatura heredada** (`copsis-commit`, `copsis-doctor` — nombres
+   de versiones anteriores del ecosistema, predecesoras de `ozali`) y **reemplázala por la de
+   `ozali`**:
+   - `copsis-commit` → **`ozali-commit`** (la skill de commit vigente que `ozali init`/`ozali update`
+     instalan en `.claude/skills/ozali-commit/`).
+   - Refs a plantillas o a la skill **`copsis-doctor`** → sus equivalentes de `ozali` (esta skill y
+     sus `references/`). No debe quedar ninguna mención a `copsis-*` en el `cdk` migrado.
+2. **Migra el histórico legado de docs**: si existe `.copsis/docs/cdk/` (la ruta que usaba
+   `copsis-doctor`), **mueve** su contenido a `.ozali/docs/cdk/` — fusionando **por hito** y **sin
+   sobrescribir** lo que ya exista en el destino — y **elimina** la carpeta `.copsis/` una vez vacía.
+   Si `.copsis/` contiene otras subrutas legadas (p. ej. `.copsis/metrics/`), reubícalas bajo
+   `.ozali/` de forma equivalente antes de borrar `.copsis/`.
+3. **Preserva** el histórico por hito ya en `.ozali/docs/cdk/` y los planes congelados
+   (`02-plan-aprobado.md`): la migración del contrato **nunca** los borra ni reescribe.
+4. **Estampa** `cdk_contract_version: N` en el frontmatter del `cdk` migrado.
+5. **Reporta** al usuario, en texto, qué cambió (referencias migradas, docs reubicados de `.copsis/`
+   a `.ozali/`, secciones actualizadas, versión nueva).
+
+---
+
+## Changelog del contrato
+
+### v1 — contrato base
+Un `cdk` conforme a la v1 debe:
+
+- Estampar `cdk_contract_version: 1` en su frontmatter.
+- En el **cierre de hito**, invocar la skill **`ozali-commit`** (nunca `copsis-commit`) para
+  generar el commit summary convencional (feature→`feat`, bugfix→`fix`, hotfix→`hotfix`,
+  refactor→`refactor`; scope = módulo del hito).
+- Operar **recall-first** (reusar memoria de Engram antes de releer/re-analizar) según
+  [`engram-convention.md`](engram-convention.md) §7.
+- Espejar a Engram los artefactos clave del hito y escribir la telemetría de tokens
+  (`.ozali/metrics/token-metrics.json`, que lee `ozali doctor`).
+- Respetar la calibración de Strict TDD (Fase 3.5) y el 🛑 GATE del plan.

package/skill-commit/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ozali-commit
+description: Genera un "commit summary" convencional (feat/fix/hotfix/refactor) con prefijo, scope y descripción a partir de los cambios EN STAGE y commitea tras tu aprobación. Úsala cuando el usuario quiera "commitea", "haz el commit", "genera el mensaje de commit", "cierra el hito con commit", o cuando otra skill (p. ej. cdk) cierre un hito.
+---
+
+# Skill: ozali-commit
+
+`ozali-commit` produce el **mensaje de commit** de un cambio siguiendo
+[Conventional Commits](https://www.conventionalcommits.org/) y lo **commitea tras tu aprobación**.
+Es la skill de commit vigente del ecosistema `ozali`.
+
+`cdk` la invoca en el **cierre de cada hito**, pero también puedes usarla suelta en cualquier repo.
+
+> **Regla de oro:** nunca commitea sin tu aprobación explícita (🛑 **GATE de mensaje**). El GATE del
+> mensaje es **independiente** del GATE del plan de `cdk`.
+
+> **Cero dependencias:** usa `git` directo (ya habilitado en el perfil base de permisos de ozali:
+> `Bash(git add *)`, `Bash(git commit *)`, `Bash(git status)`, `Bash(git diff *)`,
+> `Bash(git log *)`). No requiere herramientas externas.
+
+---
+
+## Flujo
+
+### 1. Inspecciona el stage
+- `git status --short` — qué hay staged vs sin stage.
+- `git diff --cached` — el contenido **EN STAGE** (la fuente de verdad del mensaje).
+- Si **no hay nada en stage**: dilo y pregunta si quieres que haga `git add` de archivos concretos
+  (o `git add -A`). **No** hagas `add -A` por tu cuenta sin confirmación.
+- Lee el commit anterior con `git log -1 --pretty=%s` para mantener el estilo del repo.
+
+### 2. Determina el tipo y el scope
+A partir del diff EN STAGE, clasifica el cambio:
+
+| Tipo | Cuándo |
+|---|---|
+| `feat` | nueva funcionalidad / capacidad |
+| `fix` | corrección de bug |
+| `hotfix` | corrección urgente en caliente |
+| `refactor` | reestructura sin cambiar comportamiento |
+| `docs` | solo documentación |
+| `test` | solo pruebas |
+| `chore` | mantenimiento (deps, config, build) |
+
+- **Scope** = módulo/área tocada del repo (derívalo de las rutas en stage; ej. `cobranza`, `cli`,
+  `auth`). Si abarca varias áreas, usa la más representativa o un scope general.
+- Si la skill que invoca aporta tipo/scope (p. ej. `cdk` mapea feature→`feat`, bugfix→`fix`,
+  hotfix→`hotfix`, refactor→`refactor`), **respétalos**.
+
+### 3. Redacta el mensaje
+Formato: `tipo(scope): descripción en imperativo, ≤ 72 chars`. Cuerpo opcional (qué/por qué, no el
+cómo). No inventes cambios que no estén en el diff. Idioma: el del repo (mira `git log`).
+
+```
+feat(cobranza): agrega validación de RFC en alta de cotización
+
+- valida formato y dígito verificador antes de persistir
+- cubre el caso de RFC genérico (XAXX010101000)
+```
+
+### 4. 🛑 GATE de mensaje
+Presenta el mensaje completo **como texto visible** y espera aprobación. Si el usuario pide ajustes,
+itera. **No commitees** hasta el "ok".
+
+### 5. Commitea
+Tras la aprobación:
+```bash
+git commit -m "tipo(scope): descripción" [-m "cuerpo…"]
+```
+- Commitea **solo lo que está en stage** (no añadas archivos no aprobados).
+- **No** hagas `git push` (es destructivo/saliente y está denegado por defecto): si el usuario lo
+  quiere, recuérdaselo para que lo haga él.
+- Reporta el hash corto resultante (`git rev-parse --short HEAD`).
+
+---
+
+## Notas
+- Si el repo usa una convención propia (gitmoji, prefijos de ticket), detéctala desde `git log` y
+  síguela.
+- Si el cambio es demasiado grande/heterogéneo para un solo mensaje coherente, **sugiere** dividir
+  en varios commits (pero no lo hagas sin aprobación).