@dforce2055/dai 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,50 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/). Versionado semver
 (ver `VERSION`).
 
+## [0.5.0] — 2026-07-10
+
+**`archive` en el flujo** ([ADR-0011](docs/adr/0011-archive-gate-de-aprobacion.md)): cerrar el CÓMO
+del lado de las specs canónicas, atado a la aprobación de la PR.
+
+### Agregado
+- **`dai archive [<change>]`**: funde los delta specs del change en las specs canónicas
+  (`openspec/specs/`) y lo archiva. Lo corre el **aprobador** de la PR, en la branch, al aprobar
+  (el fold viaja en la PR → elude la base protegida). Detecta el change activo por su `implements.yaml`
+  o le pasás el nombre; envuelve `openspec archive --yes` (mecánico → comando, no skill). Flag `--skip-specs`.
+
+### Cambiado
+- **`dai check` y `dai ls` saltean `openspec/changes/archive/`**: un change shippeado ya no genera
+  ⚠️ de drift falso ni aparece en el listado. `discoverImplements` acepta `includeArchived` (default
+  `true`); `check`/`ls` lo pasan `false`. `stamp`/`done` mantienen el default (lo necesitan post-merge).
+
+### Interno
+- **110 tests** (+1 desde 0.4.0: filtro `includeArchived`).
+
+## [0.4.0] — 2026-07-10
+
+**Versionado y upgrade** ([ADR-0010](docs/adr/0010-versionado-y-upgrade.md)): mantené tu repo al
+día con el CLI sin pisar nada. Las copias scaffoldeadas (skills, constitución, templates) son un
+caché derivable — ahora la máquina te avisa cuando quedaron atrás y las refresca sola.
+
+### Agregado
+- **`dai sync`**: refresca skills, constitución, templates y PR template a la versión del CLI —
+  **aditivo** (conserva tu `CLAUDE.md` propio vía bloque delimitado), sin tocar el `.env` ni OpenSpec.
+  Detecta los asistentes del repo o acepta `--for`; `--dry-run` muestra qué cambiaría.
+- **`dai doctor` · version-drift**: compara `.dai/VERSION` (scaffold del repo) vs el CLI y avisa con
+  color + `⬆️` (misma major → refresh opcional con `dai sync`; major distinta → revisar migración;
+  repo más nuevo → actualizar el CLI).
+- **`dai version`**: además de la versión, muestra el estado de drift si estás en un repo con dai
+  (chequeo liviano). `dai --version` fuera de un repo dai queda limpio (solo la versión).
+- **`lib/semver.mjs`** (comparación de versiones, cero dependencias).
+
+### Interno
+- **Golden vectors de `ac_hash`**: pineados como inmutables dentro de la línea major — blindan el
+  contrato ([ADR-0001](docs/adr/0001-contrato-ac-hash.md)) que hace seguros a los minors/patches y a `dai sync`.
+- **109 tests** (+4 desde 0.3.1: semver ×3, golden vectors ×1).
+
+> Diferido a un futuro major (ya diseñado en el ADR-0010): `dai migrate` + `MIGRATION.md` y estampar
+> `schema:` en el `implements.yaml`.
+
 ## [0.3.1] — 2026-07-10
 
 Pulido de la experiencia de `dai init` y `dai link-us`, y un ejemplo de US listo para probar.
@@ -122,6 +166,8 @@ ClickUp y Jira Cloud.
 - Tests de las rutas de red (jira/clickup/forge) con `fetch` mockeado. Sin links rotos;
   `files` de npm sin tests ni secretos.
 
+[0.5.0]: https://github.com/dforce2055/dai/releases/tag/v0.5.0
+[0.4.0]: https://github.com/dforce2055/dai/releases/tag/v0.4.0
 [0.3.1]: https://github.com/dforce2055/dai/releases/tag/v0.3.1
 [0.3.0]: https://github.com/dforce2055/dai/releases/tag/v0.3.0
 [0.2.0]: https://github.com/dforce2055/dai/releases/tag/v0.2.0

package/README.md

