@dforce2055/dai 0.10.0 → 0.11.0

package/cli/lib/branch-scope.mjs

@@ -0,0 +1,144 @@
+// dai · qué US toca esta branch (governance/branch-naming.md, ADR-0004).
+//
+// Dos preguntas que el CLI se hacía a ojo y respondía mal:
+//   1. `dai stamp` — ¿cuál de las US del repo estoy cerrando? (issue #22: estampaba TODAS,
+//      archivadas incluidas, así que un sprint entero recibía un comentario por PR).
+//   2. `dai check --ci` — ¿esta branch está OBLIGADA a tener implements.yaml? Una `chore/`
+//      o una `fix/` sin US no lo está, y bloquearla sería mentirle al equipo.
+//
+// Todo acá es puro: entra el nombre de la branch y la lista de implements, sale la
+// decisión. La red, git y los prompts viven en dai.mjs.
+
+import { isPlaceholderId } from "./implements.mjs";
+
+// Prefijos que NO son trabajo de producto: no exigen link (branch-naming.md).
+// `fix/` es "corrección sobre una US ya implementada": puede llevar ID o no, y muchas
+// veces es un hotfix sin ticket. Se exige link solo si el nombre trae el ID.
+const EXEMPT = new Set(["chore", "docs", "ci", "build", "test", "refactor", "style", "release", "hotfix", "revert"]);
+const ALWAYS = new Set(["feature", "feat"]);
+
+// El tipo de branch = lo que hay antes de la primera `/`. Sin `/` → "" (main, develop…).
+export function branchType(branch) {
+  const s = String(branch ?? "").trim();
+  const i = s.indexOf("/");
+  return i === -1 ? "" : s.slice(0, i).toLowerCase();
+}
+
+// Los ids candidatos que aparecen en el nombre de la branch, en orden de aparición.
+// Cubre las dos formas que emite `link-us` (ver slugify/branchName en link-us.mjs):
+//   feature/ABC-482-titulo   → Jira-like (LETRAS-números)
+//   feature/86acme482-titulo → ClickUp-like (alfanumérico, sin guion)
+// Devuelve TODOS los candidatos porque el segmento alfanumérico es ambiguo: `historia`
+// también matchea. Quién decide es matchBranchToImplements, comparando contra las US reales.
+export function branchIdCandidates(branch) {
+  const s = String(branch ?? "").trim();
+  const tail = s.includes("/") ? s.slice(s.indexOf("/") + 1) : s;
+  const out = [];
+  for (const m of tail.matchAll(/[A-Za-z][A-Za-z0-9_]*-\d+|[A-Za-z0-9]+/g)) out.push(m[0]);
+  return out;
+}
+
+// Un key de tracker con pinta de tal: MAYÚSCULAS + guion + números (ABC-482). El case
+// importa — es lo único que separa un key real de una palabra del slug con un número
+// pegado: `feat/issues-22-26` no implementa la US "issues-22", y sugerírsela al dev es
+// mandarlo a crear un link inventado. Los ids de ClickUp (`86acme482`) no matchean acá:
+// no llevan guion, y para esos el nombre de la branch no alcanza — se resuelve comparando
+// contra las US que el repo declara (matchBranchToImplements).
+const KEYISH = /^[A-Z][A-Z0-9_]*-\d+$/;
+
+// Los keys de tracker que nombra la branch (0, 1 o varios).
+export function trackerKeysIn(branch) {
+  return branchIdCandidates(branch).filter((c) => KEYISH.test(c));
+}
+
+// ¿Esta branch tiene que declarar una US? (gate de CI, issue #26)
+//   feature/ → siempre sí
+//   chore/, docs/, ci/…  → nunca
+//   fix/ y el resto → solo si el nombre trae un ID con pinta de key de tracker
+// `main`/`develop`/sin branch → no (no es una branch de trabajo).
+export function requiresLink(branch) {
+  const t = branchType(branch);
+  if (ALWAYS.has(t)) return { required: true, reason: `'${t}/' es trabajo de producto: requiere US` };
+  if (EXEMPT.has(t)) return { required: false, reason: `'${t}/' está exenta de US (governance/branch-naming.md)` };
+  if (t === "") return { required: false, reason: "sin prefijo tipo/, no es una branch de trabajo: sin gate de link" };
+  // Tipo desconocido (fix/, spike/, lo que el repo use): si nombró un ID, lo tomamos
+  // como intención de implementar una US y se lo exigimos. Si no, no inventamos.
+  const keyish = trackerKeysIn(branch).length > 0;
+  return keyish
+    ? { required: true, reason: `'${t}/' con un ID en el nombre: se toma como trabajo de producto` }
+    : { required: false, reason: `'${t}/' sin ID en el nombre: no exige US (governance/branch-naming.md)` };
+}
+
+// Aplana los implements descubiertos a filas { path, change, repo, id, version, ac_hash },
+// salteando los placeholders de plantilla (ABC-###).
+export function flattenImplements(found) {
+  const rows = [];
+  for (const f of found || []) {
+    for (const im of f.implements || []) {
+      if (isPlaceholderId(im.id)) continue;
+      rows.push({ path: f.path, change: f.change, repo: f.repo, id: im.id, version: im.version, ac_hash: im.ac_hash });
+    }
+  }
+  return rows;
+}
+
+// ¿Cuál de estas US es la de la branch? Compara sin distinguir mayúsculas, porque el
+// slug de la branch va en minúsculas y el key de Jira en mayúsculas (ABC-482 → abc-482).
+export function matchBranchToImplements(branch, rows) {
+  const cands = branchIdCandidates(branch).map((c) => c.toLowerCase());
+  if (cands.length === 0) return [];
+  const seen = new Set();
+  const hit = [];
+  for (const c of cands) {
+    for (const r of rows) {
+      if (String(r.id).toLowerCase() === c && !seen.has(r.path + " " + r.id)) {
+        seen.add(r.path + " " + r.id);
+        hit.push(r);
+      }
+    }
+  }
+  return hit;
+}
+
+// La decisión completa de `dai stamp`: qué estampar y por qué.
+//
+//   { mode, targets, candidates, reason }
+//
+//   mode "explicit" → los ids que pidió el usuario (dai stamp ABC-482)
+//   mode "all"      → --all: todo, archivadas incluidas (el comportamiento viejo)
+//   mode "branch"   → la branch nombra una US del repo: esa
+//   mode "only"     → hay una sola US viva: esa
+//   mode "ambiguous"→ varias y ninguna pista: NO estampa, pide confirmación
+//   mode "none"     → no hay nada que estampar
+//
+// `rows` viene de flattenImplements sobre el discover SIN archivados; `allRows` incluye
+// los archivados y solo se usa para --all y para resolver un id explícito de un change
+// ya archivado (estampar después del merge es exactamente ese caso).
+export function stampScope({ branch, rows, allRows = rows, ids = [], all = false }) {
+  if (all) {
+    return { mode: "all", targets: allRows, candidates: allRows, reason: "--all: todas las US del repo (archivadas incluidas)" };
+  }
+  if (ids.length) {
+    const want = ids.map((i) => String(i).toLowerCase());
+    const targets = allRows.filter((r) => want.includes(String(r.id).toLowerCase()));
+    // `missing` conserva la grafía que tipeó el usuario: si le devolvemos su ABC-404 en
+    // minúsculas, lo primero que hace es dudar de si el problema era el case.
+    const missing = ids.filter((i) => !allRows.some((r) => String(r.id).toLowerCase() === String(i).toLowerCase()));
+    return { mode: "explicit", targets, candidates: allRows, missing, reason: `ids pedidos: ${ids.join(", ")}` };
+  }
+  if (rows.length === 0) return { mode: "none", targets: [], candidates: [], reason: "no hay implements.yaml vivos para estampar" };
+
+  const hit = matchBranchToImplements(branch, rows);
+  if (hit.length === 1) {
+    return { mode: "branch", targets: hit, candidates: rows, reason: `la branch '${branch}' nombra ${hit[0].id}` };
+  }
+  if (rows.length === 1) {
+    return { mode: "only", targets: rows, candidates: rows, reason: "es la única US viva del repo" };
+  }
+  return {
+    mode: "ambiguous",
+    targets: [],
+    candidates: hit.length > 1 ? hit : rows,
+    reason: `hay ${hit.length > 1 ? hit.length : rows.length} US vivas y la branch '${branch}' no dice cuál`,
+  };
+}

