@dforce2055/dai 0.9.0 → 0.11.0

package/cli/lib/bootstrap.mjs

@@ -47,13 +47,38 @@ function unquoteScalar(s) {
 // Parsea el frontmatter YAML de un SKILL.md → { name, description, body }.
 // Devuelve los valores YA sin comillas, para que quien los reserialice (skillToCursor)
 // no los cite dos veces.
+// Lee un campo del frontmatter. Soporta escalar de una línea (con/sin comillas) y BLOQUE
+// YAML (`|` literal, `>` plegado, con chomp `-`/`+`): junta las líneas indentadas siguientes
+// hasta la próxima clave (columna 0). El parser de dai es regex, no un YAML completo — esto
+// cubre lo común: descripciones multilínea, que es como se escriben las skills reales.
+function readFmField(fm, key) {
+  const lines = fm.split(/\r?\n/);
+  const keyRe = new RegExp(`^${key}:\\s*(.*)$`);
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(keyRe);
+    if (!m) continue;
+    const inline = m[1].trim();
+    const blk = inline.match(/^([|>])[-+]?\s*$/);       // |, >, |-, |+, >-, >+
+    if (!blk) return unquoteScalar(inline) || null;     // escalar de una línea
+    const buf = [];
+    for (let j = i + 1; j < lines.length; j++) {
+      if (lines[j].trim() === "") { buf.push(""); continue; }
+      if (!/^\s/.test(lines[j])) break;                 // sin indentar → empezó otra clave
+      buf.push(lines[j]);
+    }
+    const indent = ((buf.find((l) => l.trim() !== "") || "").match(/^\s*/) || [""])[0].length;
+    const text = buf.map((l) => l.slice(indent)).join("\n").replace(/\s+$/, "");
+    // `>` plegado: un salto simple → espacio; los dobles (párrafo) se conservan.
+    return (blk[1] === ">" ? text.replace(/([^\n])\n(?!\n)/g, "$1 ") : text) || null;
+  }
+  return null;
+}
+
 export function parseFrontmatter(md) {
   const m = md.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
   if (!m) return { name: null, description: null, body: md.trim() };
   const fm = m[1];
-  const name = unquoteScalar((fm.match(/^name:\s*(.+)$/m) || [])[1]) || null;
-  const description = unquoteScalar((fm.match(/^description:\s*(.+)$/m) || [])[1]) || null;
-  return { name, description, body: m[2].trim() };
+  return { name: readFmField(fm, "name"), description: readFmField(fm, "description"), body: m[2].trim() };
 }
 
 // Valida el contrato MÍNIMO de un SKILL.md para que dai lo ingiera y los asistentes lo