@@ -158,6 +158,7 @@ flowchart TD
 |---|---|
 | `dai init [<repo>]` | scaffolder interactivo del repo. Flags: `--for claude\|copilot\|both\|cursor\|all` (asistente, default `all`) · `--pm md\|jira\|clickup` (tracker) · `--openspec` |
 | `dai install [--global \| --local <repo>] [--force] [--dry-run] [--for claude\|cursor\|all]` | instala/actualiza skills de IA en Claude y/o Cursor (`--for all` por defecto). `--force` re-copia aunque ya existan. Ej: `dai install --local . --for cursor --force` · `dai install --global --for all --force` |
+| `dai sync [--dry-run] [--for <asistentes>]` | **refresca** skills, constitución, templates y PR template a la versión del CLI — **aditivo** (no pisa tu `CLAUDE.md`), no toca el `.env` ni OpenSpec. Detecta los asistentes del repo o pasás `--for`. `--dry-run` muestra qué cambiaría ([ADR-0010](docs/adr/0010-versionado-y-upgrade.md)) |
 | `dai publish <us.md>` | crea la US en el tracker (Jira/ClickUp/md) desde un `.md` y devuelve el key. Es el fallback del MCP para publicar sin el asistente |
 | `dai link-us <ID> [--us <md>]` | crea branch + `implements.yaml`; sin `--us` trae la US del tracker |
 | `dai link-us <ID> --resync` | re-estampa el `ac_hash` contra la US viva (tras un ⚠️ de check) |
@@ -166,9 +167,17 @@ flowchart TD
 | `dai pr [--assignee u] [--base b] [--draft] [--yes]` | crea TU PR/MR precargada: pregunta la branch base (default `main`), muestra el texto y confirma antes de publicar |
 | `dai stamp` | estampa la cobertura inversa en el tracker (branch + commit-ancla) |
 | `dai done [--base main] [--force]` | cierra la US: vuelve a la base, `fetch --prune` + `pull`, y borra la branch local **si está mergeada** (chequeo estricto; `--force` la borra igual). Redes: no estar en la base, sin cambios sueltos, sin commits sin pushear |
+| `dai archive [<change>] [--skip-specs]` | **funde los delta specs del change en las specs canónicas** (`openspec/specs/`) y lo archiva. Lo corre el **aprobador** de la PR (gate de aprobación, [ADR-0011](docs/adr/0011-archive-gate-de-aprobacion.md)); detecta el change activo o le pasás el nombre. Envuelve `openspec archive` |
 | `dai forge comment <ref> --body-file <f>` · `dai forge pr <ref>` | comentar / leer una PR/MR (GitHub/GitLab) |
 | `dai ac-hash <us.md>` | calcula el hash de los criterios de aceptación de una US |
-| `dai doctor` · `dai docs <dest>` · `dai --version` | diagnóstico del entorno · copiar la doc · versión |
+| `dai doctor` · `dai docs <dest>` · `dai version` | diagnóstico del entorno (incluye **version-drift** del scaffold) · copiar la doc · versión (`dai version` avisa si tu repo quedó atrás) |
+
+> **🆕 Mantené tu repo al día — `dai sync`.** Las skills, la constitución y los templates son un
+> *caché derivable* del CLI. Cuando actualizás `dai` (`npm i -g @dforce2055/dai`), **`dai doctor` y
+> `dai version` te avisan solos** si tu scaffold quedó atrás — con color y un `⬆️` —, y **`dai sync`**
+> lo refresca: **aditivo** (conserva tu `CLAUDE.md` propio), sin tocar el `.env` ni OpenSpec. Probá sin
+> riesgo con `dai sync --dry-run`. El versionado es semver: patch/minor no rompen nada; solo un major
+> pediría migración. ([ADR-0010](docs/adr/0010-versionado-y-upgrade.md))
 
 Skills (se invocan en el asistente): `/doc-to-backlog` · `/grill-intent` · `/grill-epic` · `/grill-user-story` · `/link-us` ·
 `/tdd` · `/dai-review`. Config del tracker (`md`\|`jira`\|`clickup`) y tokens: en `.env` —

package/VERSION

@@ -1 +1 @@
-0.3.1
+0.5.0

package/cli/dai.mjs