package/cli/lib/forge-api.mjs

@@ -72,6 +72,10 @@ export function inlinePosition(ref, c, { diffRefs } = {}) {
   return { body: c.body, position };
 }
 
+// La variable de entorno que autentica contra este forge, y su valor.
+export function tokenVar(ref) { return ref.forge === "gitlab" ? "GITLAB_TOKEN" : "GITHUB_TOKEN"; }
+export function tokenFor(ref, env = process.env) { return String(env[tokenVar(ref)] || "").trim(); }
+
 export function authHeaders(ref, env = process.env) {
   if (ref.forge === "github") {
     return { Authorization: `Bearer ${env.GITHUB_TOKEN || ""}`, Accept: "application/vnd.github+json", "User-Agent": "dai" };
@@ -79,6 +83,59 @@ export function authHeaders(ref, env = process.env) {
   return { "PRIVATE-TOKEN": env.GITLAB_TOKEN || "" };
 }
 
+// Traduce el fallo del forge a algo accionable (issue #24).
+//
+// El mensaje viejo era `¿token? ¿ref correcta?` para TODO: sin token, token vencido,
+// token sin scope, PR inexistente y repo privado caían en la misma frase. Costó una
+// sesión de diagnóstico equivocado. Cada causa tiene una acción distinta, así que se
+// nombran por separado — y "no hay token" se detecta ANTES de salir a la red.
+//
+// Ojo con el 404 de GitHub: en un repo privado, un token sin permiso devuelve 404 (no
+// 403) para no filtrar la existencia del repo. Por eso el 404 nombra las dos causas.
+export function describeForgeError(ref, { status = null, body = "", env = process.env, cause = null } = {}) {
+  const v = tokenVar(ref);
+  const has = tokenFor(ref, env) !== "";
+  const where = `${ref.projectPath}#${ref.number} (${ref.host})`;
+  const setIt = `  Configuralo en tu .env.dai (o exportalo en la shell):  ${v}=<token>`;
+
+  if (!has) {
+    return `no hay ${v} configurado, así que la llamada al forge salió sin credencial.\n` +
+      `${setIt}\n` +
+      (ref.forge === "github"
+        ? "  Token: https://github.com/settings/tokens  ·  scope 'repo' (o fine-grained con Pull requests: read+write)."
+        : "  Token: <tu-gitlab>/-/user_settings/personal_access_tokens  ·  scope 'api'.");
+  }
+  if (status === 401) {
+    return `el forge rechazó tu ${v} (401): el token existe pero NO es válido — vencido, revocado, o mal copiado.\n` +
+      `  Probalo:  ${ref.forge === "github"
+        ? "curl -sI -H \"Authorization: Bearer $GITHUB_TOKEN\" https://api.github.com/user"
+        : `curl -sI -H "PRIVATE-TOKEN: $GITLAB_TOKEN" https://${ref.host}/api/v4/user`}\n` +
+      `  Si da 200, el token sirve y el problema es otro. Si da 401, generá uno nuevo.\n${setIt}`;
+  }
+  if (status === 403) {
+    const rate = /rate limit|api rate/i.test(String(body));
+    return rate
+      ? `el forge te frenó por rate limit (403). Esperá unos minutos, o usá un ${v} con más cuota.`
+      : `tu ${v} es válido pero NO tiene permiso sobre ${where} (403).\n` +
+        `  Le falta scope (github: 'repo' / fine-grained con Pull requests read+write · gitlab: 'api'),\n` +
+        "  o tu usuario no tiene acceso a ese repo.";
+  }
+  if (status === 404) {
+    return `el forge no encontró ${where} (404). Dos causas posibles, y no se distinguen desde afuera:\n` +
+      "    1. La PR/MR no existe con ese número en ese repo (revisá la ref).\n" +
+      `    2. El repo es privado y tu ${v} no tiene permiso — GitHub devuelve 404, no 403, para no filtrar que existe.`;
+  }
+  if (status != null) return `el forge respondió ${status} sobre ${where}.${body ? `\n  ${String(body).slice(0, 400)}` : ""}`;
+  return `no pude hablar con ${ref.host}${cause ? `: ${cause}` : ""}. ¿Hay red / proxy / VPN de por medio?`;
+}
+
+// El error que tiran getPR/postComment/postReview lleva el status pegado al mensaje
+// (`forge 401: {...}`). Esto lo vuelve a separar para poder explicarlo.
+export function parseForgeError(e) {
+  const m = String(e?.message || e || "").match(/^forge (\d{3}): ([\s\S]*)$/);
+  return m ? { status: Number(m[1]), body: m[2] } : { status: null, body: "", cause: String(e?.message || e || "") };
+}
+
 // Comentario estándar de dai-review (mismo formato lo emita el CLI o la skill).
 export function renderReviewComment(r) {
   const { us, version, checkStatus, dod, errors = [], improvements = [], good = [] } = r;

package/cli/lib/pm-adapter.mjs

@@ -7,12 +7,17 @@
 //   clickup — REST v2 (pm-clickup.mjs)
 //
 // Interfaz (fetchUS/stamp pueden ser sync o async — el CLI siempre await-ea):
-//   fetchUS(id)          → { id, title, spec_version, ac_hash, url } | null
+//   fetchUS(id)          → { id, title, spec_version, ac_hash, url, raw } | null
 //   stamp(id, record)    → destino donde quedó la cobertura
+//   createUS({...})      → { id, url }            (opcional: `dai publish`)
+//   updateUS(id, {...})  → { id, url }            (opcional: `dai update-us`)
 //   kind                 → nombre del backend
 //
 // `url` es la URL web canónica de la US según el tracker (opcional: null si el backend
 // no la sabe, como md). El CLI la prefiere sobre la derivada — ver tracker-url.mjs.
+// `raw` es el markdown COMPLETO de la US tal como vive en el backend: es lo que
+// `dai edit-us` baja y te abre. Sin esto solo teníamos el parseo (título + hash), que
+// alcanza para detectar drift pero no para editar.
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
@@ -32,7 +37,8 @@ function mdAdapter(env) {
     fetchUS(id) {
       const p = join(dir, `${id}.md`);
       if (!existsSync(p)) return null;
-      return { id, ...parseUS(readFileSync(p, "utf8")) };
+      const raw = readFileSync(p, "utf8");
+      return { id, ...parseUS(raw), raw };
     },
     stamp(id, record) {
       const p = join(dir, `${id}.coverage.md`);
@@ -47,6 +53,14 @@ function mdAdapter(env) {
       writeFileSync(p, descriptionMarkdown.startsWith("# ") ? descriptionMarkdown : `# ${title}\n\n${descriptionMarkdown}`);
       return { id, url: p };
     },
+    // Sin tracker, "actualizar la US" es pisar el .md canónico. Se exige que exista:
+    // si no, `dai update-us` estaría creando una US con el id equivocado en silencio.
+    updateUS(id, { title, descriptionMarkdown }) {
+      const p = join(dir, `${id}.md`);
+      if (!existsSync(p)) throw new Error(`no existe ${p} — con DAI_PM=md, update-us actualiza el .md canónico. Creá la US primero (dai publish).`);
+      writeFileSync(p, descriptionMarkdown.startsWith("# ") ? descriptionMarkdown : `# ${title}\n\n${descriptionMarkdown}`);
+      return { id, url: p };
+    },
   };
 }
 

package/cli/lib/pm-clickup.mjs

@@ -30,8 +30,9 @@ export function clickupAdapter(env) {
       if (res.status === 404) return null;
       if (!res.ok) throw new Error(`clickup ${res.status}: ${await res.text()}`);
       const j = await res.json();
+      const raw = clickupTaskToText(j);
       // `url` es la canónica (/t/<team_id>/<id>): la sabe ClickUp, no la deducimos.
-      return { id, ...parseUS(clickupTaskToText(j)), url: j.url || null };
+      return { id, ...parseUS(raw), url: j.url || null, raw };
     },
     async stamp(id, record) {
       const res = await fetch(clickupCommentUrl(id), {
@@ -41,6 +42,20 @@ export function clickupAdapter(env) {
       if (!res.ok) throw new Error(`clickup ${res.status}: ${await res.text()}`);
       return `task ${id} (comentario)`;
     },
+    // PUT /task/<id>: ClickUp acepta `markdown_content` para pisar la descripción.
+    // Solo mandamos lo que cambió — un PUT con `name` vacío renombraría la tarea.
+    async updateUS(id, { title, descriptionMarkdown }) {
+      const payload = {};
+      if (title) payload.name = title;
+      if (descriptionMarkdown != null) payload.markdown_content = descriptionMarkdown;
+      const res = await fetch(`${API}/task/${encodeURIComponent(id)}`, {
+        method: "PUT", headers: clickupAuthHeaders(env), body: JSON.stringify(payload),
+      });
+      if (res.status === 404) throw new Error(`clickup: no existe la tarea '${id}' (404). Revisá el id.`);
+      if (!res.ok) throw new Error(`clickup ${res.status}: ${await res.text()}`);
+      const j = await res.json().catch(() => ({}));
+      return { id, url: j.url || null };
+    },
     async createUS({ title, descriptionMarkdown }) {
       const list = env.DAI_CLICKUP_LIST_ID;
       if (!list) throw new Error("falta DAI_CLICKUP_LIST_ID en el .env.dai (la lista donde crear la tarea).");

package/cli/lib/pm-jira.mjs

@@ -143,7 +143,8 @@ export function jiraAdapter(env) {
       const res = await daiFetch(jiraIssueUrl(base, id), { headers: jiraAuthHeaders(env) });
       if (res.status === 404) return null;
       if (!res.ok) throw new Error(`jira ${res.status}: ${await res.text()}`);
-      return { id, ...parseUS(jiraIssueToText(await res.json())), url: `${trim(base)}/browse/${id}` };
+      const raw = jiraIssueToText(await res.json());
+      return { id, ...parseUS(raw), url: `${trim(base)}/browse/${id}`, raw };
     },
     async stamp(id, record) {
       const res = await daiFetch(jiraCommentUrl(base, id), {
@@ -153,6 +154,25 @@ export function jiraAdapter(env) {
       if (!res.ok) throw new Error(`jira ${res.status}: ${await res.text()}`);
       return `${trim(base)}/browse/${id}`;
     },
+    // PUT /issue/<id>: Jira responde 204 SIN cuerpo, así que la URL la componemos
+    // nosotros. Solo se mandan los campos que cambian — un PUT con summary vacío
+    // borraría el título de la US.
+    async updateUS(id, { title, descriptionMarkdown, fields }) {
+      const payload = { ...(fields || {}) };
+      if (title) payload.summary = title;
+      if (descriptionMarkdown != null) payload.description = markdownToAdf(descriptionMarkdown);
+      if (Object.keys(payload).length === 0) throw new Error("nada que actualizar (ni título, ni descripción, ni campos).");
+      const res = await daiFetch(`${trim(base)}/rest/api/3/issue/${encodeURIComponent(id)}`, {
+        method: "PUT", headers: jiraAuthHeaders(env), body: JSON.stringify({ fields: payload }),
+      });
+      if (res.status === 404) throw new Error(`jira: no existe el issue '${id}' (404), o tu usuario no lo ve.`);
+      if (res.status === 403) throw new Error(`jira: sin permiso para editar '${id}' (403). ¿Tu usuario puede editar issues en ese proyecto?`);
+      if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`jira ${res.status}: ${body}${createHint(res.status, body)}`);
+      }
+      return { id, url: `${trim(base)}/browse/${id}` };
+    },
     // `fields` son los campos propios del proyecto ya resueltos (ver jira-fields.mjs);
     // `parent` cuelga la US de su épica. Ambos son opcionales: un Jira sin campos
     // obligatorios sigue publicando igual que antes.

package/cli/lib/us-format.mjs

@@ -0,0 +1,147 @@
+// dai · validación del formato de una US y manejo de `spec_version`.
+//
+// El molde canónico vive en templates/formato-us.md. Acá está la parte MECÁNICA de ese
+// molde: ¿tiene título? ¿tiene criterios? ¿los criterios son Gherkin completo?
+//
+// Lo que NO hace: juzgar si un criterio es *bueno*. Eso es criterio (ADR-0002) y vive en
+// la skill /grill-user-story, que te interroga. Acá solo se verifica lo que una máquina
+// puede verificar sin opinar — y por eso casi todo es WARNING, no error: dai es una
+// herramienta, no un mandato. Bloquean únicamente las tres cosas sin las cuales el link
+// QUÉ↔CÓMO no existe: título, sección de criterios, y al menos un criterio.
+
+import { extractAcBlock } from "./ac-hash.mjs";
+import { extractTitle } from "./link-us.mjs";
+
+// Limpia el marcado editorial de una línea para poder mirarla (mismo espíritu que
+// normalizeAcBlock, pero conservando las líneas: acá importa la ESTRUCTURA).
+const strip = (line) => line
+  .replace(/^\s*>\s?/, "")
+  .replace(/^\s*[-*+]\s+\[[ xX]\]\s*/, "")
+  .replace(/^\s*[-*+]\s+/, "")
+  .replace(/^\s*\d+[.)]\s+/, "")
+  .replace(/[*_`]+/g, "")
+  .trim();
+
+const GHERKIN = { dado: /^dado\b/i, cuando: /^cuando\b/i, entonces: /^entonces\b/i };
+
+// Parte el bloque de criterios en criterios individuales.
+//
+// Soporta las dos formas que se ven en la práctica:
+//   a) etiquetadas   — `- [ ] **AC-1** —` seguida de las tres líneas Gherkin
+//   b) sueltas       — una tanda de `- Dado … / - Cuando … / - Entonces …`
+// En (b) cada `Dado` abre un criterio nuevo, que es como se leen naturalmente.
+export function splitCriteria(block) {
+  const lines = (block || "").split(/\r?\n/).map(strip).filter((l) => l !== "");
+  const hasLabels = lines.some((l) => /^AC[-\s]?\d+\b/i.test(l));
+  const out = [];
+  let cur = null;
+  const open = (label) => { cur = { label: label || null, lines: [] }; out.push(cur); };
+
+  for (const l of lines) {
+    const label = l.match(/^(AC[-\s]?\d+)\b\s*[—:\-]?\s*(.*)$/i);
+    if (hasLabels && label) {
+      open(label[1]);
+      if (label[2]) cur.lines.push(label[2]);
+      continue;
+    }
+    if (!hasLabels && GHERKIN.dado.test(l)) { open(null); }
+    if (!cur) open(null);
+    cur.lines.push(l);
+  }
+  return out.map((c, i) => {
+    const text = c.lines.join(" ");
+    return {
+      label: c.label || `#${i + 1}`,
+      text,
+      dado: c.lines.some((l) => GHERKIN.dado.test(l)),
+      cuando: c.lines.some((l) => GHERKIN.cuando.test(l)),
+      entonces: c.lines.some((l) => GHERKIN.entonces.test(l)),
+    };
+  });
+}
+
+export const isGherkin = (c) => c.dado && c.cuando && c.entonces;
+
+// Palabras que delatan que el criterio se metió en el CÓMO. El QUÉ es funcional: si un
+// criterio habla de endpoints o de tablas, el PO está diseñando la solución y ya no
+// describe el comportamiento observable (Art. 1). Es un aviso, no un bloqueo: a veces
+// el dominio realmente usa esas palabras.
+const TECNICAS = /\b(endpoint|API REST|base de datos|tabla SQL|migraci[oó]n|componente React|microservicio|query|schema|foreign key|índice|index)\b/i;
+
+// ¿Esta US está lista para viajar al tracker?
+//   → { ok, errors, warnings, criteria, title, acHashable }
+// `ok` es false SOLO si hay errors. Los warnings se muestran y se siguen (salvo --strict).
+export function validateUS(md) {
+  const errors = [], warnings = [];
+  const title = extractTitle(md);
+  if (!title) errors.push("falta el título: la US tiene que empezar con un '# Título'.");
+  else if (title.split(/\s+/).length > 10) {
+    warnings.push(`el título tiene ${title.split(/\s+/).length} palabras — el molde pide 3 a 6 (de ahí sale el nombre de la branch).`);
+  }
+
+  const block = extractAcBlock(md);
+  if (block == null) {
+    errors.push("falta la sección '## Criterios de aceptación'. Sin criterios no hay ac_hash, y sin ac_hash no hay link QUÉ↔CÓMO.");
+    return { ok: false, errors, warnings, criteria: [], title, acHashable: false };
+  }
+
+  const criteria = splitCriteria(block);
+  if (criteria.length === 0) {
+    errors.push("la sección 'Criterios de aceptación' está vacía.");
+    return { ok: false, errors, warnings, criteria, title, acHashable: false };
+  }
+
+  for (const c of criteria) {
+    if (!isGherkin(c)) {
+      const falta = [!c.dado && "Dado", !c.cuando && "Cuando", !c.entonces && "Entonces"].filter(Boolean).join(" / ");
+      warnings.push(`${c.label}: no es Gherkin completo — falta ${falta}. Un criterio sin las tres partes es difícil de volver un test.`);
+    }
+    if (TECNICAS.test(c.text)) {
+      warnings.push(`${c.label}: menciona implementación (${c.text.match(TECNICAS)[0]}). El QUÉ describe comportamiento observable; el CÓMO lo decide el dev.`);
+    }
+  }
+  return { ok: errors.length === 0, errors, warnings, criteria, title, acHashable: true };
+}
+
+// ── spec_version ─────────────────────────────────────────────────────────────
+// El número que COMUNICA el cambio del QUÉ; el ac_hash es el que lo DETECTA
+// (METODOLOGIA §4). Sube cuando el cambio es material, y eso lo sabe el PO: dai
+// mirando el hash no puede distinguir un criterio nuevo de un typo corregido.
+
+export const parseSpecVersion = (md) => {
+  const m = String(md || "").match(/spec[_ ]version[^\n]*?\b(v\d+)\b/i);
+  return m ? m[1] : null;
+};
+
+export const bumpSpecVersion = (v) => {
+  const n = Number(String(v || "v1").replace(/^v/i, "")) || 1;
+  return `v${n + 1}`;
+};
+
+// Reescribe el spec_version en el markdown. Si la US no declara ninguno (típico de una
+// traída de un tracker que nunca usó el molde), lo INSERTA justo debajo del título — no
+// al final, donde nadie lo ve, ni en una tabla que no existe.
+export function setSpecVersion(md, version) {
+  const text = String(md || "");
+  if (/spec[_ ]version[^\n]*?\bv\d+\b/i.test(text)) {
+    return text.replace(/(spec[_ ]version[^\n]*?\b)v\d+\b/i, `$1${version}`);
+  }
+  const lines = text.split(/\r?\n/);
+  const i = lines.findIndex((l) => /^#\s+\S/.test(l));
+  const stamp = `> **spec_version:** ${version}`;
+  if (i === -1) return `${stamp}\n\n${text}`;
+  lines.splice(i + 1, 0, "", stamp);
+  return lines.join("\n");
+}
+
+// Render de los hallazgos para la terminal. Devuelve las líneas ya formateadas.
+export function renderValidation({ errors, warnings, criteria }) {
+  const out = [];
+  for (const e of errors) out.push(`  ✗ ${e}`);
+  for (const w of warnings) out.push(`  ⚠ ${w}`);
+  if (errors.length === 0) {
+    const g = criteria.filter(isGherkin).length;
+    out.push(`  ✓ formato válido — ${criteria.length} criterio(s)${criteria.length ? `, ${g} en Gherkin completo` : ""}`);
+  }
+  return out;
+}

package/docs/EJEMPLO-END-TO-END.md

@@ -269,8 +269,8 @@ aprobación o rechazo:
 ## Paso 7 — Merge: la trazabilidad se estampa sola
 
 Al mergear, se corre `dai stamp` (el dev, o el CI si está automatizado — ADR-0003).
-Lee el `implements.yaml` y **estampa la cobertura inversa** en el ticket `ABC-482`,
-con links a la implementación:
+Deduce que la US de esta rama es `ABC-482`, lee el `implements.yaml` y **estampa la
+cobertura inversa** en el ticket, con links a la implementación:
 
 ```
 ABC-482 · implementado por  (lo estampó dai stamp)
@@ -312,7 +312,30 @@ AC-3 verdes → **US aceptada**. Cero sorpresas: si el QUÉ hubiera cambiado, el
 
 Dos sprints después, el PO agrega un criterio a `ABC-482` (ahora exige **avisar al
 comprador qué productos quedaron sin stock, sin cancelar el resto del carrito**).
-Sube la US a **v2** → cambia el `ac_hash`.
+
+Lo hace con `dai edit-us ABC-482`: la baja del tracker, la abre en su editor, valida el
+formato cuando guarda, y le pregunta si el cambio es material o editorial.
+
+```
+  ── formato de la US (.dai/us/ABC-482.md) ────────────
+  ✓ formato válido — 4 criterio(s), 4 en Gherkin completo
+
+  Cambiaron los criterios (ac_hash 7f3a9c2e → b81d40f5).
+    s = cambio material: subo spec_version a v2 y los repos con v1 se marcan ATRASADOS
+    n = cambio editorial (typo, redacción): se queda en v1
+  ¿Subo spec_version a v2? (S/n) s
+
+  ── ABC-482 · qué cambia en jira ────────────
+  título:     Finalizar la compra del carrito  (sin cambios)
+  criterios:  4
+  version:    v1 → v2
+  ac_hash:    7f3a9c2e → b81d40f5
+  ──────────────────────────────────────
+  Esto PISA la US ABC-482 en jira. ¿Guardo? (s/N) s
+✓ ABC-482 actualizada en jira  →  https://acme.atlassian.net/browse/ABC-482
+```
+
+La US sube a **v2** → cambia el `ac_hash`.
 
 ```
 ABC-482 · implementado por

package/docs/METODOLOGIA.md

@@ -83,6 +83,11 @@ cambio.
 - **`ac_hash`** lo calcula la máquina para **detectar**. Es el hash del bloque de
   *Criterios de aceptación* normalizado (whitespace colapsado, orden estable).
 
+> El reparto no es decorativo: la máquina sabe **que** algo cambió, la persona sabe **si
+> importa**. Un typo corregido mueve el hash igual que un criterio nuevo, y solo un humano
+> distingue el uno del otro. Por eso `dai edit-us` / `dai update-us` **proponen** subir el
+> `spec_version` cuando el hash se mueve, y esperan un sí o un no — nunca lo deciden solos.
+
 Cuando el QUÉ evoluciona, cambia el `ac_hash`; todos los CÓMO que declaran el hash
 viejo quedan marcados **atrasados** solos. El funcional ve "el backend todavía no
 tomó mi cambio"; el dev ve "el QUÉ que implementé cambió". Nadie avisa a nadie — el

package/docs/PROBAR.md

@@ -41,11 +41,18 @@ dai link-us finalizar-la-compra-del-carrito   # branch + implements.yaml
 git add -A && git commit -m "feat: guard carrito vacío"
 dai check                        # ✅ al día
 
-# 4. La demo del ⚠️: edita el criterio en .dai/us/<slug>.md y vuelve a chequear
+# 4. La demo del ⚠️: cambia el QUÉ y mira cómo se detecta solo
+dai edit-us finalizar-la-compra-del-carrito   # la trae, la abres, valida, pregunta si sube spec_version
 dai check                        # ⚠️ ATRASADO (exit 1)  → sugiere: dai link-us <id> --resync
+
+# 5. Estampa la cobertura
 dai stamp                        # con md, deja .dai/us/<slug>.coverage.md
 ```
 
+> En el paso 4, `dai edit-us` abre tu `$EDITOR`. Si no tienes uno configurado te pide
+> editar el archivo y volver, así que también funciona con el archivo abierto en tu IDE.
+> Agrega un criterio, guarda, y responde `s` a "¿subo spec_version?" para ver el ⚠️.
+
 Con esto ya viste el ciclo entero. Ahora conéctalo a tu tracker real.
 
 ## Paso 2 — contra tu tracker real (ClickUp)
@@ -75,6 +82,9 @@ dai check                        # ✅ al día
 # → edita un criterio de la tarea en ClickUp (en el navegador). Después:
 dai check                        # ⚠️ ATRASADO (lo detectó solo)
 dai stamp                        # deja un COMENTARIO en la tarea con la cobertura
+
+# ¿Editar la US sin salir de la terminal? La trae, la abres, valida y la devuelve:
+dai edit-us 86cxyz --dry-run     # el preview completo, sin escribir en ClickUp
 ```
 
 > El `.env.dai` **no se versiona**: el token no se commitea, y el `.env` del equipo no se
@@ -86,6 +96,7 @@ dai stamp                        # deja un COMENTARIO en la tarea con la cobertu
 |---|---|
 | `no encontré la US <id>` | ID mal, o el token no ve esa tarea |
 | `clickup 401` | token inválido o expirado |
+| `edit-us` dice que la US no tiene el formato mínimo | le falta el `# Título` o la sección `## Criterios de aceptación`. Sin criterios no hay `ac_hash` y no hay link |
 | `check` siempre da ⚠️ | editaste la US entre `link-us` y `check` (esperado), **o** los criterios no están bajo el heading `Criterios de aceptación` |
 | `sin US` en `check` | la tarea no tiene el bloque de criterios en la descripción |
 | branch/commit vacíos en el stamp | falta el remoto git (`git remote add origin …`) |

package/docs/SCRUM-CON-IA.md

@@ -50,8 +50,8 @@
 | **Clásico** | El PO parte épicas en Historias de Usuario y les pone criterios de aceptación. |
 | **Dolor** | US vagas, no testeables ("el usuario quiere un botón"). El malentendido se descubre tarde, ya implementado. |
 | **Con IA** | `grill-user-story` **interroga** al PO hasta que la US es testeable por construcción (INVEST + Gherkin); y después el Gate 0 de `grill-intent` desafía el *problema* detrás (veredicto: a-spec / reframe / descartar). La IA no *escribe* la US: la *saca a preguntas*. La US nace con ID estable y criterios hasheables. |
-| **Humano (HITL)** | El PO responde y decide. La IA no inventa requerimientos: los pule. |
-| **Herramienta** | `grill-user-story`, `grill-intent`, `formato-us.md` |
+| **Humano (HITL)** | El PO responde y decide. La IA no inventa requerimientos: los pule. Si la US ya existe y hay que retocarla, `dai edit-us <ID>` la baja del tracker, valida el formato al guardar y **pregunta** si el cambio es material (sube `spec_version`) o editorial. |
+| **Herramienta** | `grill-user-story`, `grill-intent`, `formato-us.md`, `dai edit-us` |
 | **Detalle →** | [`detalle/01-refinamiento.md`](detalle/01-refinamiento.md) |
 
 #### 2. Sprint Planning: comprometer US y derivar tareas