@@ -66,7 +91,11 @@ export function validateSkill(md) {
   if (!name) return "falta 'name' en el frontmatter";
   if (!description) return "falta 'description' en el frontmatter";
   for (const key of ["name", "description"]) {
-    const issue = yamlScalarIssue(rawFrontmatterValue(md, key));
+    const raw = rawFrontmatterValue(md, key);
+    // Un bloque YAML (`|`, `>`, con chomp) es literal → siempre válido; su contenido va en las
+    // líneas indentadas, no en el valor de la clave. No lo pasamos por el scalar-check.
+    if (/^[|>][-+]?\s*$/.test(String(raw ?? "").trim())) continue;
+    const issue = yamlScalarIssue(raw);
     if (issue) return `'${key}' no es YAML válido: ${issue} — citá el valor con comillas dobles`;
   }
   return null;
@@ -98,7 +127,7 @@ export function skillToCursor(md) {
 // la URL canónica que devuelve el tracker, así que el `/t/{id}` que escribíamos acá
 // tapaba la de ClickUp con team_id. Queda como override manual para trackers raros.
 export function envFor(pm) {
-  const head = "# Config de dai — completá lo que falte. NUNCA commitees tokens (.env está gitignored).\n";
+  const head = "# Config de dai — va en .env.dai (NO versionado), no en el .env del equipo.\n# Completá lo que falte. NUNCA commitees tokens.\n";
   if (pm === "clickup") {
     return head + "DAI_PM=clickup\nDAI_CLICKUP_TOKEN=\nDAI_CLICKUP_LIST_ID=\n";
   }
@@ -156,7 +185,10 @@ export function reconcileGitignore(text, want) {
   // `.dai/` NO va acá: ahí vive config que SÍ se versiona (jira-fields.json). Solo se
   // ignora `.dai/reviews/`, que son borradores de `dai forge review` — efímeros, con
   // hallazgos a medio editar, y no tienen por qué viajar en un commit.
-  const ensure = [".env", ".dai/reviews/"];
+  // `.env.dai` (config y secretos de dai) SÍ se ignora; el `.env` del equipo NO lo tocamos:
+  // es suyo y muchas orgs lo versionan como política (ADR-0017). La plantilla
+  // `.env.dai.example` sí se versiona (no matchea `.env.dai` exacto, así que no se ignora).
+  const ensure = [".env.dai", ".dai/reviews/"];
   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;
@@ -165,8 +197,11 @@ export function reconcileGitignore(text, want) {
     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));
+  // Se compara NORMALIZADO: `.dai/reviews`, `/.dai/reviews/` y `.dai/reviews/` son la
+  // misma regla para git. Comparando el texto crudo agregábamos un duplicado al repo
+  // de quien ya la había puesto a mano.
+  const have = new Set(lines.filter((l) => !l.trim().startsWith("#")).map((l) => norm(l)));
+  const add = ensure.filter((e) => !have.has(norm(e)));
   if (add.length) {
     changed = true;
     if (lines.length && lines[lines.length - 1].trim() !== "") lines.push("");
@@ -199,7 +234,7 @@ export function constitution(kind) {
 - **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**.
+- **Secretos:** en \`.env.dai\` (NO versionado; el \`.env\` del equipo no se toca). git por **SSH**, APIs por **token scopeado**.
 - **No bajes la seguridad para avanzar:** si una llamada falla por el certificado, declara la CA (\`NODE_EXTRA_CA_CERTS\`). **Nunca** \`NODE_TLS_REJECT_UNAUTHORIZED=0\`, \`verify=False\`, \`-k\` ni equivalentes: apagan la verificación de toda la conexión, y por ahí viajan los tokens.
 - **Si el CLI no llega, para y dilo:** cuando \`dai\` no cubre un caso, repórtalo — no improvises una llamada a la API por fuera. El atajo publica igual, pero rompe el link QUÉ↔CÓMO en silencio y nadie se entera hasta que la trazabilidad ya está mal.
 - **Docs vivas:** una constitución o arquitectura desactualizada es un defecto, no documentación.

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/env.mjs

@@ -4,6 +4,18 @@
 
 import { readFileSync } from "node:fs";
 
+// Config de dai: `.env.dai` (propio, nunca versionado) tiene prioridad sobre `.env`.
+// Pensado para equipos que versionan el `.env` (política de empresa): dai deja ese
+// archivo en paz y pone sus claves y secretos en `.env.dai` (gitignored). Se carga
+// `.env.dai` PRIMERO porque el loader es "primero-gana" (ver más abajo), así la
+// precedencia queda: entorno (shell/CI) > .env.dai > .env. Leer también `.env`
+// mantiene compatibilidad con repos previos que tienen los DAI_* ahí.
+export function loadDaiEnv(env = process.env) {
+  loadEnv(".env.dai", env);
+  loadEnv(".env", env);
+  return env;
+}
+
 export function loadEnv(path = ".env", env = process.env) {
   let text;
   try { text = readFileSync(path, "utf8"); } catch { return env; } // sin .env: no pasa nada

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

@@ -22,7 +22,7 @@ export function clickupTaskToText(json) {
 }
 
 export function clickupAdapter(env) {
-  if (!env.DAI_CLICKUP_TOKEN) throw new Error("falta DAI_CLICKUP_TOKEN en el .env (backend clickup).");
+  if (!env.DAI_CLICKUP_TOKEN) throw new Error("falta DAI_CLICKUP_TOKEN en el .env.dai (backend clickup).");
   return {
     kind: "clickup",
     async fetchUS(id) {
@@ -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,9 +42,23 @@ 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 (la lista donde crear la tarea).");
+      if (!list) throw new Error("falta DAI_CLICKUP_LIST_ID en el .env.dai (la lista donde crear la tarea).");
       const res = await fetch(`${API}/list/${encodeURIComponent(list)}/task`, {
         method: "POST", headers: clickupAuthHeaders(env),
         body: JSON.stringify({ name: title, markdown_content: descriptionMarkdown }),

package/cli/lib/pm-jira.mjs

@@ -15,7 +15,7 @@ const trim = (b) => String(b || "").replace(/\/+$/, "");
 // error de config más común: `dai init` deja DAI_JIRA_PROJECT vacío y quien lo completa
 // suele pegar la épica que tiene a mano. Jira responde un 400 que no lo explica.
 export function assertProjectKey(key) {
-  if (!key) throw new Error("falta DAI_JIRA_PROJECT en el .env (la clave del proyecto donde crear el issue).");
+  if (!key) throw new Error("falta DAI_JIRA_PROJECT en el .env.dai (la clave del proyecto donde crear el issue).");
   const k = String(key).trim();
   const m = k.match(/^([A-Za-z][A-Za-z0-9_]*)-\d+$/);
   if (m) {
@@ -136,14 +136,15 @@ export function createHint(status, body = "") {
 
 export function jiraAdapter(env) {
   const base = env.DAI_JIRA_BASE_URL;
-  if (!base) throw new Error("falta DAI_JIRA_BASE_URL en el .env (backend jira).");
+  if (!base) throw new Error("falta DAI_JIRA_BASE_URL en el .env.dai (backend jira).");
   return {
     kind: "jira",
     async fetchUS(id) {
       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/skills-source.mjs

@@ -15,6 +15,14 @@ export function parseSource(src) {
   const hash = raw.lastIndexOf("#");
   if (hash > 0) { ref = raw.slice(hash + 1) || null; loc = raw.slice(0, hash); }
 
+  // Paquete npm: `npm:@scope/pkg[@version]`. dai hace `npm pack` a un temp, respetando el
+  // `.npmrc` del repo (así resuelve registries privados con scope). La versión va en el
+  // propio spec (`@1.2.3`), no como ref con '#'.
+  if (loc.startsWith("npm:")) {
+    const spec = loc.slice(4).trim();
+    if (!spec) throw new Error("fuente npm vacía (usá npm:@scope/paquete)");
+    return { type: "npm", location: spec, ref: null };
+  }
   // Path local explícito (./ ../ / ~/).
   if (/^(\.\.?\/|\/|~\/)/.test(loc)) return { type: "path", location: loc, ref };
   // git por sintaxis de URL (https, ssh, scp git@host:…).

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;
+}