@@ -28,6 +28,7 @@ import { parsePrRef, getPR, postComment } from "./lib/forge-api.mjs";
 import { composePrBody, prTitle, forgeTool } from "./lib/pr.mjs";
 import { dirsEqual } from "./lib/fsutil.mjs";
 import { parseFlags, parseAssistants, isAssistantToken } from "./lib/args.mjs";
+import { versionDrift } from "./lib/semver.mjs";
 import { skillToPrompt, skillToCursor, constitution, constitutionCursorRule, envFor, mergeEnv, upsertBlock, reconcileGitignore } from "./lib/bootstrap.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -39,6 +40,10 @@ function fail(msg, code = 1) { process.stderr.write("dai: " + msg + "\n"); proce
 const ok = (m) => process.stdout.write(`✓ ${m}\n`);
 const info = (m) => process.stdout.write(`› ${m}\n`);
 const warn = (m) => process.stdout.write(`⚠ ${m}\n`);
+// Color ANSI mínimo — solo si es TTY y no está NO_COLOR (así no ensucia pipes/CI).
+const _color = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code, m) => (_color ? `\x1b[${code}m${m}\x1b[0m` : m);
+const C = { y: (m) => paint("33", m), r: (m) => paint("31", m), cy: (m) => paint("36", m), b: (m) => paint("1", m) };
 const ROOT = join(HERE, "..");            // raíz del paquete dai (cli/ está adentro)
 const CLAUDE_SKILLS_DIR = process.env.CLAUDE_SKILLS_DIR || join(homedir(), ".claude", "skills");
 const CURSOR_SKILLS_DIR = process.env.CURSOR_SKILLS_DIR || join(homedir(), ".cursor", "skills");
