# ADR-0010 — Versionado y upgrade (compatibilidad, `doctor` version-drift, `dai sync`)

- **Estado:** propuesto
- **Fecha:** 2026-07-09
- **Decide:** lead / arquitecto de la metodología

## Contexto

Un equipo scaffoldea su repo con dai `X.Y.Z`. Después publicamos versiones nuevas
(`2.2`, `2.9`, `3.0`). ¿Qué pasa con su trabajo? ¿Tienen que actualizar el CLI y el
repo? Hoy no hay política escrita ni herramienta de upgrade — el equipo queda a ciegas.

Lo que dai deja en un repo no es una cosa, son **cuatro capas** con impacto distinto
ante un upgrade (y una premisa de fondo: dai **da herramientas, no obliga** — MANIFIESTO
Art. 14, "la ceremonia se agrega cuando duele, no antes"):

| Capa | Qué es | Naturaleza |
|---|---|---|
| **CLI** | el binario `dai` (npm global) | por máquina/dev |
| **Copias scaffoldeadas** | skills, constitución (`CLAUDE.md`/rules), templates, PR template | **caché derivable**, commiteado por repo |
| **OpenSpec** | `openspec/` | **herramienta aparte** (@fission-ai/openspec), versionado propio |
| **Dato de trazabilidad** | `implements.yaml` (id, version, **`ac_hash`**) | el **contrato** (ADR-0001, ADR-0004) |

Solo la última capa, si cambia, **invalida trabajo hecho**. Por eso el principio rector
es: **dai no obliga a actualizar** — `doctor` avisa, el equipo decide cuándo.

## Decisión

### 1. La compatibilidad la comunica el semver (formaliza `RELEASING.md`)

- **patch / minor** (`2.0` → `2.2` → `2.9`): el **contrato NO cambia**. Todo lo hecho
  sigue válido; `dai check` da igual que antes. Upgrade **opcional** (fixes/features).
- **major** (`2.x` → `3.0`): puede cambiar el algoritmo del `ac_hash` o el schema del
  `implements.yaml`. Requiere **migración**.

**Invariante duro:** *dentro de una línea major, `ac_hash(input)` es estable* — el hash
que calcula `2.0` es idéntico al de `2.9` para la misma US. Es lo que vuelve seguros a
los minors. Se blinda con **golden vectors de `ac_hash` en CI que NO pueden cambiar
dentro de una major** (romperlos = obligado a bumpear major).

### 2. Las copias son caché derivable, no algo que se mantiene a mano

Las skills/constitución/templates del repo son **copias** de lo que trae el CLI. Una
copia vieja **sigue funcionando** (una skill/constitución vieja es un prompt válido).
No se editan a mano en el repo: se **regeneran** (mismo espíritu que "la cobertura se
deriva"). La fuente de verdad es la versión del CLI.

OpenSpec queda **fuera de alcance**: es otra herramienta con su propio upgrade
(`openspec`), dai solo la instala/inicia. `dai sync` **no** toca OpenSpec.

### 3. `.dai/VERSION` = provenance del scaffold

`dai init` ya estampa con qué versión se scaffoldeó el repo. Es el marcador para
detectar drift entre el repo y el CLI instalado.

### 4. `dai doctor` chequea version-drift

Compara `.dai/VERSION` (repo) contra la versión del CLI instalado y reporta:

| Situación | Mensaje |
|---|---|
| iguales | ✓ al día |
| CLI > repo, **misma major** | ℹ️ refresh disponible (skills/constitución de `vX`, CLI `vY`). `dai sync` cuando quieras — **opcional, nada roto** |
| CLI **major** > repo | ⚠️ cambio mayor: puede tocar el contrato. Ver `MIGRATION.md`/CHANGELOG antes; `dai sync` + `dai migrate` si aplica |
| CLI < repo | ⚠️ tu repo se scaffoldeó con una versión más nueva que tu CLI — actualizá el CLI |

### 5. `dai sync` — refresco **aditivo** de las copias (comando nuevo)

Re-genera skills, constitución (bloque `<!-- dai:start/end -->`), templates y PR
template **a la versión del CLI**, **aditivo e idempotente**. Reusa la maquinaria del
init aditivo: `upsertBlock` (constitución), `mergeEnv` (`.env`/`.env.example`),
`reconcileGitignore`. **No pisa** lo del proyecto (constitución propia, config). Respeta
el `--for` ya presente en el repo y actualiza `.dai/VERSION`.

- Flags: `--dry-run` (qué cambiaría, sin tocar), `--for` (override de asistentes).
- Es **opt-in**: lo corre el equipo cuando quiere.
- Relación con `dai install`: `sync` = `install --local . --force` **consciente de la
  constitución + templates + `.dai/VERSION`**, con reporte de drift. Se puede
  implementar como extensión/alias de `install`, pero el verbo explícito comunica mejor
  la intención (refrescar un repo ya inicializado).

### 6. Majors: `dai migrate` + `MIGRATION.md` + nota BREAKING

Cuando un major cambia el contrato, se provee migración — p. ej. re-derivar y
re-estampar los `ac_hash` en masa (un `link-us --resync` para todos los
`implements.yaml`). Documentado en `MIGRATION.md`, marcado **BREAKING** en el CHANGELOG.
Los majors son **raros y bien soportados**.

### 7. Future-proofing del schema (enmienda menor a ADR-0004)

Estampar `schema: <n>` en el `implements.yaml` para que un futuro `dai migrate` sepa de
qué versión de schema migrar. Se puede **diferir** hasta que un major lo necesite, pero
conviene reservar el campo desde ya.

## Consecuencias

- ✅ El **número de versión comunica el radio de explosión**: el equipo sabe si un
  upgrade es seguro sin leer diffs.
- ✅ Upgrades **opt-in** — respeta el ADN (dai no obliga). `doctor` avisa, el equipo
  decide.
- ✅ Las copias son caché → `dai sync` las refresca sin miedo (aditivo, no pisa).
- ✅ **Reusa** la maquinaria aditiva ya construida y testeada (`upsertBlock`/`mergeEnv`/
  `reconcileGitignore`, v0.3.0) — costo de implementación bajo.
- ⚠️ Obliga a **golden vectors de `ac_hash` en CI** inmutables dentro de una major —
  disciplina de release.
- ⚠️ `dai sync` debe ser **estrictamente aditivo/idempotente**; un bug ahí pisaría
  trabajo (mismo riesgo que tuvo el `init` — ya mitigado y testeado).
- ⚠️ Hay que comunicar que `dai sync` **no** actualiza OpenSpec (upgrade aparte).

## Alternativas consideradas

- **Forzar re-scaffold/upgrade en cada versión** — descartado: viola el ADN (dai no
  obliga); rompería la adopción. dai es como git: no te dicta cómo trabajar.
- **No versionar el scaffold (sin drift check)** — descartado: sin provenance no se
  puede avisar; el equipo queda a ciegas.
- **Mantener las copias a mano** — descartado: contradice "la cobertura se deriva"; las
  copias son caché, la fuente es el CLI.
- **`dai sync` destructivo (pisar y re-copiar)** — descartado: pisaría la constitución
  propia del proyecto. Debe ser aditivo (lección del `init`, v0.3.0).
- **Meter todo en `dai install --force`** — posible; pero `sync` como verbo explícito +
  reporte de drift comunica mejor la intención. Se implementa como extensión de
  `install`.