@dforce2055/dai 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -3,6 +3,53 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/). Versionado semver
 (ver `VERSION`).
 
+## [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.
+
+### Corregido
+- **`dai init` · `.env.example`**: ahora refleja el `--pm` elegido — incluye todas las claves del
+  tracker (con el `..._TOKEN`), en vez del template genérico `md`. Antes, al elegir jira/clickup,
+  el `.env.example` quedaba con `DAI_PM=md` y sin el token.
+- **`dai init` · `--for` con espacio**: mensaje claro cuando `--for claude, cursor` (con espacio) hace
+  que la shell parta la lista y un token de asistente caiga como `<repo>` ("no existe el directorio: cursor").
+- **`dai link-us` · `dai ac-hash`**: mensaje accionable cuando la US no tiene sección
+  'Criterios de aceptación' — sugiere agregarla o correr `/grill-user-story <ID>`.
+
+### Agregado
+- **`templates/formato-us.md`**: ejemplo de US copy-paste al final (con criterios testeables) para
+  probar el flujo en 30 segundos, con o sin tracker (`dai ac-hash` / `dai link-us --us … --dry-run`).
+
+### Interno
+- **105 tests** (+1 desde 0.3.0: `isAssistantToken`).
+
+## [0.3.0] — 2026-07-08
+
+`dai init` ahora es **aditivo**: no pisa la configuración de un repo funcional. Más
+robustez en el parser de `.env` y en `doctor`, y nuevas buenas prácticas agnósticas en
+la constitución.
+
+### Cambiado
+- **`dai init` es aditivo y no destructivo** sobre un repo con config existente:
+  - `.env` / `.env.example`: mergea solo las claves de dai que faltan (no reescribe lo del proyecto).
+  - `CLAUDE.md` / `copilot-instructions.md`: inserta la constitución como bloque delimitado
+    (`<!-- dai:start/end -->`), idempotente — conserva la constitución previa del proyecto.
+  - `.gitignore`: reconcilia para versionar skills y comandos (`.claude/skills/`, `.claude/commands/`),
+    dejando fuera solo lo personal (`settings.local.json`); quita ignores "broad" (`.claude/`, `CLAUDE.md`)
+    que los escondían.
+- **Constitución**: nuevas reglas agnósticas (verificar el comportamiento ≠ que compile, la IA confirma
+  antes de construir, docs vivas) + sección "Buenas prácticas (agnósticas)". Tono "tú" neutro.
+
+### Corregido
+- **Parser de `.env`** (`env.mjs`): recorta el comentario inline en valores sin comillas — un token con
+  `# ...` al lado ya no rompe el header `Authorization` (error de ByteString).
+- **`dai doctor`**: enumera solo directorios; ya no lista `.DS_Store` como skill.
+
+### Interno
+- **104 tests** (+11 desde 0.2.0: `mergeEnv`, `upsertBlock`, `reconcileGitignore`, parser de `env.mjs`).
+- El sitio (`index.html`, `onboarding.html`) sale del paquete npm (`files[]`) — es capa visual del repo/web.
+- Nueva página de onboarding del dev (`onboarding.html`) en el sitio de GitHub Pages.
+
 ## [0.2.0] — 2026-07-08
 
 Soporte para **Cursor** como asistente y un `--for` combinable. Incluye la **primera
@@ -75,6 +122,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.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
 [0.1.1]: https://github.com/dforce2055/dai/releases/tag/v0.1.1
 [0.1.0]: https://github.com/dforce2055/dai/releases/tag/v0.1.0

package/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.1

package/cli/dai.mjs

@@ -27,8 +27,8 @@ import { branchUrl, commitUrl, parseRemote, detectForge } from "./lib/forge-url.
 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 } from "./lib/args.mjs";
-import { skillToPrompt, skillToCursor, constitution, constitutionCursorRule, envFor } from "./lib/bootstrap.mjs";
+import { parseFlags, parseAssistants, isAssistantToken } from "./lib/args.mjs";
+import { skillToPrompt, skillToCursor, constitution, constitutionCursorRule, envFor, mergeEnv, upsertBlock, reconcileGitignore } from "./lib/bootstrap.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -59,7 +59,7 @@ function trackerUrl(id) {
 function cmdAcHash(arg) {
   const md = arg ? readFileSync(arg, "utf8") : readFileSync(0, "utf8");
   const h = acHash(md);
-  if (h == null) fail("la US no tiene bloque de 'Criterios de aceptación'.", 2);
+  if (h == null) fail("la US no tiene un bloque 'Criterios de aceptación' (criterios testeables bajo '## Criterios de aceptación').", 2);
   process.stdout.write(h + "\n");
 }
 