@@ -66,7 +71,7 @@ function cmdAcHash(arg) {
 // ── ls ──────────────────────────────────────────────────────────────────────
 function cmdLs(opts) {
   const root = opts.root || process.cwd();
-  const found = discoverImplements(root);
+  const found = discoverImplements(root, { includeArchived: false });
   const rows = [];
   for (const f of found) {
     for (const im of f.implements || []) {
@@ -165,7 +170,7 @@ function gitCommit() { try { return git(["rev-parse", "HEAD"]); } catch { return
 async function cmdCheck() {
   loadEnv();
   const adapter = getAdapter(process.env);
-  const found = discoverImplements(process.cwd());
+  const found = discoverImplements(process.cwd(), { includeArchived: false });
   let worst = 0, n = 0;
   const atrasadas = [];
   for (const f of found) for (const im of f.implements || []) {
@@ -677,6 +682,146 @@ function cmdDocs(dest) {
   ok(`documentación copiada a ${dest}`);
 }
 
+// ── archive: funde los delta specs del change en los specs canónicos y lo archiva ─
+// Lo corre el APROBADOR de la PR, en la branch, al aprobar: es el gate de aprobación
+// (el fold va atado a la aprobación, no a la autoría). Envuelve `openspec archive
+// <change> --yes` — mecánico, va al CLI y no a una skill (ADR-0002). El fold queda
+// sin commitear para que el aprobador lo revise y lo incluya en la PR antes de mergear.
+function cmdArchive(changeArg, opts) {
+  const repo = process.cwd();
+  if (!existsSync(join(repo, "openspec"))) fail("no hay OpenSpec en este repo (falta openspec/). Nada que archivar.", 2);
+
+  let change = changeArg;
+  if (!change) {
+    // Detectar el change ACTIVO (no archivado) por su implements.yaml.
+    const active = discoverImplements(repo, { includeArchived: false })
+      .filter((f) => /[/\\]openspec[/\\]changes[/\\]/.test(f.path))
+      .map((f) => basename(dirname(f.path)));
+    const uniq = [...new Set(active)];
+    if (uniq.length === 0) fail("no encontré un change activo para archivar (¿ya está archivado, o falta `dai link-us`?).", 2);
+    if (uniq.length > 1) fail(`hay varios changes activos: ${uniq.join(", ")}.\n  Pasá cuál: dai archive <change>`, 2);
+    change = uniq[0];
+  }
+
+  info(`archivando '${change}' — funde los delta specs en openspec/specs/ y mueve el change a archive/…`);
+  const args = ["archive", change, "--yes"];
+  if (opts.skipSpecs) args.push("--skip-specs");
+  try {
+    execFileSync(npmBin("openspec"), args, { stdio: "inherit", cwd: repo });
+  } catch (e) {
+    fail(`openspec archive falló (¿tasks incompletas? ¿change inexistente?): ${String(e.message).split("\n")[0]}`, 1);
+  }
+  process.stdout.write("\n");
+  ok(`'${change}' archivado. Revisá los cambios (specs fundidas + change en archive/) y commitealos en la PR antes de mergear.`);
+}
+
+// ── sync: refresca las copias scaffoldeadas a la versión del CLI (ADR-0010) ───
+// Las copias (skills, constitución, templates, PR template) son un CACHÉ derivable
+// del CLI: `dai sync` las re-genera a la versión instalada, aditivo (no pisa la
+// constitución propia del proyecto). NO toca el `.env` ni OpenSpec. Opt-in.
+function cmdSync(repo, opts) {
+  repo = repo || ".";
+  if (!existsSync(repo)) fail(`no existe el directorio: ${repo}`, 2);
+  const daiDir = join(repo, ".dai");
+  if (!existsSync(daiDir)) fail("este repo no tiene dai (falta .dai/). Corré `dai init` primero.", 2);
+
+  // Asistentes: --for override, o detectar los que ya están en el repo.
+  let want;
+  if (typeof opts.for === "string") {
+    try { want = parseAssistants(opts.for); } catch (e) { fail(`--for ${e.message}`); }
+  } else {
+    want = {
+      claude: existsSync(join(repo, ".claude", "skills")),
+      copilot: existsSync(join(repo, ".github", "prompts")),
+      cursor: existsSync(join(repo, ".cursor", "skills")),
+    };
+    if (!want.claude && !want.copilot && !want.cursor)
+      fail("no detecté asistentes instalados (.claude/.cursor/.github/prompts). Pasá --for.", 2);
+  }
+
+  const cliV = readFileSync(join(ROOT, "VERSION"), "utf8").trim();
+  const repoV = existsSync(join(daiDir, "VERSION")) ? readFileSync(join(daiDir, "VERSION"), "utf8").trim() : "?";
+  const dry = !!opts.dryRun;
+  const forStr = [want.claude && "claude", want.copilot && "copilot", want.cursor && "cursor"].filter(Boolean).join("+");
+  info(`dai sync — ${repoV} → v${cliV}  ·  asistentes: ${forStr}${dry ? "  [dry-run]" : ""}`);
+
+  const skillsSrc = join(ROOT, "skills");
+  const skills = readdirSync(skillsSrc).filter((n) => statSync(join(skillsSrc, n)).isDirectory());
+  const step = (label, fn) => { if (dry) info(`[dry-run] ${label}`); else { fn(); ok(label); } };
+
+  // 1. .dai/ (templates + governance) + VERSION
+  step(`.dai/         moldes + governance → v${cliV}`, () => {
+    for (const sub of ["templates", "governance"]) {
+      const src = join(ROOT, sub);
+      if (existsSync(src)) { mkdirSync(join(daiDir, sub), { recursive: true }); cpSync(src, join(daiDir, sub), { recursive: true }); }
+    }
+    writeFileSync(join(daiDir, "VERSION"), readFileSync(join(ROOT, "VERSION"), "utf8"));
+  });
+
+  // 2. PR template
+  step(".github/      pull_request_template.md", () => {
+    mkdirSync(join(repo, ".github"), { recursive: true });
+    cpSync(join(ROOT, "templates", "pull-request.md"), join(repo, ".github", "pull_request_template.md"));
+  });
+
+  // 3. skills + constitución por asistente (aditivo: upsertBlock no pisa lo del proyecto)
+  if (want.claude) step(`Claude:       .claude/skills/ (${skills.length}) + CLAUDE.md (bloque dai)`, () => {
+    const dir = join(repo, ".claude", "skills"); mkdirSync(dir, { recursive: true });
+    for (const name of skills) cpSync(join(skillsSrc, name), join(dir, name), { recursive: true });
+    const cPath = join(repo, "CLAUDE.md"), cCur = existsSync(cPath) ? readFileSync(cPath, "utf8") : "";
+    writeFileSync(cPath, upsertBlock(cCur, constitution("claude")));
+  });
+  if (want.copilot) step(`Copilot:      .github/prompts/ (${skills.length}) + copilot-instructions.md`, () => {
+    const pdir = join(repo, ".github", "prompts"); mkdirSync(pdir, { recursive: true });
+    for (const name of skills) writeFileSync(join(pdir, `${name}.prompt.md`), skillToPrompt(readFileSync(join(skillsSrc, name, "SKILL.md"), "utf8")));
+    const ciPath = join(repo, ".github", "copilot-instructions.md"), ciCur = existsSync(ciPath) ? readFileSync(ciPath, "utf8") : "";
+    writeFileSync(ciPath, upsertBlock(ciCur, constitution("copilot")));
+  });
+  if (want.cursor) step(`Cursor:       .cursor/skills/ (${skills.length}) + .cursor/rules/dai-constitution.mdc`, () => {
+    const dir = join(repo, ".cursor", "skills"); mkdirSync(dir, { recursive: true });
+    for (const name of skills) {
+      const src = join(skillsSrc, name), target = join(dir, name);
+      cpSync(src, target, { recursive: true });
+      writeFileSync(join(target, "SKILL.md"), skillToCursor(readFileSync(join(src, "SKILL.md"), "utf8")));
+    }
+    mkdirSync(join(repo, ".cursor", "rules"), { recursive: true });
+    writeFileSync(join(repo, ".cursor", "rules", "dai-constitution.mdc"), constitutionCursorRule());
+  });
+
+  // 4. .gitignore: versiona los artefactos, deja fuera solo lo personal
+  const giPath = join(repo, ".gitignore");
+  const gi = reconcileGitignore(existsSync(giPath) ? readFileSync(giPath, "utf8") : "", want);
+  if (gi.changed) step(".gitignore    ajustado (artefactos versionados; settings.local.json fuera)",
+    () => writeFileSync(giPath, gi.text.endsWith("\n") ? gi.text : gi.text + "\n"));
+
+  if (dry) info("dry-run: nada escrito. Quitá --dry-run para aplicar.");
+  else { process.stdout.write("\n"); ok(`sync completo — .dai/ ahora en v${cliV}`); process.stdout.write("  (El .env y OpenSpec no se tocan: OpenSpec se actualiza aparte con `openspec`.)\n"); }
+}
+
+// Imprime el estado de version-drift del scaffold (ADR-0010) con color + ícono.
+// Reutilizado por `dai doctor` y `dai version`. Devuelve el estado, o null si el
+// directorio no tiene dai (.dai/VERSION). No imprime nada en ese caso.
+function reportDrift(repo = process.cwd()) {
+  const vf = join(repo, ".dai", "VERSION");
+  if (!existsSync(vf)) return null;
+  const repoV = readFileSync(vf, "utf8").trim();
+  const cliV = readFileSync(join(ROOT, "VERSION"), "utf8").trim();
+  const status = versionDrift(repoV, cliV);
+  switch (status) {
+    case "current":
+      ok(`.dai/ al día con el CLI (v${repoV})`); break;
+    case "minor-behind":
+      process.stdout.write(`${C.b(C.y("⬆️  actualización disponible"))} — CLI ${C.b("v" + cliV)}, tu repo ${repoV}. Actualizá con ${C.cy("dai sync")} · probá con ${C.cy("dai sync --dry-run")}\n`); break;
+    case "major-behind":
+      process.stdout.write(`${C.b(C.r("⚠️  cambio MAYOR"))} — CLI ${C.b("v" + cliV)}, tu repo ${repoV}. Revisá el CHANGELOG/MIGRATION antes de ${C.cy("dai sync")}\n`); break;
+    case "cli-behind":
+      process.stdout.write(`${C.b(C.y("⚠️  CLI atrasado"))} — tu repo se scaffoldeó con v${repoV}, más nuevo que tu CLI (v${cliV}). Actualizá el CLI: ${C.cy("npm i -g @dforce2055/dai")}\n`); break;
+    default:
+      warn(`.dai/ VERSION ilegible: '${repoV}'`);
+  }
+  return status;
+}
+
 // ── doctor: diagnóstico ───────────────────────────────────────────────────────
 function cmdDoctor() {
   loadEnv();
@@ -727,11 +872,15 @@ function cmdDoctor() {
     process.env.DAI_CLICKUP_LIST_ID ? ok(`lista=${process.env.DAI_CLICKUP_LIST_ID} (para dai publish)`)
       : warn("DAI_CLICKUP_LIST_ID vacío — solo hace falta para `dai publish` (crear tareas)");
   }
+
+  // ── version-drift del scaffold vs el CLI (ADR-0010) ──────────────────────────
+  if (existsSync(join(process.cwd(), ".dai", "VERSION"))) { info("versión del scaffold:"); reportDrift(); }
 }
 
 // ── version ───────────────────────────────────────────────────────────────────
 function cmdVersion() {
   process.stdout.write(`dai v${readFileSync(join(HERE, "..", "VERSION"), "utf8").trim()}\n`);
+  reportDrift();   // en un repo con dai, avisa si el scaffold está atrasado (ADR-0010)
 }
 
 let [cmd, ...rest] = process.argv.slice(2);
@@ -748,8 +897,10 @@ switch (cmd) {
   case "publish": cmdPublish(pos[0]).catch((e) => fail(String(e.message))); break;
   case "pr":      cmdPr(opts).catch((e) => fail(String(e.message))); break;
   case "done":    cmdDone(opts); break;
+  case "archive": cmdArchive(pos[0], opts); break;
   case "install": cmdInstall(opts).catch((e) => fail(String(e.message))); break;
   case "init":    cmdInit(pos[0], opts).catch((e) => fail(String(e.message))); break;
+  case "sync":    cmdSync(pos[0], opts); break;
   case "docs":    cmdDocs(pos[0]); break;
   case "doctor":  cmdDoctor(); break;
   case "version": cmdVersion(); break;
@@ -765,6 +916,7 @@ switch (cmd) {
       "  check                        compara vs la US viva → atrasado (ADR-0003)\n" +
       "  stamp                        estampa la cobertura en el tracker (ADR-0005)\n" +
       "  done [--base main] [--force] cierra la US: vuelve a la base, actualiza y borra la branch local (si está mergeada)\n" +
+      "  archive [<change>] [--skip-specs]   funde los delta specs del change en las specs canónicas y lo archiva (lo corre el aprobador en la PR)\n" +
       "  pr [--assignee u] [--base b] [--draft] [--yes]   crea TU PR/MR precargada (muestra + confirma)\n" +
       "  forge comment <ref> --body-file <f> · forge pr <ref>   comentar/leer una PR ajena (github/gitlab)\n\n" +
       "Instalación:\n" +
@@ -773,6 +925,7 @@ switch (cmd) {
       "       --for <asistentes>      claude|copilot|cursor (combinables con coma) · o both|all (default all)\n" +
       "                               ej: --for claude,cursor · --for copilot · --for all\n" +
       "       --pm md|jira|clickup · --openspec   (con flags salteas las preguntas)\n" +
+      "  sync [<repo>] [--dry-run] [--for <asistentes>]   refresca skills/constitución/templates a la versión del CLI (aditivo; no toca .env ni OpenSpec)\n" +
       "  docs <destino>               documentación conceptual → <destino>\n" +
       "  doctor                       diagnóstico del entorno\n\n" +
       "  (config: .env — ver .env.example)\n"

package/cli/lib/implements.mjs

@@ -71,7 +71,10 @@ export function parseImplements(text) {
 }
 
 // Camina el árbol desde root y devuelve { path, ...parsed } por cada implements.yaml.
-export function discoverImplements(root) {
+// `includeArchived: false` saltea `openspec/changes/archive/` — los changes shippeados
+// no deben aparecer en `check`/`ls` (ADR-0010). Por defecto los incluye (stamp/done los
+// necesitan post-merge).
+export function discoverImplements(root, { includeArchived = true } = {}) {
   const found = [];
   const walk = (dir) => {
     let entries;
@@ -81,7 +84,9 @@ export function discoverImplements(root) {
       let st;
       try { st = statSync(full); } catch { continue; }
       if (st.isDirectory()) {
-        if (!SKIP_DIRS.has(name)) walk(full);
+        if (SKIP_DIRS.has(name)) continue;
+        if (!includeArchived && name === "archive") continue;
+        walk(full);
       } else if (name === "implements.yaml") {
         try {
           found.push({ path: full, ...parseImplements(readFileSync(full, "utf8")) });

package/cli/lib/semver.mjs

@@ -0,0 +1,30 @@
+// dai · comparación mínima de versiones semver (X.Y.Z). Cero dependencias.
+// Se usa para el chequeo de version-drift (`dai doctor`) y `dai sync` (ADR-0010).
+
+export function parseVersion(v) {
+  const m = String(v ?? "").trim().match(/^(\d+)\.(\d+)\.(\d+)/);
+  return m ? { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) } : null;
+}
+
+// -1 / 0 / 1 (a<b / a==b / a>b), o null si alguna no parsea.
+export function compareVersions(a, b) {
+  const pa = parseVersion(a), pb = parseVersion(b);
+  if (!pa || !pb) return null;
+  const d = (pa.major - pb.major) || (pa.minor - pb.minor) || (pa.patch - pb.patch);
+  return d < 0 ? -1 : d > 0 ? 1 : 0;
+}
+
+// Estado del scaffold del repo (repoV, de `.dai/VERSION`) frente al CLI instalado (cliV):
+//   current      → iguales
+//   minor-behind → CLI adelante, MISMA major (refresh opcional con `dai sync`, nada roto)
+//   major-behind → CLI adelante, major DISTINTA (revisar CHANGELOG/MIGRATION antes)
+//   cli-behind   → el repo se scaffoldeó con una versión más nueva que el CLI (actualizá el CLI)
+//   unknown      → alguna versión no parseable
+export function versionDrift(repoV, cliV) {
+  const r = parseVersion(repoV), c = parseVersion(cliV);
+  if (!r || !c) return "unknown";
+  const cmp = compareVersions(cliV, repoV);
+  if (cmp === 0) return "current";
+  if (cmp < 0) return "cli-behind";
+  return c.major > r.major ? "major-behind" : "minor-behind";
+}

package/docs/adr/0011-archive-gate-de-aprobacion.md

@@ -0,0 +1,68 @@
+# ADR-0011 — `archive` es un gate de aprobación (`dai archive`)
+
+- **Estado:** aceptado
+- **Fecha:** 2026-07-10
+- **Decide:** lead / arquitecto de la metodología
+
+## Contexto
+
+OpenSpec tiene `archive`: cuando un change está completo, **funde sus delta specs** en las
+specs canónicas (`openspec/specs/<capability>/spec.md`) y **mueve el change** a
+`openspec/changes/archive/`. Pero en el flujo dai (`link-us → propose → apply/tdd → check
+→ pr → dai-review → merge → stamp → done`) el `archive` **no tenía lugar**: ni cuándo, ni
+quién. Sin eso, las specs vivas del repo quedan desincronizadas de lo shippeado.
+
+Dos preguntas de fondo: **¿quién lo corre?** y **¿en qué momento?**
+
+## Decisión
+
+### `archive` = el acto de aceptar el change en las specs canónicas → lo hace **quien aprueba la PR**
+
+Fundir un change en las specs oficiales es **bendecir** ese cambio. Por eso lo ata a la
+**aprobación**, no a la autoría: lo corre **quien aprueba la PR**, no el autor. Es un
+**gate de aprobación**, no un paso de cierre del autor (un autor no debería fundir sus
+propios cambios en la spec oficial de un equipo).
+
+Ownership por **dial de ceremonia** (N1/N2/N3):
+
+- **N1/N2 — `dai archive` (comando):** el aprobador lo corre **en la branch de la PR** al
+  aprobar → funde los deltas + mueve el change + lo deja **sin commitear** para revisarlo →
+  lo incluye en la PR → mergea normal. **Resuelve solo el problema de base protegida**: el
+  fold viaja dentro de la PR, no hay push directo a `main`.
+- **N3 — workflow de CI opt-in** (roadmap): el merge aprobado dispara el `archive` solo.
+
+### `dai archive` es un **comando**, no una skill
+
+Archivar es **mecánico** (detectar el change + `openspec archive <change> --yes`): sin
+juicio → va al CLI, como `dai stamp`/`check`/`done` (ADR-0002). `dai-review` es skill
+porque revisar código sí requiere juicio; archivar no. `dai archive` **envuelve**
+`openspec archive`, detectando el change activo por su `implements.yaml` (reusa
+`discoverImplements`); si hay varios, pide el nombre.
+
+### `dai check` y `dai ls` saltean `openspec/changes/archive/`
+
+Un change archivado está **shippeado**: no debe aparecer en `check` (daría un ⚠️ de drift
+falso si el PO edita esa US después) ni en `ls`. `discoverImplements` acepta
+`includeArchived` (default `true`); `check`/`ls` lo pasan en `false`. **`dai stamp`/`done`/
+`archive` mantienen el default** — sí necesitan encontrar el `implements.yaml` (p. ej.
+`stamp` post-merge, cuando el change ya se archivó en la branch).
+
+## Consecuencias
+
+- ✅ El `archive` queda **atado a la aprobación** — las specs canónicas reflejan solo lo bendecido.
+- ✅ La variante `dai archive` (N1/N2) **elude la base protegida** sin tokens ni CI: el fold entra por la PR.
+- ✅ `check`/`ls` dejan de reportar ruido de changes shippeados.
+- ✅ Coherente con el ADN: es una **herramienta opcional** (no obliga), mecánica → CLI.
+- ⚠️ Edge: en PRs desde **fork**, el aprobador puede no tener push a la branch del autor →
+  ahí cae al workflow de CI, o lo corre el autor.
+- ⚠️ El **nudge** (que `/dai-review` recuerde archivar al aprobar) y el **workflow de CI**
+  quedan como follow-up (roadmap), igual que documentar el paso en `SCRUM-CON-IA`.
+
+## Alternativas consideradas
+
+- **Que lo corra el autor, en el PR** — descartado: fundir en la spec oficial es un acto de
+  aprobación; el autor no debería bendecir su propio cambio. Va atado a quien aprueba.
+- **Post-merge sobre la base (commit directo)** — descartado como default: choca con branch
+  protection (push directo a `main`). Queda para el workflow de CI (con follow-up PR o App token).
+- **Una skill `/dai-archive`** — descartado: archivar es mecánico, no necesita un LLM (ADR-0002).
+  El comando puede invocarse desde el asistente igual, sin ser skill.

package/docs/adr/README.md

@@ -16,6 +16,7 @@ decisión cambia, se escribe un ADR nuevo que supersede al viejo. Molde en
 | [0008](0008-estrategia-de-i18n.md) | Estrategia de i18n: fuente única (español) + traducciones derivadas, `DAI_LANG` en el CLI, por fases | propuesto |
 | [0009](0009-adaptador-cursor.md) | Adaptador nativo para Cursor (skills + rules) con `dai init`/`install`/`doctor` | propuesto |
 | [0010](0010-versionado-y-upgrade.md) | Versionado y upgrade: compatibilidad por semver, `doctor` version-drift, `dai sync` aditivo | propuesto |
+| [0011](0011-archive-gate-de-aprobacion.md) | `archive` es un gate de aprobación: `dai archive` (comando) lo corre el aprobador; `check`/`ls` saltean `archive/` | aceptado |
 
 > Estas son las decisiones que cierran las "Decisiones abiertas" de
 > [`METODOLOGIA.md §7`](../METODOLOGIA.md) y las enmiendas al

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforce2055/dai",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Metodología de desarrollo asistido por IA — CLI de acciones deterministas (trazabilidad QUÉ↔CÓMO).",
   "repository": { "type": "git", "url": "git+https://github.com/dforce2055/dai.git" },
   "homepage": "https://dforce2055.github.io/dai/",