ozali 0.4.1 → 0.6.0

package/docs/team-history.md

@@ -64,3 +64,55 @@ histórico apunta a un commit exacto.
 
 El contrato concreto de qué se espeja a Engram, cuándo, y el algoritmo de `ozali sync` está en
 [skill/references/engram-convention.md](../skill/references/engram-convention.md) (§3 y §6).
+
+## Engram Cloud: réplica en tiempo real (opt-in)
+
+Además del git-sync, ozali soporta **Engram Cloud** — un servidor central que replica la memoria
+del equipo **en tiempo real** (autosync), sin necesidad de commit/push manual.
+
+### Modelo: cloud-first, git-sync como backup
+
+```
+dev A guarda memoria → autosync → cloud → dev B (autosync recibe)
+                                ↕
+                    git-sync (backup/secondary, repos de conocimiento)
+```
+
+- **Cloud-first**: la réplica es automática e invisible. El repo de conocimiento sigue siendo
+  el backup offline y el canal para docs (que no van a cloud).
+- **Sin cloud**: todo funciona igual con git-sync manual (`ozali sync` + `--push`/`--import`).
+
+### Onboarding de equipo (un dev nuevo en 1 paso)
+
+Cuando un dev nuevo hace `ozali init` en un repo que ya tiene `.ozali/cloud.json` (commiteable,
+sin secretos), el CLI detecta la cloud del equipo y ofrece conectarse automáticamente:
+
+```
+$ ozali init
+✓ Engram Cloud del equipo detectado (servidor: https://engram.mi-empresa.com)
+  → Proyecto: "ozali"
+  → ¿Conectarte a la memoria del equipo? [sí/no]
+  → token: ****
+  → Recibiendo memoria del equipo…
+  → autosync activo (invisible)
+  → Listo.
+```
+
+### Despliegue del servidor
+
+Ver [docs/deploy-cloud-vps.md](deploy-cloud-vps.md) (VPS genérico con docker-compose) y
+[docs/deploy-cloud-gcloud.md](deploy-cloud-gcloud.md) (Google Cloud: Cloud Run o GCE VM).
+
+### Comandos cloud
+
+| Comando | Qué hace |
+|---|---|
+| `ozali sync --cloud` | Push manual a cloud |
+| `ozali sync --cloud --import` | Pull desde cloud (onboarding inverso) |
+| `ozali cloud status` | Estado + último sync + upgrade |
+| `ozali cloud upgrade` | doctor → repair → bootstrap |
+| `ozali cloud dashboard` | Abre el dashboard web |
+| `ozali cloud config` | Re-configura servidor/token |
+
+Detalle del contrato de memoria cloud (scope, idioma, conflictos, troubleshooting) en
+[skill/references/engram-convention.md](../skill/references/engram-convention.md) §8.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ozali",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "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,45 @@ 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 `copsis-commit`** y reemplázala por **`ozali-commit`** (la skill de
+     commit vigente, instalada en `.claude/skills/ozali-commit/`).
+   - 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 `.ozali/docs/cdk/` (histórico por hito) y los planes congelados
+     (`02-plan-aprobado.md`).
+   - **Reporta** al usuario, en texto, qué cambió (referencias migradas, 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 +257,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 +292,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,72 @@
+<!-- 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 `copsis-commit`** (nombre heredado de versiones anteriores) y
+   **reemplázala por `ozali-commit`** — la skill de commit vigente que `ozali init`/`ozali update`
+   instalan en `.claude/skills/ozali-commit/`.
+2. **Preserva** el histórico por hito (`.ozali/docs/cdk/`) y los planes congelados
+   (`02-plan-aprobado.md`): la migración del contrato **nunca** los borra ni reescribe.
+3. **Estampa** `cdk_contract_version: N` en el frontmatter del `cdk` migrado.
+4. **Reporta** al usuario, en texto, qué cambió (referencias migradas, 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/references/engram-convention.md

@@ -269,3 +269,81 @@ artefacto, menos cuesta recuperarlo después.
   agresivo con recall-first (resume antes, evita relecturas grandes).
 
 > `savedByRecall` = estimación de relectura evitada por reusar memoria (ver plantilla `06-uso-tokens`).
+
+---
+
+## 8. Cloud: réplica de equipo en tiempo real
+
+Engram Cloud es una **capa opt-in** que replica la memoria del equipo a un servidor central,
+**adicional al git-sync**. Con autosync activo, la réplica es **automática e invisible**: los devs
+no necesitan correr `ozali sync` manualmente para compartir memoria.
+
+### 8.1 Modelo: cloud-first, git-sync como backup
+
+```
+dev A guarda memoria → autosync → cloud → dev B (autosync recibe)
+                                ↕
+                    git-sync (backup/secondary)
+```
+
+- **Cloud-first**: la réplica es en tiempo real (autosync). El repo de conocimiento sigue siendo
+  el backup offline (ver [team-history](../../docs/team-history.md)).
+- **Sin cloud**: todo funciona igual, solo que el sync es manual (`ozali sync` + `--push`/`--import`).
+
+### 8.2 Cómo se comparten las memorias vía cloud
+
+1. Un dev guarda una observación con `mem_save` (scope: project, español — ver §1.5).
+2. El autosync la replica al servidor cloud automáticamente.
+3. El autosync del otro dev la recibe y la importa a su store local.
+4. Ambos devs pueden buscarla con `mem_search`.
+
+> **Scope + idioma siguen siendo obligatorios** (§1.5): `scope: project` siempre en español,
+> `scope: personal` cualquier idioma. Cloud no cambia esta regla — solo acelera el transporte.
+
+### 8.3 Archivos de configuración
+
+| Archivo | Commiteable | Contiene | Propósito |
+|---|---|---|---|
+| `.ozali/cloud.json` | **Sí** (no lleva secretos) | server, project, enrolled, dashboard URL | Que un dev nuevo detecte la cloud del equipo al hacer `ozali init` |
+| `~/.engram/cloud_token` | No (local) | El token de auth | Persistencia del token entre sesiones |
+| `.claude/settings.json` (env) | Sí | `ENGRAM_CLOUD_AUTOSYNC=1`, `ENGRAM_CLOUD_TOKEN` | Autosync en el MCP del agente |
+
+> El token **nunca** se commitea. `.ozali/cloud.json` solo tiene metadatos sin secretos.
+
+### 8.4 Comandos cloud del CLI
+
+| Comando | Qué hace |
+|---|---|
+| `ozali init` → detecta `.ozali/cloud.json` | Onboarding: conecta al dev nuevo en 1 paso (Fase 1) |
+| `ozali sync --cloud` | Push manual a cloud (además del git-sync) |
+| `ozali sync --cloud --import` | Pull desde cloud (onboarding inverso) |
+| `ozali cloud status` | Estado de enrollment + último sync + upgrade pipeline |
+| `ozali cloud upgrade` | Flujo completo: doctor → repair --apply → bootstrap |
+| `ozali cloud repair` | `engram cloud upgrade repair --apply` |
+| `ozali cloud dashboard` | Abre el dashboard web en el navegador |
+| `ozali cloud config` | Re-configura servidor/token |
+| `ozali audit --conflicts` | Lista conflictos de memoria pendientes |
+| `ozali audit --conflicts --stats` | Estadísticas de conflictos |
+
+### 8.5 Conflictos: qué son y cómo resolverlos
+
+Cuando dos devs guardan memorias que el sistema detecta como **potencialmente conflictivas**
+(misma `topic_key`, contenido divergente), Engram Cloud las marca como conflictos pendientes.
+
+- `ozali doctor` avisa si hay conflictos pendientes (`pending > 0`).
+- `ozali audit --conflicts` los lista.
+- El agente los resuelve con `mem_judge` (ver protocolo de conflict surfacing en las
+  instrucciones del MCP de Engram): `related`, `compatible`, `scoped`, `conflicts_with`,
+  `supersedes`, `not_conflict`.
+- `ozali audit --conflicts --judged` muestra los ya resueltos.
+
+### 8.6 Troubleshooting cloud
+
+| `reason_code` | Significado | Acción |
+|---|---|---|
+| `blocked_unenrolled` | El proyecto no está enrolado en el servidor | `ozali init` o `ozali cloud config` |
+| `transport_failed` | No se pudo conectar al servidor | Verifica URL, red, firewall |
+| `bootstrap_verified` (upgrade) | Todo OK, no necesita upgrade | — |
+| otro (upgrade) | El proyecto requiere upgrade de esquema | `ozali cloud upgrade` |
+
+> `ozali doctor` parsea estos códigos y muestra warnings específicos.

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. Sucesora de copsis-commit.
+---
+
+# 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` (sucede a la antigua `copsis-commit`).
+
+`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).