@dforce2055/dai 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 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
@@ -102,6 +122,7 @@ 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

package/VERSION

@@ -1 +1 @@
-0.3.0
+0.3.1

package/cli/dai.mjs

@@ -27,7 +27,7 @@ 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 { 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";
   }
@@ -503,7 +503,13 @@ async function askYesNo(rl, q, def = false) {
 // ── 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");
@@ -557,8 +563,9 @@ async function cmdInit(repo, opts) {
   writeFileSync(join(dai, "VERSION"), readFileSync(join(ROOT, "VERSION"), "utf8"));
   ok(".dai/         moldes (templates) + reglas (governance) del método");
 
-  // .env.example — aditivo: agrega las claves de dai que falten (no pisa el del proyecto).
-  const exSrc = readFileSync(join(ROOT, ".env.example"), "utf8");
+  // .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);

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/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.3.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/",

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.