@@ -98,7 +98,7 @@ async function cmdLinkUs(key, opts) {
     // Fuente local: un .md con la US.
     const md = readFileSync(opts.us, "utf8");
     hash = acHash(md);
-    if (hash == null) fail("la US no tiene 'Criterios de aceptación' → no se puede calcular ac_hash.", 2);
+    if (hash == null) fail(`la US en ${opts.us} no tiene una sección 'Criterios de aceptación' con criterios testeables → sin ac_hash.\n  Agregá los criterios bajo '## Criterios de aceptación', o corré /grill-user-story para pulir la US.`, 2);
     title = opts.title || extractTitle(md);
   } else {
     // Fuente tracker: traer la US del adaptador (mismo hash que usará `dai check`).
@@ -107,7 +107,7 @@ async function cmdLinkUs(key, opts) {
     const us = await adapter.fetchUS(key);
     if (!us) fail(`no encontré la US ${key} en el backend ${adapter.kind}. Pasa --us <md> o revisa el .env.`, 2);
     hash = us.ac_hash;
-    if (hash == null) fail(`la US ${key} no tiene 'Criterios de aceptación' → sin ac_hash.`, 2);
+    if (hash == null) fail(`la US ${key} no tiene una sección 'Criterios de aceptación' con criterios testeables → sin ac_hash, no se puede linkear.\n  Agregá la sección en el tracker, o corré /grill-user-story ${key} para pulir la US (te interroga y la re-publica).`, 2);
     title = opts.title || us.title;
     version = us.spec_version || "v1";
   }
@@ -500,21 +500,16 @@ async function askYesNo(rl, q, def = false) {
   return ["s", "si", "sí", "y", "yes"].includes(a);
 }
 
-// Asegura que ciertas entradas estén en el .gitignore del repo (crea o agrega).
-function ensureGitignored(repo, entries) {
-  const gi = join(repo, ".gitignore");
-  const cur = existsSync(gi) ? readFileSync(gi, "utf8") : "";
-  const have = new Set(cur.split(/\r?\n/).map((s) => s.trim()));
-  const add = entries.filter((e) => !have.has(e));
-  if (add.length === 0) return false;
-  writeFileSync(gi, cur + (cur && !cur.endsWith("\n") ? "\n" : "") + "\n# dai — secretos, no commitear\n" + add.join("\n") + "\n");
-  return true;
-}
-
 // ── init: scaffolder interactivo del repo ─────────────────────────────────────
 async function cmdInit(repo, opts) {
   repo = repo || ".";   // por defecto, el directorio actual (como git init / npm init)
-  if (!existsSync(repo)) fail(`no existe el directorio: ${repo}`);
+  if (!existsSync(repo)) {
+    // Error común: `--for claude, cursor` con espacio → la shell parte y 'cursor' cae acá como repo.
+    const hint = isAssistantToken(repo)
+      ? `\n  ¿Separaste --for con un espacio? '${repo}' quedó como <repo>. Usá coma SIN espacio: --for claude,cursor`
+      : "";
+    fail(`no existe el directorio: ${repo}${hint}`);
+  }
   const rl = process.stdin.isTTY ? createInterface({ input: process.stdin, output: process.stdout }) : null;
 
   process.stdout.write("\n  dai · configurar este repo para desarrollo asistido por IA\n");
@@ -568,11 +563,28 @@ async function cmdInit(repo, opts) {
   writeFileSync(join(dai, "VERSION"), readFileSync(join(ROOT, "VERSION"), "utf8"));
   ok(".dai/         moldes (templates) + reglas (governance) del método");
 
-  cpSync(join(ROOT, ".env.example"), join(repo, ".env.example"));
-  const envPath = join(repo, ".env");
-  if (existsSync(envPath)) warn(".env          ya existe — lo dejo como está");
-  else { writeFileSync(envPath, envFor(pm)); ok(`.env          listo, DAI_PM=${pm}${pm === "md" ? "" : " (completa el token)"}`); }
-  if (ensureGitignored(repo, [".env"])) ok(".gitignore    .env agregado (los tokens NO se commitean)");
+  // .env.example — aditivo, reflejando el --pm elegido: mismas claves que el .env
+  // (con valores VACÍOS, sin secretos) para que el token del tracker esté presente.
+  const exSrc = envFor(pm);
+  const exPath = join(repo, ".env.example");
+  if (existsSync(exPath)) {
+    const cur = readFileSync(exPath, "utf8"), merged = mergeEnv(cur, exSrc);
+    if (merged !== cur) { writeFileSync(exPath, merged); ok(".env.example  claves de dai agregadas (aditivo)"); }
+    else ok(".env.example  ya tenía la config de dai");
+  } else { writeFileSync(exPath, exSrc); ok(".env.example  creado"); }
+
+  // .env — aditivo: agrega las claves de dai que falten; si no existe, lo crea.
+  const envPath = join(repo, ".env"), envBlock = envFor(pm);
+  if (existsSync(envPath)) {
+    const cur = readFileSync(envPath, "utf8"), merged = mergeEnv(cur, envBlock);
+    if (merged !== cur) { writeFileSync(envPath, merged); ok(`.env          claves de dai agregadas (aditivo, DAI_PM=${pm}${pm === "md" ? "" : " — completa el token"})`); }
+    else ok(".env          ya tenía la config de dai");
+  } else { writeFileSync(envPath, envBlock); ok(`.env          listo, DAI_PM=${pm}${pm === "md" ? "" : " (completa el token)"}`); }
+
+  // .gitignore — versiona los artefactos de dai (según --for), deja fuera solo lo personal.
+  const giPath = join(repo, ".gitignore");
+  const gi = reconcileGitignore(existsSync(giPath) ? readFileSync(giPath, "utf8") : "", want);
+  if (gi.changed) { writeFileSync(giPath, gi.text.endsWith("\n") ? gi.text : gi.text + "\n"); ok(".gitignore    ajustado (skills/constitución versionadas; .env y settings.local.json fuera)"); }
 
   mkdirSync(join(repo, ".github"), { recursive: true });
   cpSync(join(ROOT, "templates", "pull-request.md"), join(repo, ".github", "pull_request_template.md"));
@@ -585,15 +597,17 @@ async function cmdInit(repo, opts) {
     const dir = join(repo, ".claude", "skills");
     mkdirSync(dir, { recursive: true });
     for (const name of skills) cpSync(join(skillsSrc, name), join(dir, name), { recursive: true });
-    writeFileSync(join(repo, "CLAUDE.md"), constitution("claude"));
-    ok(`Claude:       .claude/skills/ (${skills.length}) + CLAUDE.md → conoce el método y las skills`);
+    const cPath = join(repo, "CLAUDE.md"), cCur = existsSync(cPath) ? readFileSync(cPath, "utf8") : "";
+    writeFileSync(cPath, upsertBlock(cCur, constitution("claude")));
+    ok(`Claude:       .claude/skills/ (${skills.length}) + CLAUDE.md${cCur ? " (bloque dai, aditivo)" : ""} → conoce el método y las skills`);
   }
   if (wantCopilot) {
     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")));
-    writeFileSync(join(repo, ".github", "copilot-instructions.md"), constitution("copilot"));
-    ok(`Copilot:      .github/prompts/ (${skills.length}) + copilot-instructions.md`);
+    const ciPath = join(repo, ".github", "copilot-instructions.md"), ciCur = existsSync(ciPath) ? readFileSync(ciPath, "utf8") : "";
+    writeFileSync(ciPath, upsertBlock(ciCur, constitution("copilot")));
+    ok(`Copilot:      .github/prompts/ (${skills.length}) + copilot-instructions.md${ciCur ? " (bloque dai, aditivo)" : ""}`);
   }
   if (wantCursor) {
     const dir = join(repo, ".cursor", "skills");
@@ -670,9 +684,11 @@ function cmdDoctor() {
 
   // Una skill sirve si está en el repo actual (.claude/skills, la puso `dai init`)
   // O global (~/.claude/skills, la puso `dai install`). Reportamos dónde.
+  const skillsRoot = join(ROOT, "skills");
+  const skillNames = readdirSync(skillsRoot).filter((n) => statSync(join(skillsRoot, n)).isDirectory());
   const localDir = join(process.cwd(), ".claude", "skills");
   info("skills (repo local / global ~/.claude/skills):");
-  for (const name of readdirSync(join(ROOT, "skills"))) {
+  for (const name of skillNames) {
     const local = existsSync(join(localDir, name)), global = existsSync(join(CLAUDE_SKILLS_DIR, name));
     if (local && global) ok(`${name}  (local + global)`);
     else if (local) ok(`${name}  (local, este repo)`);
@@ -682,7 +698,7 @@ function cmdDoctor() {
 
   const cursorLocalDir = join(process.cwd(), ".cursor", "skills");
   info("skills Cursor (repo local / global ~/.cursor/skills):");
-  for (const name of readdirSync(join(ROOT, "skills"))) {
+  for (const name of skillNames) {
     const local = existsSync(join(cursorLocalDir, name)), global = existsSync(join(CURSOR_SKILLS_DIR, name));
     if (local && global) ok(`${name}  (local + global)`);
     else if (local) ok(`${name}  (local, este repo)`);

package/cli/lib/args.mjs

@@ -5,6 +5,12 @@
 
 export const camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 
+// Tokens válidos de `--for`. Sirve para detectar el error común de separar la lista
+// con un espacio (`--for claude, cursor`): la shell parte antes de que dai lo vea, y
+// `cursor` cae como posicional (el `<repo>`). Con esto damos un hint claro.
+const ASSISTANT_TOKENS = new Set(["claude", "copilot", "cursor", "both", "all"]);
+export const isAssistantToken = (s) => ASSISTANT_TOKENS.has(String(s ?? "").toLowerCase());
+
 // Parsea el valor de `--for` como una LISTA COMBINABLE de asistentes.
 // Acepta "claude", "copilot", "cursor" (combinables con coma o espacio),
 // "both" (= claude+copilot) y "all" (= los tres). Lanza si hay un token inválido.

package/cli/lib/bootstrap.mjs

@@ -53,11 +53,66 @@ export function envFor(pm) {
   return head + "DAI_PM=md\nDAI_MD_US_DIR=.dai/us\n";
 }
 
+// ── Helpers aditivos para `dai init` — no destruir la config de un repo vivo ──
+
+// Une aditivamente variables de entorno: agrega solo las claves KEY= que NO estén
+// ya definidas en `existing`. Idempotente; no toca lo demás. Ignora comentarios.
+export function mergeEnv(existing, block) {
+  const keyOf = (line) => {
+    const m = line.match(/^\s*(?:export\s+)?([\w.-]+)\s*=/);
+    return m ? m[1] : null;
+  };
+  const have = new Set(existing.split(/\r?\n/).map(keyOf).filter(Boolean));
+  const toAdd = block.split(/\r?\n/).filter((line) => { const k = keyOf(line); return k && !have.has(k); });
+  if (toAdd.length === 0) return existing;
+  const sep = existing && !existing.endsWith("\n") ? "\n" : "";
+  return existing + sep + "\n# ── dai ──\n" + toAdd.join("\n") + "\n";
+}
+
+// Inserta o actualiza un bloque delimitado (marcadores HTML) en una constitución,
+// sin pisar el resto del archivo. Idempotente: re-correr actualiza el bloque, no duplica.
+export function upsertBlock(existing, block, marker = "dai") {
+  const start = `<!-- ${marker}:start -->`, end = `<!-- ${marker}:end -->`;
+  const wrapped = `${start}\n${block.trim()}\n${end}`;
+  const i = existing.indexOf(start), j = existing.indexOf(end);
+  if (i !== -1 && j > i) {
+    return existing.slice(0, i) + wrapped + existing.slice(j + end.length);
+  }
+  const base = existing.trimEnd();
+  return base ? `${base}\n\n${wrapped}\n` : `${wrapped}\n`;
+}
+
+// Ajusta el texto de un .gitignore para que los artefactos de dai (según --for)
+// queden versionados, dejando fuera SOLO lo personal (settings.local.json). Quita
+// los ignores "broad" (.claude, CLAUDE.md, .cursor) que los esconderían. Aditivo e
+// idempotente. Devuelve { text, changed }.
+export function reconcileGitignore(text, want) {
+  const norm = (s) => { let t = s.trim(); while (t.startsWith("/")) { t = t.slice(1); } while (t.endsWith("/")) { t = t.slice(0, -1); } return t; };
+  const broad = new Set();
+  const ensure = [".env"];
+  if (want.claude) { broad.add("CLAUDE.md"); broad.add(".claude"); ensure.push(".claude/settings.local.json"); }
+  if (want.cursor) { broad.add(".cursor"); }
+  let changed = false;
+  let lines = text.split(/\r?\n/).filter((line) => {
+    if (line.trim().startsWith("#")) return true;
+    if (broad.has(norm(line))) { changed = true; return false; }
+    return true;
+  });
+  const have = new Set(lines.map((l) => l.trim()));
+  const add = ensure.filter((e) => !have.has(e));
+  if (add.length) {
+    changed = true;
+    if (lines.length && lines[lines.length - 1].trim() !== "") lines.push("");
+    lines.push("# dai — solo lo personal fuera del control de versiones", ...add);
+  }
+  return { text: lines.join("\n"), changed };
+}
+
 // La constitución del repo: se inyecta como CLAUDE.md (Claude) o
 // copilot-instructions.md (Copilot). Mismo núcleo, distinto encabezado.
 export function constitution(kind) {
   const head = kind === "copilot"
-    ? "# Instrucciones de Copilot para este repo\n\nEste repo sigue la metodología **dai**. Aplicá estas reglas en todo lo que generes.\n\n> **Superficie:** los prompts de dai (`.github/prompts/`) se invocan solo en VS Code /\n> JetBrains, o como custom agents en el Copilot CLI — no en la app standalone ni en\n> github.com. El CLI `dai` corre en cualquier terminal."
+    ? "# Instrucciones de Copilot para este repo\n\nEste repo sigue la metodología **dai**. Aplica estas reglas en todo lo que generes.\n\n> **Superficie:** los prompts de dai (`.github/prompts/`) se invocan solo en VS Code /\n> JetBrains, o como custom agents en el Copilot CLI — no en la app standalone ni en\n> github.com. El CLI `dai` corre en cualquier terminal."
     : kind === "cursor"
       ? "# Constitución del proyecto (dai)\n\nEste repo sigue la metodología **dai**. Estas reglas gobiernan todo el trabajo.\n\n> **Superficie:** las skills de dai (`.cursor/skills/`) se invocan con `/nombre-skill`\n> o cuando el agente las detecta por descripción. El CLI `dai` corre en cualquier terminal."
     : "# Constitución del proyecto (dai)\n\nEste repo sigue la metodología **dai**. Estas reglas gobiernan todo el trabajo.";
@@ -75,8 +130,19 @@ export function constitution(kind) {
 - **No vibe coding:** toda implementación arranca de una US con criterios testeables.
 - **TDD:** test primero, por la interfaz pública; sobrevive a un refactor.
 - **El link se autora una vez** (\`implements.yaml\`); la cobertura se **deriva** (nunca a mano).
+- **Verifica el comportamiento, no solo que compile:** que pase el chequeo estático o el build no prueba que funcione; ejercita el flujo real antes de darlo por hecho.
+- **La IA confirma antes de construir:** el asistente declara que entendió esta constitución y la va a obedecer antes de generar código.
 - **Secretos:** en \`.env\` (nunca commiteados). git por **SSH**, APIs por **token scopeado**.
-- Separá el QUÉ (funcional) del CÓMO (técnico); no mezcles.
+- **Docs vivas:** una constitución o arquitectura desactualizada es un defecto, no documentación.
+- Separa el QUÉ (funcional) del CÓMO (técnico); no mezcles.
+
+## Buenas prácticas (agnósticas)
+
+- **Confía en el borde, no en el input:** valida y autoriza en el límite de confianza; no aceptes identidad, permisos ni datos externos sin verificar.
+- **"No existe" > "no autorizado":** si un recurso no pertenece a quien pregunta, responde "no encontrado" en vez de revelar que existe.
+- **Aísla la E/S externa:** toda llamada a un servicio externo vive detrás de un borde dedicado; la capa de presentación no llama afuera directo.
+- **Estático en rojo = no está hecho:** los errores de tipos/lint son bloqueantes, no deuda diferible.
+- **Lo que cambia junto, vive junto:** coloca junto la lógica, la interfaz y los tests de una misma unidad.
 
 ## Herramientas
 

package/cli/lib/env.mjs

@@ -16,6 +16,12 @@ export function loadEnv(path = ".env", env = process.env) {
     val = val.trim();
     if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
       val = val.slice(1, -1);
+    } else {
+      // Valor sin comillas: recortar comentario inline (espacio + #). Evita que un
+      // `TOKEN=xxx  # nota` meta la nota — y caracteres no-ASCII como ← — en el valor,
+      // que después rompen headers HTTP (ByteString). Para conservar un # literal, usar comillas.
+      const c = val.search(/\s#/);
+      if (c !== -1) val = val.slice(0, c).trimEnd();
     }
     if (!(key in env)) env[key] = val;
   }

package/docs/adr/0010-versionado-y-upgrade.md

@@ -0,0 +1,122 @@
+# 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`.

package/docs/adr/README.md

@@ -15,6 +15,7 @@ decisión cambia, se escribe un ADR nuevo que supersede al viejo. Molde en
 | [0007](0007-modelo-de-autenticacion.md) | Modelo de auth: SSH para git, tokens scopeados para forge/tracker, sin contraseñas | aceptado |
 | [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 |
 
 > 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.2.0",
+  "version": "0.3.1",
   "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/",
@@ -30,7 +30,6 @@
     "templates",
     "governance",
     "skills",
-    "index.html",
     "manifest.yaml",
     "install.sh",
     ".env.example",

package/templates/formato-us.md

@@ -127,3 +127,44 @@ Lo que quedó sin resolver y necesita una decisión antes de pasar a implementac
   - spec_version (número legible) lo sube el PO/skill para comunicar; ac_hash lo
     calcula el CI para detectar. El número comunica, el hash detecta.
 -->
+
+---
+
+<!--
+  ══════════════════════════════════════════════════════════════════════════════
+  EJEMPLO LISTO PARA PROBAR — copiá desde el título de abajo hasta el final.
+  Es lo MÍNIMO que funciona (una US real necesita más secciones, ver arriba),
+  pero alcanza para ver el flujo:
+
+    • Sin tracker:  guardalo como .dai/us/EJ-1.md  y corré:
+        dai ac-hash .dai/us/EJ-1.md          # imprime el ac_hash
+        dai link-us EJ-1 --us .dai/us/EJ-1.md --dry-run   # muestra branch + implements.yaml
+    • Con tracker:  pegalo como una US nueva y corré  dai link-us <ID>.
+
+  La clave es la sección "Criterios de aceptación": es lo que se hashea. Sin ella,
+  dai no linkea (por diseño: no hay link sin criterios testeables).
+  ══════════════════════════════════════════════════════════════════════════════
+-->
+
+# Marcar una tarea como completada
+
+## Historia
+
+Como **usuario de la lista de tareas**
+quiero **marcar una tarea como completada**
+para **distinguir de un vistazo lo que ya hice de lo que me falta**.
+
+## Criterios de aceptación
+
+- [ ] **AC-1** —
+  - **Dado** una tarea pendiente en mi lista
+  - **Cuando** la marco como completada
+  - **Entonces** queda diferenciada como hecha y deja de contar en el total de pendientes.
+- [ ] **AC-2** —
+  - **Dado** una tarea ya completada
+  - **Cuando** la vuelvo a marcar
+  - **Entonces** vuelve al estado pendiente y se recuenta en el total.
+- [ ] **AC-3** —
+  - **Dado** que recargo la página
+  - **Cuando** vuelve a cargar mi lista
+  - **Entonces** cada tarea conserva el estado (completada o pendiente) que tenía.

package/index.html

@@ -1,481 +0,0 @@
-<!doctype html>
-<html lang="es">
-<head>
-<meta charset="utf-8" />
-<meta name="viewport" content="width=device-width, initial-scale=1" />
-<title>dai — Desarrollo Asistido por IA con trazabilidad</title>
-<meta name="description" content="Un método y un CLI para que la IA programe con trazabilidad y sin vibe coding. Separa el QUÉ del CÓMO, linkéalos una vez, y que la máquina avise sola cuando se desincronizan. Se adapta a cualquier tamaño de equipo." />
-<!-- Favicon SVG inline (sin CDN, nítido en cualquier resolución) -->
-<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Cdefs%3E%3ClinearGradient id='g' x1='0' y1='0' x2='1' y2='1'%3E%3Cstop offset='0' stop-color='%236366f1'/%3E%3Cstop offset='1' stop-color='%230ea5e9'/%3E%3C/linearGradient%3E%3C/defs%3E%3Crect width='64' height='64' rx='14' fill='url(%23g)'/%3E%3Ctext x='32' y='48' font-family='ui-sans-serif,system-ui,Arial' font-size='44' font-weight='800' fill='white' text-anchor='middle'%3Ed%3C/text%3E%3C/svg%3E" />
-<meta name="theme-color" content="#6366f1" />
-<style>
-  /* Autocontenido: fuentes del sistema + diagramas en CSS. Sin CDN → anda offline. */
-  :root{
-    --bg:#0b1120; --card:#131c2e; --ink:#eef2f8; --mut:#94a3b8; --line:#263247;
-    --brand:#6366f1; --brand-dark:#4f46e5;
-    --func:#f59e0b; --func-soft:#3a2f12; --func-ink:#fbbf24;   /* el QUÉ */
-    --tech:#0ea5e9; --tech-soft:#10273b; --tech-ink:#7dd3fc;   /* el CÓMO */
-    --ci:#10b981;   --ci-soft:#0f2c22;   --ci-ink:#6ee7b7;     /* la máquina */
-    --danger:#ef4444;
-    --mono:ui-monospace,"SF Mono",Menlo,Consolas,monospace;
-    --sans:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
-  }
-  :root[data-theme="light"]{
-    --bg:#f8fafc; --card:#ffffff; --ink:#0f172a; --mut:#475569; --line:#e2e8f0;
-    --func-soft:#fef3c7; --func-ink:#92400e; --tech-soft:#e0f2fe; --tech-ink:#075985;
-    --ci-soft:#d1fae5; --ci-ink:#065f46;
-  }
-  @media (prefers-color-scheme: light){
-    :root:not([data-theme="dark"]){
-      --bg:#f8fafc; --card:#ffffff; --ink:#0f172a; --mut:#475569; --line:#e2e8f0;
-      --func-soft:#fef3c7; --func-ink:#92400e; --tech-soft:#e0f2fe; --tech-ink:#075985;
-      --ci-soft:#d1fae5; --ci-ink:#065f46;
-    }
-  }
-  *{box-sizing:border-box}
-  html{scroll-behavior:smooth}
-  body{margin:0;background:var(--bg);color:var(--ink);font-family:var(--sans);
-    line-height:1.6;-webkit-font-smoothing:antialiased}
-  .wrap{max-width:960px;margin:0 auto;padding:0 20px}
-  a{color:var(--brand);text-decoration:none}
-  a:hover{text-decoration:underline}
-  code,kbd{font-family:var(--mono);font-size:.9em}
-  h1,h2,h3{line-height:1.2;letter-spacing:-.02em}
-  section{padding:64px 0;border-top:1px solid var(--line)}
-  .eyebrow{font-family:var(--mono);font-size:.8rem;letter-spacing:.08em;
-    text-transform:uppercase;color:var(--mut);margin:0 0 8px}
-  h2{font-size:clamp(1.5rem,4vw,2rem);margin:0 0 8px}
-  .lede{color:var(--mut);font-size:1.05rem;max-width:62ch;margin:0 0 28px}
-
-  /* ---------- nav ---------- */
-  nav{position:sticky;top:0;z-index:10;backdrop-filter:blur(10px);
-    background:color-mix(in srgb,var(--bg) 82%,transparent);border-bottom:1px solid var(--line)}
-  nav .wrap{display:flex;align-items:center;gap:16px;height:56px}
-  nav .logo{font-weight:800;letter-spacing:-.03em}
-  nav .logo b{color:var(--brand)}
-  nav .sp{flex:1}
-  nav a.nl{color:var(--mut);font-size:.9rem}
-  nav a.nl:hover{color:var(--ink);text-decoration:none}
-  .toggle{cursor:pointer;border:1px solid var(--line);background:var(--card);
-    color:var(--ink);border-radius:8px;padding:5px 9px;font-size:.85rem}
-  @media(max-width:640px){nav a.nl{display:none}}
-
-  /* ---------- hero ---------- */
-  .hero{padding:80px 0 64px;text-align:center}
-  .hero h1{font-size:clamp(2.2rem,7vw,3.6rem);margin:0 0 16px;font-weight:900}
-  .hero h1 .g{background:linear-gradient(120deg,var(--brand),var(--tech));
-    -webkit-background-clip:text;background-clip:text;color:transparent}
-  .hero p{color:var(--mut);font-size:1.2rem;max-width:60ch;margin:0 auto 28px}
-  .cta{display:flex;gap:12px;justify-content:center;flex-wrap:wrap}
-  .btn{display:inline-block;padding:11px 20px;border-radius:10px;font-weight:600;font-size:.95rem}
-  .btn.p{background:var(--brand);color:#fff}
-  .btn.p:hover{background:var(--brand-dark);text-decoration:none}
-  .btn.s{border:1px solid var(--line);color:var(--ink)}
-  .btn.s:hover{text-decoration:none;border-color:var(--brand)}
-  .install{margin:26px auto 0;max-width:520px;background:var(--card);border:1px solid var(--line);
-    border-radius:12px;padding:14px 16px;font-family:var(--mono);font-size:.9rem;text-align:left;
-    color:var(--ink);overflow-x:auto}
-  .install .c{color:var(--ci-ink)}
-  .install .m{color:var(--mut)}
-
-  /* ---------- pills / cards ---------- */
-  .grid{display:grid;gap:16px}
-  .g3{grid-template-columns:repeat(3,1fr)}
-  .g2{grid-template-columns:repeat(2,1fr)}
-  @media(max-width:720px){.g3,.g2{grid-template-columns:1fr}}
-  .card{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:20px;
-    transition:transform .25s ease,border-color .25s ease,box-shadow .25s ease}
-  .card:hover{transform:translateY(-4px);border-color:color-mix(in srgb,var(--brand) 55%,var(--line));
-    box-shadow:0 12px 30px -12px color-mix(in srgb,var(--brand) 45%,transparent)}
-  .card h3{margin:0 0 6px;font-size:1.05rem}
-  .card p{margin:0;color:var(--mut);font-size:.95rem}
-
-  /* ---------- animaciones (reveal al scroll + hover) ---------- */
-  .reveal{transition:opacity .7s ease,transform .7s cubic-bezier(.2,.7,.2,1)}
-  html.anim .reveal{opacity:0;transform:translateY(20px)}
-  html.anim .reveal.in{opacity:1;transform:none}
-  .lvl,.step .body,.side{transition:transform .25s ease}
-  .lvl:hover{transform:translateY(-4px)}
-  .install{transition:border-color .25s ease}
-  .install:hover{border-color:color-mix(in srgb,var(--ci) 50%,var(--line))}
-  @media (prefers-reduced-motion: reduce){
-    html.anim .reveal{opacity:1 !important;transform:none !important}
-    .card:hover,.lvl:hover{transform:none}
-  }
-  .ic{width:34px;height:34px;border-radius:9px;display:grid;place-items:center;
-    font-size:1.1rem;margin-bottom:12px}
-  .ic{transition:transform .25s ease}
-  .ic.d{background:linear-gradient(135deg,color-mix(in srgb,var(--brand) 28%,transparent),color-mix(in srgb,var(--tech) 28%,transparent));
-    box-shadow:inset 0 0 0 1px color-mix(in srgb,var(--brand) 24%,transparent)}
-  .ic.b{background:linear-gradient(135deg,color-mix(in srgb,var(--brand) 26%,transparent),color-mix(in srgb,var(--tech) 26%,transparent))}
-  .card:hover .ic{transform:scale(1.08) rotate(-3deg)}
-
-  .tag{display:inline-block;font-family:var(--mono);font-size:.72rem;font-weight:600;
-    padding:2px 8px;border-radius:999px;letter-spacing:.02em}
-  .tag.q{background:var(--func-soft);color:var(--func-ink)}
-  .tag.c{background:var(--tech-soft);color:var(--tech-ink)}
-  .tag.m{background:var(--ci-soft);color:var(--ci-ink)}
-
-  /* ---------- QUÉ vs CÓMO ---------- */
-  .split{display:grid;grid-template-columns:1fr auto 1fr;gap:0;align-items:stretch;
-    background:var(--card);border:1px solid var(--line);border-radius:16px;overflow:hidden}
-  @media(max-width:720px){.split{grid-template-columns:1fr}}
-  .side{padding:24px}
-  .side.q{border-right:1px solid var(--line)}
-  @media(max-width:720px){.side.q{border-right:0;border-bottom:1px solid var(--line)}}
-  .side h4{margin:0 0 4px;font-size:1.1rem}
-  .side .who{color:var(--mut);font-size:.85rem;margin:0 0 14px}
-  .side ul{margin:0;padding-left:18px;color:var(--mut);font-size:.92rem}
-  .link{display:grid;place-items:center;padding:0 8px;background:
-    color-mix(in srgb,var(--brand) 10%,transparent)}
-  .link .b{font-family:var(--mono);font-size:.72rem;color:var(--brand);
-    writing-mode:vertical-rl;transform:rotate(180deg);letter-spacing:.1em;font-weight:700}
-  @media(max-width:720px){.link{padding:10px}.link .b{writing-mode:horizontal-tb;transform:none}}
-
-  /* ---------- steps / journey ---------- */
-  .steps{position:relative;margin-top:8px}
-  .step{display:grid;grid-template-columns:44px 1fr;gap:18px;padding:14px 0;position:relative}
-  .step:not(:last-child)::before{content:"";position:absolute;left:21px;top:44px;bottom:-14px;
-    width:2px;background:var(--line)}
-  .num{width:44px;height:44px;border-radius:12px;display:grid;place-items:center;
-    font-weight:800;font-family:var(--mono);background:var(--card);border:1px solid var(--line);z-index:1}
-  .step.q .num{border-color:var(--func);color:var(--func-ink)}
-  .step.c .num{border-color:var(--tech);color:var(--tech-ink)}
-  .step.m .num{border-color:var(--ci);color:var(--ci-ink)}
-  .step .body h3{margin:0 0 3px;font-size:1.08rem}
-  .step .body p{margin:0 0 8px;color:var(--mut);font-size:.95rem}
-  .step .tool{font-family:var(--mono);font-size:.82rem;background:var(--bg);
-    border:1px solid var(--line);border-radius:8px;padding:3px 9px;display:inline-block;color:var(--ink)}
-
-  /* ---------- traceability demo ---------- */
-  .demo{background:var(--card);border:1px solid var(--line);border-radius:16px;padding:8px}
-  .term{font-family:var(--mono);font-size:.86rem;background:#0a0f1e;border-radius:12px;
-    padding:18px 18px;color:#cbd5e1;overflow-x:auto}
-  :root[data-theme="light"] .term{background:#0f172a;color:#e2e8f0}
-  @media(prefers-color-scheme:light){:root:not([data-theme="dark"]) .term{background:#0f172a;color:#e2e8f0}}
-  .term .p{color:#64748b}
-  .term .ok{color:#6ee7b7}
-  .term .warn{color:#fca5a5}
-  .term .cmd{color:#e2e8f0}
-  .term .dim{color:#64748b}
-  .term b{color:#fff;font-weight:600}
-
-  /* ---------- dial ---------- */
-  .dial{display:grid;grid-template-columns:repeat(3,1fr);gap:14px}
-  @media(max-width:720px){.dial{grid-template-columns:1fr}}
-  .lvl{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:18px}
-  .lvl .n{font-family:var(--mono);font-size:.78rem;color:var(--brand);font-weight:700}
-  .lvl h4{margin:6px 0 4px;font-size:1.05rem}
-  .lvl p{margin:0;color:var(--mut);font-size:.9rem}
-
-  /* ---------- start ---------- */
-  ol.start{counter-reset:s;list-style:none;padding:0;margin:0}
-  ol.start li{position:relative;padding:0 0 18px 40px}
-  ol.start li::before{counter-increment:s;content:counter(s);position:absolute;left:0;top:0;
-    width:26px;height:26px;border-radius:8px;background:var(--brand);color:#fff;
-    display:grid;place-items:center;font-weight:700;font-size:.85rem}
-  ol.start code{background:var(--card);border:1px solid var(--line);border-radius:7px;
-    padding:2px 7px;display:inline-block}
-  ol.start .d{color:var(--mut);font-size:.9rem}
-
-  footer{border-top:1px solid var(--line);padding:40px 0 60px;color:var(--mut);font-size:.9rem}
-  footer .wrap{display:flex;gap:20px;flex-wrap:wrap;align-items:center}
-  footer .sp{flex:1}
-</style>
-</head>
-<body>
-
-<nav>
-  <div class="wrap">
-    <span class="logo"><b>dai</b> · Desarrollo Asistido por IA</span>
-    <span class="sp"></span>
-    <a class="nl" href="#problema">Problema</a>
-    <a class="nl" href="#flujo">El flujo</a>
-    <a class="nl" href="#traza">Trazabilidad</a>
-    <a class="nl" href="#empezar">Empezar</a>
-    <button class="toggle" id="tg" aria-label="Cambiar tema">◐</button>
-  </div>
-</nav>
-
-<!-- ══════════ HERO ══════════ -->
-<header class="hero wrap">
-  <h1>La IA programa. <span class="g">@dai te da la trazabilidad.</span></h1>
-  <p>Un método —y un CLI— para desarrollo asistido por IA <b>sin vibe coding</b> y con
-     trazabilidad real: separa el <span class="tag q">QUÉ</span> del
-     <span class="tag c">CÓMO</span>, linkéalos una sola vez, y deja que la máquina
-     avise sola cuando se desincronizan. De un dev solo a una organización entera —
-     el mismo método.</p>
-  <div class="cta">
-    <a class="btn p" href="#empezar">Empezar ahora</a>
-    <a class="btn s" href="https://github.com/dforce2055/dai">Ver en GitHub</a>
-    <a class="btn s" href="https://www.npmjs.com/package/@dforce2055/dai">Ver en npm</a>
-  </div>
-  <div class="install">
-    <span class="m"># instala el CLI (Node ≥18, cero dependencias)</span><br>
-    <span class="c">npm i -g @dforce2055/dai</span><br>
-    <span class="c">dai init</span>  <span class="m"># configura tu repo: Claude/Copilot + OpenSpec + el link</span>
-  </div>
-</header>
-
-<!-- ══════════ PROBLEMA ══════════ -->
-<section id="problema">
-  <div class="wrap">
-    <p class="eyebrow">El problema</p>
-    <h2>La IA acelera el código. Y también acelera el caos.</h2>
-    <p class="lede">Tres dolores que la IA no resuelve sola — al contrario, los amplifica
-      si no hay método.</p>
-    <div class="grid g3">
-      <div class="card">
-        <div class="ic d">🔌</div>
-        <h3>Desincronización silenciosa</h3>
-        <p>El requerimiento cambia, el código sigue con la versión vieja, y se descubre
-           recién en la demo. Nadie se enteró a tiempo.</p>
-      </div>
-      <div class="card">
-        <div class="ic d">🎲</div>
-        <h3>Vibe coding</h3>
-        <p>La IA construye sobre una idea vaga y sale cualquier cosa. Rápido, sí — pero
-           sin garantía de que sea lo que se pedía.</p>
-      </div>
-      <div class="card">
-        <div class="ic d">🔀</div>
-        <h3>QUÉ y CÓMO mezclados</h3>
-        <p>El funcional se mete en la implementación; el dev redefine el negocio. Se pierde
-           quién es dueño de qué.</p>
-      </div>
-    </div>
-  </div>
-</section>
-
-<!-- ══════════ LA IDEA ══════════ -->
-<section id="idea">
-  <div class="wrap">
-    <p class="eyebrow">La idea</p>
-    <h2>Separa el QUÉ del CÓMO. Linkéalos una sola vez.</h2>
-    <p class="lede">El requerimiento (el QUÉ) y la implementación (el CÓMO) son cosas
-      distintas, con dueños distintos. dai las mantiene atadas — y la dirección inversa
-      se <b>deriva</b>, nunca se escribe a mano.</p>
-
-    <div class="split">
-      <div class="side q">
-        <span class="tag q">EL QUÉ · funcional</span>
-        <h4 style="margin-top:12px">La User Story</h4>
-        <p class="who">dueño: PO / analista · vive en Jira o ClickUp</p>
-        <ul>
-          <li>Criterios de aceptación testeables</li>
-          <li>Lo produce una skill de IA por interrogación</li>
-          <li>Identidad estable: el ticket del tracker</li>
-        </ul>
-      </div>
-      <div class="link"><span class="b">implements →</span></div>
-      <div class="side">
-        <span class="tag c">EL CÓMO · técnico</span>
-        <h4 style="margin-top:12px">El código + su spec</h4>
-        <p class="who">dueño: dev / ingeniero · vive en el repo</p>
-        <ul>
-          <li>Declara <code>implements: US@versión</code> — una vez</li>
-          <li>Diseño y tareas generados con OpenSpec</li>
-          <li>Se construye con tests primero (TDD)</li>
-        </ul>
-      </div>
-    </div>
-
-    <div class="grid g3" style="margin-top:16px">
-      <div class="card"><span class="tag q">1</span><h3 style="margin-top:10px">Identidad estable</h3>
-        <p>El QUÉ nace con un ID único (el ticket). Es lo único que lo hace linkeable.</p></div>
-      <div class="card"><span class="tag c">2</span><h3 style="margin-top:10px">Un solo link, a mano</h3>
-        <p>El código apunta al QUÉ. La cobertura inversa (quién implementó qué) la genera la máquina.</p></div>
-      <div class="card"><span class="tag m">3</span><h3 style="margin-top:10px">@version que grita</h3>
-        <p>Número legible + hash de criterios. Si el QUÉ cambia, los CÓMO atrasados se marcan solos.</p></div>
-    </div>
-  </div>
-</section>
-
-<!-- ══════════ EL FLUJO GUIADO ══════════ -->
-<section id="flujo">
-  <div class="wrap">
-    <p class="eyebrow">El flujo</p>
-    <h2>Tu Scrum de siempre — con IA en cada paso</h2>
-    <p class="lede">dai no reemplaza tu proceso: lo potencia. En cada etapa hay una skill
-      de IA o un comando que hace el trabajo pesado. <span class="tag q">QUÉ</span>
-      <span class="tag c">CÓMO</span> <span class="tag m">máquina</span></p>
-
-    <div class="steps">
-      <div class="step q"><div class="num">1</div><div class="body">
-        <h3>Define el QUÉ</h3>
-        <p>El analista describe la idea. Una skill de IA lo <b>interroga</b> hasta que la
-           User Story es testeable, y la publica en el tracker. La IA no inventa: pregunta.</p>
-        <span class="tool">/grill-intent → /grill-user-story → ClickUp / Jira</span>
-      </div></div>
-
-      <div class="step c"><div class="num">2</div><div class="body">
-        <h3>Abre el CÓMO, atado al QUÉ</h3>
-        <p>El dev arranca la implementación. dai trae la US del tracker, crea la branch y
-           siembra el link — <b>correcto por construcción</b>, sin tipear el ID a mano.</p>
-        <span class="tool">dai link-us &lt;ID&gt;  →  branch + implements.yaml</span>
-      </div></div>
-
-      <div class="step c"><div class="num">3</div><div class="body">
-        <h3>Diseña con OpenSpec</h3>
-        <p>OpenSpec toma la US y genera la propuesta, el diseño y las tareas — co-localizados
-           con el link, en la misma branch. El QUÉ se convierte en un plan técnico.</p>
-        <span class="tool">/opsx:propose  →  proposal · design · tasks</span>
-      </div></div>
-
-      <div class="step c"><div class="num">4</div><div class="body">
-        <h3>Implementa con tests primero</h3>
-        <p>TDD en rebanadas verticales: un test, el código mínimo, repetir. La IA escribe el
-           test como spec ejecutable. Anti vibe-coding de verdad.</p>
-        <span class="tool">/tdd  ·  red → green → refactor</span>
-      </div></div>
-
-      <div class="step m"><div class="num">5</div><div class="body">
-        <h3>Verifica la trazabilidad</h3>
-        <p>¿Tu código sigue al día con la US? dai re-deriva el hash de la US viva y compara.
-           Si el QUÉ cambió, te avisa <b>y te dice cómo resincronizar</b>.</p>
-        <span class="tool">dai check  →  ✅ al día  /  ⚠️ atrasado</span>
-      </div></div>
-
-      <div class="step c"><div class="num">6</div><div class="body">
-        <h3>Crea y revisa la PR</h3>
-        <p>dai arma el texto de la PR desde el template, precargado con la US, el estado del
-           check y los enlaces. Tu PR la revisas tú; la de un compañero, con la skill de review.</p>
-        <span class="tool">dai pr  ·  /dai-review (la PR de otro)</span>
-      </div></div>
-
-      <div class="step m"><div class="num">7</div><div class="body">
-        <h3>Mergea y estampa la cobertura</h3>
-        <p>Al mergear, dai escribe en el tracker <b>quién implementó qué</b>, contra qué
-           versión, con branch y commit. La trazabilidad inversa — nadie la mantiene a mano.</p>
-        <span class="tool">dai stamp  →  cobertura en el tracker</span>
-      </div></div>
-    </div>
-  </div>
-</section>
-
-<!-- ══════════ TRAZABILIDAD (demo) ══════════ -->
-<section id="traza">
-  <div class="wrap">
-    <p class="eyebrow">La pieza que lo cambia todo</p>
-    <h2>Cuando el QUÉ cambia, el desajuste se hace visible solo</h2>
-    <p class="lede">El PO edita un criterio en el tracker. Tú no tocaste una línea de código.
-      Y aun así, dai lo detecta — porque compara el hash de la US viva contra el que dejaste
-      estampado.</p>
-
-    <div class="demo">
-      <div class="term">
-<span class="p">$</span> <span class="cmd">dai check</span>
-<span class="ok">✅ 86ajcjwzk al día (v1)</span>
-
-<span class="dim"># … el PO agrega un criterio de aceptación en el tracker …</span>
-
-<span class="p">$</span> <span class="cmd">dai check</span>
-<span class="warn">⚠️  86ajcjwzk ATRASADO: implementaste 2124e94f, la US viva es 51abbfa0</span>
-
-  <span class="dim">El QUÉ cambió desde que lo implementaste. Para resincronizar:</span>
-    <b>dai link-us 86ajcjwzk --resync</b>  <span class="dim"># re-estampa contra la US viva</span>
-      </div>
-    </div>
-    <p class="lede" style="margin-top:22px">Nadie le avisó al dev. El link versionado lo
-      avisó solo. Esa es la diferencia entre <i>esperar que alguien se dé cuenta</i> y
-      <i>que el sistema te lo diga</i>.</p>
-  </div>
-</section>
-
-<!-- ══════════ SE ADAPTA ══════════ -->
-<section id="escala">
-  <div class="wrap">
-    <p class="eyebrow">Un solo método</p>
-    <h2>Se adapta a cualquier tamaño de equipo</h2>
-    <p class="lede">No hay una versión para equipos chicos y otra para grandes. Hay
-      <b>un protocolo invariante</b> y un dial de ceremonia que sube o baja según la escala.
-      Cada capa se agrega cuando duele, no antes.</p>
-    <div class="dial">
-      <div class="lvl"><span class="n">NIVEL 1</span><h4>Un dev solo</h4>
-        <p>OpenSpec y el CLI, todo local. La US puede vivir como un <code>.md</code>. Cero
-           infraestructura. El link y el check funcionan igual.</p></div>
-      <div class="lvl"><span class="n">NIVEL 2</span><h4>Equipo compacto</h4>
-        <p>Aparece el tracker (ClickUp/Jira) para coordinar. El link referencia la US; el
-           check y el stamp corren a mano o en un hook.</p></div>
-      <div class="lvl"><span class="n">NIVEL 3</span><h4>Organización grande</h4>
-        <p>Muchos repos, equipos separados, CI que estampa cobertura y matriz de ambientes.
-           El mismo protocolo, con más plomería.</p></div>
-    </div>
-    <p class="lede" style="margin-top:20px">El dev que aprende el nivel chico ya sabe el
-      grande. Nadie mantiene dos metodologías.</p>
-  </div>
-</section>
-
-<!-- ══════════ EMPEZAR ══════════ -->
-<section id="empezar">
-  <div class="wrap">
-    <p class="eyebrow">Empezar</p>
-    <h2>De cero a tu primera US trazada</h2>
-    <p class="lede">Requiere Node ≥ 18. El CLI no tiene dependencias — anda incluso en redes
-      corporativas cerradas.</p>
-    <ol class="start">
-      <li><code>npm i -g @dforce2055/dai</code>
-        <div class="d">Instala el CLI. El comando queda <code>dai</code>.</div></li>
-      <li><code>dai init</code>
-        <div class="d">Scaffolder interactivo: eliges asistente (Claude/Copilot), tracker
-          (md/ClickUp/Jira) y si sumas OpenSpec. Deja el repo listo.</div></li>
-      <li><code>dai link-us &lt;ID&gt;</code>
-        <div class="d">Trae la US del tracker, crea la branch y el link. Implementas con TDD.</div></li>
-      <li><code>dai check</code>  →  <code>dai pr</code>  →  <code>dai stamp</code>
-        <div class="d">Verificas que sigues al día, creas la PR precargada, y al mergear
-          estampas la cobertura. El círculo cerrado.</div></li>
-    </ol>
-    <div class="cta" style="justify-content:flex-start;margin-top:8px">
-      <a class="btn p" href="https://github.com/dforce2055/dai">Documentación completa</a>
-      <a class="btn s" href="https://github.com/dforce2055/dai/blob/main/docs/EJEMPLO-END-TO-END.md">Ver un ejemplo real</a>
-    </div>
-  </div>
-</section>
-
-<footer>
-  <div class="wrap">
-    <span><b style="color:var(--brand)">dai</b> — Desarrollo Asistido por IA</span>
-    <span class="sp"></span>
-    <a href="https://github.com/dforce2055/dai">GitHub</a>
-    <a href="https://www.npmjs.com/package/@dforce2055/dai">npm</a>
-    <a href="https://github.com/dforce2055/dai/blob/main/docs/MANIFIESTO.md">Manifiesto</a>
-    <a href="https://github.com/dforce2055/dai/blob/main/LICENSE">GPLv3</a>
-  </div>
-</footer>
-
-<script>
-  // JS mínimo: toggle de tema + animaciones de reveal. Nada externo.
-  (function(){
-    var r=document.documentElement, t=document.getElementById('tg');
-    try{var s=localStorage.getItem('dai-theme'); if(s) r.setAttribute('data-theme',s);}catch(e){}
-    t.addEventListener('click',function(){
-      var cur=r.getAttribute('data-theme');
-      var m=window.matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light';
-      var next=(cur||m)==='dark'?'light':'dark';
-      r.setAttribute('data-theme',next);
-      try{localStorage.setItem('dai-theme',next);}catch(e){}
-    });
-
-    // Reveal al hacer scroll (fade + slide up), con stagger por grupo.
-    var reduce=window.matchMedia('(prefers-reduced-motion: reduce)').matches;
-    var els=document.querySelectorAll(
-      'section h2, section .lede, .card, .step, .lvl, .split, .demo, .install, ol.start li, .cta');
-    if(reduce || !('IntersectionObserver' in window)){ return; } // sin animar: todo visible
-    r.classList.add('anim');                                     // recién acá ocultamos (fallback sin JS = visible)
-    els.forEach(function(el){
-      el.classList.add('reveal');
-      // stagger: retraso según la posición del elemento entre sus hermanos
-      var i=0,p=el.previousElementSibling;
-      while(p){ i++; p=p.previousElementSibling; }
-      el.style.transitionDelay=Math.min(i,6)*70+'ms';
-    });
-    var io=new IntersectionObserver(function(entries){
-      entries.forEach(function(e){
-        if(e.isIntersecting){ e.target.classList.add('in'); io.unobserve(e.target); }
-      });
-    },{threshold:.12, rootMargin:'0px 0px -8% 0px'});
-    els.forEach(function(el){ io.observe(el); });
-  })();
-</script>
-</body>
-</html>