@dforce2055/dai 0.9.0 → 0.11.0

package/cli/dai.mjs

@@ -21,7 +21,7 @@ import { createInterface } from "node:readline/promises";
 import { acHash } from "./lib/ac-hash.mjs";
 import { discoverImplements, isPlaceholderId } from "./lib/implements.mjs";
 import { isValidKey, slugify, branchName, extractTitle, renderImplementsYaml } from "./lib/link-us.mjs";
-import { loadEnv } from "./lib/env.mjs";
+import { loadDaiEnv } from "./lib/env.mjs";
 import { getAdapter, coverageStatus, statusLabel } from "./lib/pm-adapter.mjs";
 import { branchUrl, commitUrl, parseRemote, detectForge } from "./lib/forge-url.mjs";
 import { parsePrRef, getPR, postComment, postReview } from "./lib/forge-api.mjs";
@@ -35,6 +35,9 @@ import { parseSource } from "./lib/skills-source.mjs";
 import { skillToCursor, validateSkill, constitution, constitutionCursorRule, envFor, mergeEnv, upsertBlock, reconcileGitignore, stalePromptFiles } from "./lib/bootstrap.mjs";
 import { parseFieldsFile, parseFieldOverrides, resolveJiraFields } from "./lib/jira-fields.mjs";
 import { assertProjectKey } from "./lib/pm-jira.mjs";
+import { flattenImplements, stampScope, requiresLink, trackerKeysIn } from "./lib/branch-scope.mjs";
+import { describeForgeError, parseForgeError } from "./lib/forge-api.mjs";
+import { validateUS, renderValidation, parseSpecVersion, bumpSpecVersion, setSpecVersion } from "./lib/us-format.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -48,8 +51,36 @@ const warn = (m) => process.stdout.write(`⚠ ${m}\n`);
 // Color ANSI mínimo — solo si es TTY y no está NO_COLOR (así no ensucia pipes/CI).
 const _color = process.stdout.isTTY && !process.env.NO_COLOR;
 const paint = (code, m) => (_color ? `\x1b[${code}m${m}\x1b[0m` : m);
-const C = { y: (m) => paint("33", m), r: (m) => paint("31", m), cy: (m) => paint("36", m), b: (m) => paint("1", m) };
+const C = { y: (m) => paint("33", m), r: (m) => paint("31", m), cy: (m) => paint("36", m), b: (m) => paint("1", m), dim: (m) => paint("2", m) };
 const ROOT = join(HERE, "..");            // raíz del paquete dai (cli/ está adentro)
+// Rutas relativas al cwd en la salida: una ruta absoluta de 120 caracteres no se lee ni
+// se copia. Si el archivo está fuera del cwd (`../otro`), se muestra tal cual.
+const rel = (p) => { const r = relative(process.cwd(), p); return !r || r.startsWith("..") ? p : r; };
+
+// Banner de bienvenida de `dai init`: el Sol de Mayo en bloques (cuerpo y rayos rectos en
+// oro; rayos ondulados en celeste) al lado del título, más el preview de lo que se configura.
+// Todo con caracteres — cero-dep. Degrada a ASCII sin color si no hay TTY o con NO_COLOR.
+const initBanner = () => {
+  const sun = [
+    "     █     ",
+    " ▒ ▄███▄ ▒ ",
+    "██ █████ ██",
+    " ▒ ▀███▀ ▒ ",
+    "     █     ",
+  ];
+  const paintSun = (line) => [...line].map((ch) => (ch === "▒" ? C.cy(ch) : ch === " " ? " " : C.y(ch))).join("");
+  const aside = ["", paint("1;33", "dai") + " · Desarrollo Asistido por IA", C.dim("La IA asiste; la persona firma."), "", ""];
+  let out = "\n";
+  for (let i = 0; i < sun.length; i++) out += "  " + paintSun(sun[i]) + (aside[i] ? "    " + aside[i] : "") + "\n";
+  out += "\n  " + C.b("Esto va a configurar el repo:") + "\n";
+  for (const b of [
+    "Skills del método (grill · link-us · tdd · dai-review) en tu asistente",
+    "La constitución del proyecto — las reglas del trabajo",
+    "OpenSpec para el CÓMO (design / tasks) — opcional",
+    "Plantilla de PR + .env.dai para el tracker",
+  ]) out += "    " + C.cy("▸") + " " + b + "\n";
+  return out;
+};
 const CLAUDE_SKILLS_DIR = process.env.CLAUDE_SKILLS_DIR || join(homedir(), ".claude", "skills");
 const CURSOR_SKILLS_DIR = process.env.CURSOR_SKILLS_DIR || join(homedir(), ".cursor", "skills");
 // Copilot lee las skills personales de ~/.copilot/skills (NO de ~/.claude/skills, que
@@ -119,10 +150,10 @@ async function cmdLinkUs(key, opts) {
     title = opts.title || extractTitle(md);
   } else {
     // Fuente tracker: traer la US del adaptador (mismo hash que usará `dai check`).
-    loadEnv();
+    loadDaiEnv();
     const adapter = getAdapter(process.env);
     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);
+    if (!us) fail(`no encontré la US ${key} en el backend ${adapter.kind}. Pasa --us <md> o revisa el .env.dai.`, 2);
     hash = us.ac_hash;
     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;
@@ -178,9 +209,84 @@ function gitRemote() { try { return git(["remote", "get-url", "origin"]); } catc
 function gitBranch() { try { return git(["rev-parse", "--abbrev-ref", "HEAD"]); } catch { return null; } }
 function gitCommit() { try { return git(["rev-parse", "HEAD"]); } catch { return null; } }
 
+// ── check --ci: el gate de governance/ci-rules.md, ejecutable ────────────────
+//
+// La brecha del issue #26: ci-rules.md prometía "sin implements.yaml el CI bloquea",
+// pero no existía el comando que lo hiciera. Era una regla escrita que nadie aplicaba.
+//
+// Lo que NO hace: exigirle US a todo. Una `chore/` o una `fix/` sin ticket son trabajo
+// legítimo (branch-naming.md), y un gate que las bloquea se desactiva a la semana.
+// Quién decide es requiresLink(), leyendo el nombre de la branch.
+//
+// Salidas:  0 = pasa · 1 = falta el link · 2 = hay link pero el QUÉ cambió (atrasado)
+async function cmdCheckCi(opts = {}) {
+  const branch = opts.branch || process.env.DAI_CI_BRANCH || ciBranch() || gitBranch();
+  const { required, reason } = requiresLink(branch);
+  const rows = flattenImplements(discoverImplements(process.cwd(), { includeArchived: false }));
+
+  info(`branch '${branch || "(desconocida)"}' — ${reason}`);
+  if (!required) {
+    if (rows.length) info(`igual declara ${rows.length} US (${rows.map((r) => r.id).join(", ")}) — se chequea su cobertura.`);
+    else { ok("gate OK — esta branch no requiere US."); process.exit(0); }
+  }
+  if (required && rows.length === 0) {
+    const ids = trackerKeysIn(branch);
+    process.stderr.write(
+      "✗ gate: falta el link QUÉ↔CÓMO — esta branch no tiene implements.yaml.\n" +
+      `    Crealo:  dai link-us ${ids[0] || "<ID-DE-LA-US>"}\n` +
+      "    Si NO implementa una US (tooling, deps, docs), renombrá la branch con un\n" +
+      "    prefijo exento — chore/, docs/, ci/ — según governance/branch-naming.md.\n");
+    process.exit(1);
+  }
+
+  // Hay link: que además esté al día contra la US viva. Sin token/backend eso no se
+  // puede saber, y un gate que bloquea por falta de red es un gate que se apaga:
+  // con --no-network (o sin adaptador utilizable) valida el link y no más.
+  if (opts.noNetwork) {
+    ok(`gate OK — ${rows.length} US linkeada(s): ${rows.map((r) => r.id).join(", ")} (--no-network: no se comparó contra la US viva).`);
+    process.exit(0);
+  }
+  loadDaiEnv();
+  let adapter;
+  try { adapter = getAdapter(process.env); }
+  catch (e) {
+    warn(`no puedo comparar contra la US viva: ${e.message}`);
+    ok(`gate OK igual — el link existe (${rows.map((r) => r.id).join(", ")}). Configurá el backend para chequear también el atraso.`);
+    process.exit(0);
+  }
+  let worst = 0;
+  for (const r of rows) {
+    let live = null, netErr = null;
+    try { live = await adapter.fetchUS(r.id); } catch (e) { netErr = String(e.message).split("\n")[0]; }
+    if (netErr) { warn(`${r.id}: no pude leer la US (${netErr}) — no bloqueo por un problema de red/credencial.`); continue; }
+    const status = coverageStatus(r.ac_hash, live?.ac_hash);
+    if (status === "al-dia") ok(`${r.id} al día (${r.version})`);
+    else if (status === "atrasado") {
+      process.stderr.write(`✗ gate: ${r.id} ATRASADO — implementaste ${r.ac_hash}, la US viva es ${live.ac_hash}.\n` +
+        `    El QUÉ cambió. Resincronizá y revisá que lo cubras:  dai link-us ${r.id} --resync\n`);
+      worst = Math.max(worst, 2);
+    } else {
+      warn(`${r.id}: no encontré la US en ${adapter.kind} — el link apunta a un ID que el tracker no tiene.`);
+      worst = Math.max(worst, 2);
+    }
+  }
+  if (worst === 0) ok(`gate OK — ${rows.length} US linkeada(s) y al día.`);
+  process.exit(worst);
+}
+
+// La branch real en CI: en una PR, HEAD es un merge commit detached, así que
+// `git rev-parse --abbrev-ref HEAD` devuelve "HEAD" y no el nombre. Cada forge la
+// expone en su propia variable.
+function ciBranch() {
+  const e = process.env;
+  return e.GITHUB_HEAD_REF || e.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME || e.CI_COMMIT_REF_NAME ||
+    e.BITBUCKET_BRANCH || e.BUILD_SOURCEBRANCHNAME ||
+    (e.GITHUB_REF_NAME && !/^\d+\/merge$/.test(e.GITHUB_REF_NAME) ? e.GITHUB_REF_NAME : null) || null;
+}
+
 // ── check ──────────────────────────────────────────────────────────────────
 async function cmdCheck() {
-  loadEnv();
+  loadDaiEnv();
   const adapter = getAdapter(process.env);
   const found = discoverImplements(process.cwd(), { includeArchived: false });
   let worst = 0, n = 0;
@@ -210,38 +316,106 @@ async function cmdCheck() {
 }
 
 // ── stamp ──────────────────────────────────────────────────────────────────
-async function cmdStamp() {
-  loadEnv();
+// Estampa la cobertura de UNA US: la de esta branch. Antes recorría todo el repo
+// —archivados incluidos— así que cerrar una US le dejaba un comentario a las cuatro
+// del sprint (issue #22). Ahora decide con branch-scope.mjs y, si no puede saber cuál,
+// PREGUNTA en vez de estampar de más: un comentario en el tracker no se deshace.
+async function cmdStamp(ids = [], opts = {}) {
+  loadDaiEnv();
   const adapter = getAdapter(process.env);
   const remote = gitRemote(), branch = gitBranch(), commit = gitCommit();
-  const found = discoverImplements(process.cwd());
-  let n = 0;
-  for (const f of found) for (const im of f.implements || []) {
-    if (isPlaceholderId(im.id)) continue;   // plantilla sin completar, no es una US real
-    n++;
-    const live = await adapter.fetchUS(im.id);
-    const status = coverageStatus(im.ac_hash, live?.ac_hash);
+  const rows = flattenImplements(discoverImplements(process.cwd(), { includeArchived: false }));
+  const allRows = flattenImplements(discoverImplements(process.cwd()));
+  const scope = stampScope({ branch, rows, allRows, ids, all: !!opts.all });
+
+  if (scope.mode === "none") { process.stdout.write("No hay implements.yaml para estampar.\n"); return; }
+  if (scope.mode === "explicit" && scope.missing?.length) {
+    fail(`no encontré implements.yaml para: ${scope.missing.join(", ")}.\n` +
+         `  US en este repo: ${allRows.map((r) => r.id).join(", ") || "(ninguna)"}`, 1);
+  }
+
+  let targets = scope.targets;
+  if (scope.mode === "ambiguous") {
+    warn(`${scope.reason}.`);
+    const listed = scope.candidates.map((r, i) => `    ${i + 1}) ${r.id}  ${C.dim(`(${r.change})`)}`).join("\n");
+    process.stdout.write(`  US vivas en el repo:\n${listed}\n`);
+    if (opts.yes || !process.stdin.isTTY) {
+      fail("no sé cuál estampar. Decilo explícitamente:  dai stamp <ID>   (o `dai stamp --all` para todas).", 1);
+    }
+    const ans = await askOrCancel("  ¿Cuál estampo? (número, varios con coma, 'a'=todas, Enter=cancelar) ");
+    if (!ans) { info("Cancelado — no se estampó nada."); return; }
+    if (/^a(ll|)$/i.test(ans)) targets = scope.candidates;
+    else {
+      const picked = ans.split(/[,\s]+/).filter(Boolean).map((t) => Number(t));
+      if (picked.some((n) => !Number.isInteger(n) || n < 1 || n > scope.candidates.length)) {
+        fail(`respuesta inválida: '${ans}'. Se esperaba número(s) entre 1 y ${scope.candidates.length}, o 'a'.`, 1);
+      }
+      targets = picked.map((n) => scope.candidates[n - 1]);
+    }
+  } else if (scope.mode !== "all") {
+    info(`${scope.reason} → estampo ${targets.map((t) => t.id).join(", ")}.`);
+  }
+
+  for (const r of targets) {
+    const live = await adapter.fetchUS(r.id);
+    const status = coverageStatus(r.ac_hash, live?.ac_hash);
     const record = {
-      repo: f.repo, change: f.change, version: im.version, ac_hash: im.ac_hash, status,
+      repo: r.repo, change: r.change, version: r.version, ac_hash: r.ac_hash, status,
       branch, branchUrl: branchUrl(remote, branch), commit, commitUrl: commitUrl(remote, commit),
     };
-    const where = await adapter.stamp(im.id, record);
-    process.stdout.write(`✓ ${im.id} → ${where}  (${statusLabel(status)})\n`);
+    const where = await adapter.stamp(r.id, record);
+    process.stdout.write(`✓ ${r.id} → ${where}  (${statusLabel(status)})\n`);
   }
-  if (n === 0) process.stdout.write("No hay implements.yaml para estampar.\n");
+  if (targets.length === 0) process.stdout.write("No se estampó nada.\n");
 }
 
 // ── forge (review) ───────────────────────────────────────────────────────────
+// El review.json lo escribe la SKILL, no el CLI — así que `dai init`/`dai sync` son los
+// únicos que ponían `.dai/reviews/` en el .gitignore, y un repo inicializado con una dai
+// vieja se comía borradores a medio editar en un commit (issue #25). Acá lo arreglamos
+// donde duele: al consumir el archivo. Aditivo, y solo si el borrador está bajo
+// `.dai/reviews/` — si el equipo decidió versionar sus reviews en otro lado, no opinamos.
+function ensureReviewsIgnored(fromPath) {
+  const rel = relative(process.cwd(), fromPath).replace(/\\/g, "/");
+  if (!rel.startsWith(".dai/reviews/")) return;
+  const giPath = join(process.cwd(), ".gitignore");
+  if (!existsSync(giPath)) return;               // sin .gitignore no inventamos uno
+  const cur = readFileSync(giPath, "utf8");
+  const gi = reconcileGitignore(cur, {});        // {} → solo el `ensure` base (.env.dai, .dai/reviews/)
+  if (!gi.changed) return;
+  writeFileSync(giPath, gi.text.endsWith("\n") ? gi.text : gi.text + "\n");
+  info(".gitignore: agregué `.dai/reviews/` — los borradores de review no viajan en un commit.");
+  info("            Si tu equipo los quiere versionar, sacá esa línea a mano.");
+}
+
+// Una pregunta puntual por TTY. Ctrl+D (EOF) devuelve "" — se trata como "cancelar", no
+// como un crash: en un prompt que precede a una acción irreversible, abortar es la
+// respuesta más segura, y "Aborted with Ctrl+D" no le dice eso a nadie.
+async function askOrCancel(q) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try { return (await rl.question(q)).trim(); }
+  catch { process.stdout.write("\n"); return ""; }
+  finally { rl.close(); }
+}
+
+// Corre una llamada al forge y, si falla, la traduce a una causa concreta (issue #24)
+// en vez del genérico "¿token? ¿ref correcta?".
+async function forgeCall(pr, fn) {
+  try { return await fn(); }
+  catch (e) { fail(describeForgeError(pr, { ...parseForgeError(e), env: process.env }), 1); }
+}
+
 async function cmdForge(sub, ref, opts) {
-  loadEnv();
+  loadDaiEnv();
   const pr = parsePrRef(ref, gitRemote());
   if (!pr) fail("no pude resolver la PR/MR. Pasa la URL completa o el número (con remoto git).", 1);
   if (sub === "pr") {
-    process.stdout.write(JSON.stringify(await getPR(pr, process.env), null, 2) + "\n");
+    const j = await forgeCall(pr, () => getPR(pr, process.env));
+    process.stdout.write(JSON.stringify(j, null, 2) + "\n");
   } else if (sub === "comment") {
     const body = opts.bodyFile ? readFileSync(opts.bodyFile, "utf8") : opts.body;
     if (!body) fail("falta --body-file <archivo> o --body <texto>.", 1);
-    const res = await postComment(pr, body, process.env);
+    const res = await forgeCall(pr, () => postComment(pr, body, process.env));
     process.stdout.write(`✓ comentario posteado${res.url ? `: ${res.url}` : ""}\n`);
   } else if (sub === "review") {
     await cmdForgeReview(pr, opts);
@@ -259,11 +433,11 @@ async function cmdForge(sub, ref, opts) {
 async function cmdForgeReview(pr, opts) {
   if (!opts.from) fail("falta --from <review.json>. Lo escribe la skill dai-review; revisalo antes de postear.", 1);
   const review = parseFindings(readFileSync(opts.from, "utf8"));
+  ensureReviewsIgnored(opts.from);
 
   // El diff sale de git (local, por SSH), no de la API: es la fuente de verdad de qué
   // línea es comentable, y no gasta rate limit.
-  const remote = await Promise.resolve(getPR(pr, process.env)).catch(() => null);
-  if (!remote) fail("no pude leer la PR/MR del forge (¿token? ¿ref correcta?).", 1);
+  const remote = await forgeCall(pr, () => getPR(pr, process.env));
   const base = opts.base || remote.baseRef;
   if (!base) fail("no pude saber la branch base de la PR. Pasala con --base <branch>.", 1);
   let diff = "";
@@ -310,7 +484,7 @@ async function cmdForgeReview(pr, opts) {
   }
   if (!kept.length && !review.summary) fail("no hay nada que postear (0 comentarios y resumen vacío).", 1);
 
-  const res = await postReview(pr, { body, comments, headSha: remote.headSha, diffRefs: remote.diffRefs }, process.env);
+  const res = await forgeCall(pr, () => postReview(pr, { body, comments, headSha: remote.headSha, diffRefs: remote.diffRefs }, process.env));
   ok(`review posteado${res.url ? `: ${res.url}` : ""} — ${res.posted} comentario(s) en línea.`);
   if (res.failed.length) {
     warn(`${res.failed.length} comentario(s) NO entraron (gitlab no es atómico: el resumen y el resto SÍ están posteados):`);
@@ -332,7 +506,7 @@ function loadJiraFieldsSpec() {
 
 async function cmdPublish(file, opts = {}) {
   if (!file) fail("uso: dai publish <archivo-us.md> [--parent KEY] [--issuetype T] [--field alias=valor]", 1);
-  loadEnv();
+  loadDaiEnv();
   const md = readFileSync(file, "utf8");
   const title = extractTitle(md);
   if (!title) fail("no pude extraer el título de la US (falta un '# Título').", 1);
@@ -362,6 +536,254 @@ async function cmdPublish(file, opts = {}) {
   info(`Próximo paso (el dev abre el CÓMO):  dai link-us ${r.id}`);
 }
 
+// ── edit-us / update-us: el QUÉ cambia y el tracker se entera ────────────────
+//
+// Dos puertas de entrada a UN camino. La diferencia es de dónde sale el markdown:
+//
+//   dai edit-us <ID>    trae la US del tracker → la abrís en tu editor → valida → empuja
+//   dai update-us <ID>  ya tenés el .md escrito (lo refinaste implementando) → empuja
+//
+// El tramo compartido —validar, mostrar el diff, proponer el bump de spec_version,
+// confirmar, escribir, re-estampar el ac_hash local— es `pushUS`. No es código duplicado
+// con dos nombres: es un solo camino con dos entradas, y por eso las dos puertas dan
+// exactamente el mismo preview y la misma confirmación.
+
+// Los campos propios de Jira, si el proyecto los exige (compartido por las dos puertas).
+function fieldsFor(adapter, opts) {
+  if (opts.field === undefined) return undefined;
+  if (adapter.kind !== "jira") fail(`--field es solo para jira (DAI_PM=${adapter.kind}).`, 2);
+  return resolveJiraFields({
+    spec: loadJiraFieldsSpec(),
+    issuetype: opts.issuetype || process.env.DAI_JIRA_ISSUETYPE || "Story",
+    overrides: parseFieldOverrides(asList(opts.field)),
+  });
+}
+
+// El backend md devuelve SINCRÓNICO (el contrato del adaptador lo permite), así que
+// `adapter.fetchUS(id).catch(...)` explotaba con DAI_PM=md. Se normaliza a promesa.
+const fetchLive = (adapter, id) => Promise.resolve().then(() => adapter.fetchUS(id)).catch(() => null);
+
+// Valida el formato e imprime el veredicto. Devuelve el resultado; corta si hay errores.
+function validateOrFail(md, source, { strict = false } = {}) {
+  const v = validateUS(md);
+  const lines = renderValidation(v);
+  process.stdout.write(`\n  ── formato de la US (${source}) ────────────\n`);
+  for (const l of lines) process.stdout.write(l + "\n");
+  if (!v.ok) {
+    process.stdout.write("\n");
+    fail("la US no tiene el formato mínimo para viajar al tracker (ver arriba).\n" +
+         "  El molde canónico está en .dai/templates/formato-us.md, y /grill-user-story te interroga hasta llegar a él.", 2);
+  }
+  if (strict && v.warnings.length) {
+    process.stdout.write("\n");
+    fail(`--strict: ${v.warnings.length} advertencia(s) y ninguna se puede ignorar en este modo.`, 2);
+  }
+  return v;
+}
+
+// El tramo compartido: preview → spec_version → confirmación → tracker → ac_hash local.
+// `md` puede reescribirse acá (el bump de spec_version), por eso devuelve el markdown final.
+async function pushUS(id, md, { adapter, file, opts, live }) {
+  const validation = validateOrFail(md, rel(file), { strict: !!opts.strict });
+  const title = opts.title || validation.title;
+  const newHash = acHash(md);
+
+  // ── spec_version: el número COMUNICA, el hash DETECTA (METODOLOGIA §4) ──────
+  // Si cambiaron los criterios se PROPONE subirlo, no se impone: dai mirando el hash no
+  // distingue un criterio nuevo de un typo corregido, y quien sabe la diferencia es el PO.
+  const curVer = parseSpecVersion(md);
+  const hashChanged = live?.ac_hash !== newHash;
+  let newVer = curVer;
+  if (hashChanged && !opts.noBump) {
+    const proposed = bumpSpecVersion(curVer);
+    if (opts.bump === true || opts.yes) newVer = proposed;
+    else if (typeof opts.bump === "string") newVer = opts.bump;
+    else if (process.stdin.isTTY) {
+      process.stdout.write(`\n  Cambiaron los criterios (ac_hash ${C.dim(live?.ac_hash ?? "ninguno")} → ${C.b(newHash)}).\n`);
+      process.stdout.write(`    s = cambio ${C.b("material")}: subo spec_version a ${C.b(proposed)} y los repos con ${curVer || "la versión vieja"} se marcan ATRASADOS\n`);
+      process.stdout.write(`    n = cambio ${C.b("editorial")} (typo, redacción): se queda en ${curVer || "(sin versión)"}\n`);
+      const ans = await askOrCancel(`  ¿Subo spec_version a ${proposed}? (S/n) `);
+      if (!/^n/i.test(ans)) newVer = proposed;
+    } else {
+      // Sin TTY y sin --bump/--no-bump no hay quién decida, y decidir por nuestra cuenta
+      // sería inventar la respuesta a la única pregunta que este comando NO puede
+      // responder solo. Se deja como está, pero se DICE — un no-op silencioso acá
+      // termina en un spec_version que dejó de comunicar nada.
+      info(`cambiaron los criterios y spec_version se queda en ${curVer || "(sin versión)"}: no hay TTY para preguntarlo.`);
+      info(`  Si el cambio es material:  --bump    (${curVer || "v1"} → ${proposed}, marca atrasados a los repos)`);
+      info("  Si es editorial (typo):   --no-bump");
+    }
+  }
+  if (newVer && newVer !== curVer) md = setSpecVersion(md, newVer);
+
+  // ── Preview: qué cambia ALLÁ ARRIBA. Se muestra siempre, antes de escribir nada ──
+  // "(ninguno)" también del lado del "sin cambios": imprimir el `null` crudo hace dudar
+  // de si el comando se rompió, justo en el preview que la persona lee antes de aprobar.
+  const show = (v) => v ?? "(ninguno)";
+  const chg = (from, to) => (from === to ? `${show(to)}${C.dim("  (sin cambios)")}` : `${C.dim(show(from))} → ${C.b(show(to))}`);
+  process.stdout.write(`\n  ── ${id} · qué cambia en ${adapter.kind} ────────────\n`);
+  process.stdout.write(`  título:     ${chg(live?.title, title)}\n`);
+  process.stdout.write(`  criterios:  ${validation.criteria.length}\n`);
+  process.stdout.write(`  version:    ${chg(curVer, newVer)}\n`);
+  process.stdout.write(`  ac_hash:    ${chg(live?.ac_hash, newHash)}\n`);
+  process.stdout.write(`  fuente:     ${rel(file)}\n  ──────────────────────────────────────\n`);
+
+  if (opts.dryRun) { info("[dry-run] no se tocó el tracker."); return md; }
+  if (!opts.yes && process.stdin.isTTY) {
+    const ans = await askOrCancel(`  Esto PISA la US ${id} en ${adapter.kind}. ¿Guardo? (s/N) `);
+    if (!/^s|^y/i.test(ans)) { info("Cancelado — el tracker quedó como estaba."); return null; }
+  }
+  if (md !== readFileSync(file, "utf8")) writeFileSync(file, md);   // el bump también queda local
+
+  const r = await adapter.updateUS(id, { title, descriptionMarkdown: md, fields: fieldsFor(adapter, opts) });
+  ok(`${id} actualizada en ${adapter.kind}${r.url ? `  →  ${r.url}` : ""}`);
+
+  // Re-estampar el ac_hash local: si no, `dai check` marca atrasado por tu propia edición.
+  if (opts.noResync) { info("--no-resync: el implements.yaml quedó con el ac_hash viejo (dai check te lo va a marcar)."); return md; }
+  const target = discoverImplements(process.cwd()).find((f) => (f.implements || []).some((im) => im.id === id));
+  if (!target) { info(`sin implements.yaml para ${id} en este repo — no hay ac_hash local que resincronizar.`); return md; }
+  const prev = (target.implements.find((im) => im.id === id) || {}).ac_hash;
+  if (prev === newHash && !newVer) { ok(`ac_hash local ya estaba al día (${newHash}).`); return md; }
+  let txt = readFileSync(target.path, "utf8").replace(/^(\s*ac_hash:\s*).*$/m, `$1${newHash}`);
+  if (newVer) txt = txt.replace(/^(\s*version:\s*).*$/m, `$1${newVer}`);
+  writeFileSync(target.path, txt);
+  ok(`ac_hash re-estampado: ${prev} → ${newHash}${newVer && newVer !== curVer ? ` (${newVer})` : ""} en ${rel(target.path)}`);
+  if (prev !== newHash) warn("cambiaron los criterios: revisá que tu implementación los cubra, y corré tus tests.");
+  return md;
+}
+
+// El .md de trabajo de una US: explícito con --us, o el `us.md` del change que la implementa.
+function usFileFor(id, opts, { quiet = false } = {}) {
+  if (typeof opts.us === "string") return opts.us;
+  const target = discoverImplements(process.cwd()).find((f) => (f.implements || []).some((im) => im.id === id));
+  const guess = target ? join(dirname(target.path), "us.md") : null;
+  if (guess && existsSync(guess)) {
+    if (!quiet) info(`sin --us: uso ${rel(guess)} (el change que implementa ${id}).`);
+    return guess;
+  }
+  return null;
+}
+
+// ── edit-us: traer la US del tracker, editarla, validarla y guardarla ─────────
+//
+// Para el PO: la US vive en el tracker, no en un .md que alguien tiene que acordarse de
+// sincronizar. Este comando la BAJA, te la abre en tu editor, valida el formato cuando
+// guardás, te muestra qué cambia y recién ahí la sube. Si el formato no da, te deja
+// volver al editor en vez de tirarte el trabajo.
+async function cmdEditUs(id, opts = {}) {
+  if (!id) fail("uso: dai edit-us <ID> [--us <archivo.md>] [--strict] [--dry-run] [--yes]", 1);
+  if (!isValidKey(id)) fail(`key inválido: '${id}'. Sin espacios ni barras (ej.: ABC-482 o 86cxyz).`, 1);
+  loadDaiEnv();
+  const adapter = getAdapter(process.env);
+  if (typeof adapter.updateUS !== "function") fail(`el backend '${adapter.kind}' no soporta actualizar US.`, 1);
+
+  const live = await fetchLive(adapter, id);
+  if (!live) {
+    fail(`no encontré la US ${id} en ${adapter.kind}. ¿Es el key correcto?\n` +
+         `  Para CREARLA:  dai publish <us.md>   (edit-us edita una que ya existe)`, 2);
+  }
+
+  // Dónde se edita: el us.md del change si existe (así el dev y el PO tocan el MISMO
+  // archivo), si no `.dai/us/<ID>.md`, que es la convención del backend md.
+  const file = usFileFor(id, opts, { quiet: true }) ||
+    join(process.env.DAI_MD_US_DIR || join(".dai", "us"), `${id}.md`);
+
+  // El cuerpo que baja del tracker. Si ya hay un .md local con el MISMO ac_hash, se
+  // respeta el local: puede tener secciones del molde (contexto, fuera de scope) que el
+  // tracker no devuelve, y pisarlas con la versión de arriba sería perder trabajo.
+  let md = live.raw || null;
+  const localExists = existsSync(file);
+  const local = localExists ? readFileSync(file, "utf8") : null;
+  if (local && acHash(local) === live.ac_hash) {
+    md = local;
+    info(`${rel(file)} ya está al día con ${adapter.kind} (ac_hash ${live.ac_hash}) — edito el local, que tiene el molde completo.`);
+  } else if (md == null) {
+    fail(`el backend '${adapter.kind}' no devuelve el cuerpo de la US, así que no puedo traerla para editar.\n` +
+         "  Editá el .md a mano y empujalo con:  dai update-us " + id + " --us <archivo.md>", 1);
+  } else if (localExists && typeof opts.us === "string") {
+    // Pediste ESE archivo: es la fuente, punto. Bajarle la versión del tracker encima
+    // borraría justo lo que viniste a subir — es el camino que usa /grill-user-story,
+    // que escribe la US refinada al .md y después la empuja.
+    md = local;
+    info(`${rel(file)} es tu fuente (local ${acHash(local) || "sin criterios"} vs vivo ${live.ac_hash}) — no lo piso con el tracker.`);
+  } else if (localExists) {
+    warn(`${rel(file)} existe pero DIFIERE del tracker (local ${acHash(local) || "sin criterios"} vs vivo ${live.ac_hash}).`);
+    // Ante la duda gana lo LOCAL: es trabajo que alguien escribió y que el tracker no
+    // tiene. Pisarlo es la única de las dos opciones que destruye algo.
+    if (!opts.yes && process.stdin.isTTY) {
+      const ans = await askOrCancel("  ¿Lo piso con la versión del tracker? (s/N — 'n' edita el local tal cual) ");
+      if (!/^s|^y/i.test(ans)) { md = local; info("Edito el local, sin pisarlo."); }
+    } else {
+      md = local;
+      info(`edito el local sin pisarlo (${opts.yes ? "--yes" : "no interactivo"}). Para partir del tracker, borrá ${rel(file)} o pasá otro --us.`);
+    }
+  }
+
+  mkdirSync(dirname(file), { recursive: true });
+  if (md !== local) { writeFileSync(file, md); ok(`traje ${id} de ${adapter.kind} → ${rel(file)}`); }
+
+  // ── El ciclo editar → validar ──────────────────────────────────────────────
+  // Un formato inválido NO tira el trabajo: te devuelve al editor con los errores a la
+  // vista. Se sale con Ctrl+C, no perdiendo lo escrito.
+  for (;;) {
+    if (!opts.noEditor) await openEditor(file);
+    md = readFileSync(file, "utf8");
+    const v = validateUS(md);
+    if (v.ok || opts.noEditor || !process.stdin.isTTY) break;
+    process.stdout.write(`\n  ── formato de la US (${rel(file)}) ────────────\n`);
+    for (const l of renderValidation(v)) process.stdout.write(l + "\n");
+    const ans = await askOrCancel("\n  El formato no da. ¿Vuelvo a abrir el editor? (S/n — 'n' aborta sin tocar el tracker) ");
+    if (/^n/i.test(ans)) { info("Abortado — el tracker quedó como estaba; tu edición está en " + rel(file) + "."); return; }
+  }
+
+  await pushUS(id, md, { adapter, file, opts, live });
+}
+
+// Abre $VISUAL/$EDITOR sobre el archivo. Sin editor configurado no se impone `vi`: se
+// pide editar el archivo y volver — funciona igual en una terminal, en un IDE, o con el
+// archivo abierto en otra ventana.
+async function openEditor(file) {
+  const ed = process.env.VISUAL || process.env.EDITOR;
+  if (ed && process.stdin.isTTY) {
+    info(`abriendo ${rel(file)} en ${ed}…`);
+    try {
+      execFileSync(ed, [file], { stdio: "inherit", shell: process.platform === "win32" });
+      return;
+    } catch (e) {
+      warn(`no pude abrir '${ed}': ${String(e.message).split("\n")[0]}`);
+    }
+  }
+  if (!process.stdin.isTTY) return;
+  if (!ed) info("no hay $EDITOR ni $VISUAL configurados.");
+  await askOrCancel(`  Editá ${rel(file)} y presioná Enter cuando termines (Ctrl+C para abortar) `);
+}
+
+// ── update-us: empuja al tracker una US que ya escribiste ─────────────────────
+//
+// El inverso de `dai publish`: la US ya existe con su key, la refinaste implementando (un
+// criterio que apareció escribiendo el test) y el tracker quedó viejo. Sin esto había que
+// copiar y pegar a mano, que es justo lo que el método no quiere (Art. 10).
+async function cmdUpdateUs(id, opts = {}) {
+  if (!id) fail("uso: dai update-us <ID> [--us <archivo.md>] [--strict] [--no-resync] [--dry-run] [--yes]", 1);
+  if (!isValidKey(id)) fail(`key inválido: '${id}'. Sin espacios ni barras (ej.: ABC-482 o 86cxyz).`, 1);
+  loadDaiEnv();
+
+  const file = usFileFor(id, opts);
+  if (!file) {
+    fail(`falta --us <archivo.md> con la US (no encontré un us.md junto al implements.yaml de ${id}).\n` +
+         `  Si querés traerla del tracker y editarla ahí mismo:  dai edit-us ${id}`, 1);
+  }
+  if (!existsSync(file)) fail(`no existe el archivo '${file}'.`, 1);
+
+  const adapter = getAdapter(process.env);
+  if (typeof adapter.updateUS !== "function") fail(`el backend '${adapter.kind}' no soporta actualizar US.`, 1);
+  const live = await fetchLive(adapter, id);
+  if (!live && adapter.kind !== "md") {
+    fail(`no encontré la US ${id} en ${adapter.kind}. ¿Es el key correcto? Para CREARLA: dai publish ${rel(file)}`, 2);
+  }
+  await pushUS(id, readFileSync(file, "utf8"), { adapter, file, opts, live });
+}
+
 // ── done: cierra una US — vuelve a la base, actualiza y borra la branch local ──
 function cmdDone(opts) {
   const base = opts.base || "main";
@@ -409,7 +831,7 @@ function cmdDone(opts) {
 // ── pr: crea TU PROPIA PR/MR precargada desde el template + el link ────────────
 // (Distinto de dai-review, que revisa la PR de OTRO. Tu PR la creas y revisas tú.)
 async function cmdPr(opts) {
-  loadEnv();
+  loadDaiEnv();
   const remote = gitRemote(), branch = gitBranch(), commit = gitCommit();
   if (!remote) fail("no hay remoto git 'origin'. Configúralo para crear la PR.", 1);
   if (!branch || branch === "HEAD") fail("no estás en una branch.", 1);
@@ -447,7 +869,7 @@ async function cmdPr(opts) {
   for (const f of found) for (const im of f.implements || []) {
     if (!isPlaceholderId(im.id)) { entry = { f, im }; break; }
   }
-  if (!entry) fail("no encontré un implements.yaml con una US real. Ejecuta `dai link-us` primero.", 1);
+  if (!entry) fail("no hay una US linkeada (implements.yaml). Si este PR implementa una US, corré `dai link-us` primero. Si es un chore/tooling (sin US), creá la PR con tu forge: `glab mr create` / `gh pr create`.", 1);
   const { id, version, ac_hash } = entry.im;
 
   // 2. Estado de trazabilidad (dai check) contra la US viva.
@@ -470,7 +892,7 @@ async function cmdPr(opts) {
   const usUrl = usUrlFor(id, live?.url);
   if (!usUrl) {
     warn(`no sé la URL de ${id} en el tracker: la PR va a quedar sin link a la US.`);
-    warn(`configurá DAI_TRACKER_URL_TEMPLATE en el .env (p. ej. https://tu-tracker/browse/{id}).`);
+    warn(`configurá DAI_TRACKER_URL_TEMPLATE en el .env.dai (p. ej. https://tu-tracker/browse/{id}).`);
   }
   const body = composePrBody(readFileSync(tplPath, "utf8"), {
     id, version, ac_hash, status, usUrl, usTitle: live?.title, commits,
@@ -632,7 +1054,7 @@ async function cmdInstall(opts) {
 // dai (colisión → warn + skip). `dai sync` NO las toca: es solo de dai.
 function cmdInstallFrom(opts) {
   if (typeof opts.from !== "string" || !opts.from.trim())
-    fail("--from necesita una fuente: un git URL (github.com/org/skills[#ref]) o un path local", 2);
+    fail("--from necesita una fuente: un git URL (github.com/org/skills[#ref]), un paquete npm (npm:@scope/pkg) o un path local", 2);
   let want;
   try { want = parseAssistants(typeof opts.for === "string" ? opts.for : "all"); }
   catch (e) { fail(`--for ${e.message}`); }
@@ -651,6 +1073,33 @@ function cmdInstallFrom(opts) {
     try { git(args); }
     catch (e) { rmSync(tmp, { recursive: true, force: true }); fail(`no pude clonar la fuente: ${String(e.message).split("\n")[0]}`, 1); }
     root = tmp;
+  } else if (src.type === "npm") {
+    tmp = mkdtempSync(join(tmpdir(), "dai-skills-"));
+    info(`bajando el paquete npm ${src.location} …`);
+    try {
+      // `npm install` (no `npm pack`) en el temp. Dos decisiones a propósito:
+      // 1) install en vez de pack: los registries de GRUPO de GitLab devuelven una
+      //    `dist.tarball` malformada (el scope duplicado en el nombre) que `npm pack` sigue
+      //    literal y da 404; `npm install` —como `npx`— reconstruye la URL y resuelve.
+      // 2) copiamos el `.npmrc` del repo al temp y corremos con cwd=temp: así npm ve el
+      //    registry/scope privado (con `--prefix` npm NO lee el `.npmrc` del cwd y se va al
+      //    registry público). `--ignore-scripts`: no corremos scripts de un paquete de 3ros.
+      const repoNpmrc = join(process.cwd(), ".npmrc");
+      if (existsSync(repoNpmrc)) cpSync(repoNpmrc, join(tmp, ".npmrc"));
+      runNpmTool("npm", ["install", src.location,
+        "--no-save", "--no-package-lock", "--ignore-scripts", "--no-audit", "--no-fund"],
+        { cwd: tmp, stdio: ["ignore", "ignore", "pipe"] });
+      // El paquete queda en <tmp>/node_modules/<name>. name = spec sin la versión
+      // (@scope/pkg@1.2.3 → @scope/pkg; el `@` inicial del scope no cuenta).
+      let name = src.location; const at = name.lastIndexOf("@");
+      if (at > 0) name = name.slice(0, at);
+      root = join(tmp, "node_modules", name);
+      if (!existsSync(root)) throw new Error(`npm install no dejó '${name}' en node_modules`);
+    } catch (e) {
+      rmSync(tmp, { recursive: true, force: true });
+      const detail = String(e.stderr || e.stdout || e.message || "").split("\n").map((s) => s.trim()).filter(Boolean).slice(0, 3).join("\n         ");
+      fail(`no pude bajar el paquete npm '${src.location}':\n         ${detail || "npm install falló — revisá el spec, el registry y el .npmrc del repo"}`, 1);
+    }
   } else {
     root = src.location;
     if (!existsSync(root)) fail(`no existe la fuente: ${root}`, 2);
@@ -738,7 +1187,7 @@ async function cmdInit(repo, opts) {
   }
   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");
+  process.stdout.write(initBanner());
 
   // Preguntas primero (después cerramos readline para liberar stdin a los instaladores).
   let forOpt = typeof opts.for === "string" ? opts.for.toLowerCase() : null;
@@ -788,29 +1237,34 @@ async function cmdInit(repo, opts) {
   }
   writeFileSync(join(dai, "VERSION"), readFileSync(join(ROOT, "VERSION"), "utf8"));
   ok(".dai/         moldes (templates) + reglas (governance) del método");
+  info("              gate de CI opcional: cp .dai/templates/ci-dai-gate.yml .github/workflows/");
+
+  // Config de dai en SUS PROPIOS archivos, sin tocar el `.env`/`.env.example` del equipo:
+  // muchas orgs versionan el `.env` como política, así que dai lo deja en paz (solo lo lee,
+  // por compat) y pone lo suyo en `.env.dai` (ver ADR-0017). `.env.dai.example` se versiona
+  // como plantilla; `.env.dai` (gitignored) es donde cada dev completa token y datos propios.
+  const envBlock = envFor(pm);
 
-  // .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");
+  // .env.dai.example — plantilla VERSIONADA, mismas claves con valores VACÍOS (sin secretos).
+  const exPath = join(repo, ".env.dai.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"); }
+    const cur = readFileSync(exPath, "utf8"), merged = mergeEnv(cur, envBlock);
+    if (merged !== cur) { writeFileSync(exPath, merged); ok(".env.dai.example  claves de dai agregadas (aditivo)"); }
+    else ok(".env.dai.example  ya tenía la config de dai");
+  } else { writeFileSync(exPath, envBlock); ok(".env.dai.example  creado (plantilla versionada)"); }
 
-  // .env — aditivo: agrega las claves de dai que falten; si no existe, lo crea.
-  const envPath = join(repo, ".env"), envBlock = envFor(pm);
+  // .env.dai — el real de cada dev (gitignored): aditivo; si no existe, lo crea.
+  const envPath = join(repo, ".env.dai");
   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)"}`); }
+    if (merged !== cur) { writeFileSync(envPath, merged); ok(`.env.dai      claves de dai agregadas (aditivo, DAI_PM=${pm}${pm === "md" ? "" : " — completa el token"})`); }
+    else ok(".env.dai      ya tenía la config de dai");
+  } else { writeFileSync(envPath, envBlock); ok(`.env.dai      creado (no versionado), 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)"); }
+  if (gi.changed) { writeFileSync(giPath, gi.text.endsWith("\n") ? gi.text : gi.text + "\n"); ok(".gitignore    ajustado (skills/constitución versionadas; .env.dai 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"));
@@ -894,12 +1348,12 @@ async function cmdInit(repo, opts) {
   }
 
   // ── Próximos pasos ─────────────────────────────────────────────────────────
-  process.stdout.write("\n  ✔ Repo configurado. Próximos pasos:\n");
+  process.stdout.write("\n  " + C.y("✔") + " " + C.b("Repo configurado.") + " Próximos pasos:\n");
   process.stdout.write(pm === "md"
-    ? "    1. Crea tu primera US en .dai/us/<ID>.md (criterios bajo '## Criterios de aceptación')\n"
-    : `    1. Completa el token de ${pm} en .env, y verifica con: dai doctor\n`);
-  process.stdout.write("    2. dai link-us <ID>     → crea la branch + el link a la US\n");
-  process.stdout.write("    3. Implementa con test primero, después: dai check\n");
+    ? `    1. Crea tu primera US en ${C.cy(".dai/us/<ID>.md")} (criterios bajo '## Criterios de aceptación')\n`
+    : `    1. Copia ${C.cy(".env.dai.example")} → ${C.cy(".env.dai")} y completa el token de ${pm}; verifica con ${C.y("dai doctor")}\n`);
+  process.stdout.write(`    2. ${C.y("dai link-us <ID>")}     → crea la branch + el link a la US\n`);
+  process.stdout.write(`    3. Implementa con test primero, después: ${C.y("dai check")}\n`);
   process.stdout.write("    Guía paso a paso: https://github.com/dforce2055/dai/blob/main/docs/PROBAR.md\n\n");
 }
 
@@ -1031,7 +1485,7 @@ function cmdSync(repo, opts) {
     () => writeFileSync(giPath, gi.text.endsWith("\n") ? gi.text : gi.text + "\n"));
 
   if (dry) info("dry-run: nada escrito. Quitá --dry-run para aplicar.");
-  else { process.stdout.write("\n"); ok(`sync completo — .dai/ ahora en v${cliV}`); process.stdout.write("  (El .env y OpenSpec no se tocan: OpenSpec se actualiza aparte con `openspec`.)\n"); }
+  else { process.stdout.write("\n"); ok(`sync completo — .dai/ ahora en v${cliV}`); process.stdout.write("  (El .env.dai y OpenSpec no se tocan: OpenSpec se actualiza aparte con `openspec`.)\n"); }
 }
 
 // Imprime el estado de version-drift del scaffold (ADR-0010) con color + ícono.
@@ -1097,7 +1551,7 @@ function cmdUpgrade(opts) {
 
 // ── doctor: diagnóstico ───────────────────────────────────────────────────────
 function cmdDoctor() {
-  loadEnv();
+  loadDaiEnv();
   info(`dai doctor — versión v${readFileSync(join(ROOT, "VERSION"), "utf8").trim()}`);
 
   // Una skill sirve si está en el repo actual (la puso `dai init`) o global (la puso
@@ -1151,11 +1605,11 @@ function cmdDoctor() {
   const pm = process.env.DAI_PM || "md";
   ok(`DAI_PM=${pm}`);
   if (pm === "jira") {
-    if (!process.env.DAI_JIRA_BASE_URL) warn("falta DAI_JIRA_BASE_URL en el .env");
-    if (!process.env.DAI_JIRA_EMAIL) warn("falta DAI_JIRA_EMAIL en el .env");
+    if (!process.env.DAI_JIRA_BASE_URL) warn("falta DAI_JIRA_BASE_URL en .env.dai");
+    if (!process.env.DAI_JIRA_EMAIL) warn("falta DAI_JIRA_EMAIL en .env.dai");
     // Ojo: solo miramos que el token ESTÉ, no que sirva — uno vencido pasa este chequeo
     // y recién falla al publicar. Verificarlo de verdad es pegarle a la red.
-    if (!process.env.DAI_JIRA_TOKEN) warn("falta DAI_JIRA_TOKEN en el .env"); else ok("token de Jira presente (no verificado: eso lo dice `dai publish`)");
+    if (!process.env.DAI_JIRA_TOKEN) warn("falta DAI_JIRA_TOKEN en .env.dai"); else ok("token de Jira presente (no verificado: eso lo dice `dai publish`)");
     if (!process.env.DAI_JIRA_PROJECT) warn("DAI_JIRA_PROJECT vacío — solo hace falta para `dai publish` (crear issues)");
     else {
       try { ok(`proyecto=${assertProjectKey(process.env.DAI_JIRA_PROJECT)} (para dai publish)`); }
@@ -1173,7 +1627,7 @@ function cmdDoctor() {
     }
   }
   if (pm === "clickup") {
-    if (!process.env.DAI_CLICKUP_TOKEN) warn("falta DAI_CLICKUP_TOKEN en el .env"); else ok("token de ClickUp presente");
+    if (!process.env.DAI_CLICKUP_TOKEN) warn("falta DAI_CLICKUP_TOKEN en .env.dai"); else ok("token de ClickUp presente");
     process.env.DAI_CLICKUP_LIST_ID ? ok(`lista=${process.env.DAI_CLICKUP_LIST_ID} (para dai publish)`)
       : warn("DAI_CLICKUP_LIST_ID vacío — solo hace falta para `dai publish` (crear tareas)");
   }
@@ -1196,8 +1650,10 @@ switch (cmd) {
   case "ac-hash": cmdAcHash(pos[0]); break;
   case "ls":      cmdLs(opts); break;
   case "link-us": cmdLinkUs(pos[0], opts).catch((e) => fail(String(e.message))); break;
-  case "check":   cmdCheck().catch((e) => fail(String(e.message))); break;
-  case "stamp":   cmdStamp().catch((e) => fail(String(e.message))); break;
+  case "check":   (opts.ci ? cmdCheckCi(opts) : cmdCheck()).catch((e) => fail(String(e.message))); break;
+  case "stamp":   cmdStamp(pos, opts).catch((e) => fail(String(e.message))); break;
+  case "update-us": cmdUpdateUs(pos[0], opts).catch((e) => fail(String(e.message))); break;
+  case "edit-us": cmdEditUs(pos[0], opts).catch((e) => fail(String(e.message))); break;
   case "forge":   cmdForge(pos[0], pos[1], opts).catch((e) => fail(String(e.message))); break;
   case "publish": cmdPublish(pos[0], opts).catch((e) => fail(String(e.message))); break;
   case "pr":
@@ -1227,8 +1683,19 @@ switch (cmd) {
       "      [--field alias=valor]    campos propios que exige tu Jira (.dai/jira-fields.json); repetible\n" +
       "  link-us <KEY> [--us <md>]    crea branch + implements.yaml; sin --us trae la US del tracker (ADR-0004)\n" +
       "  link-us <KEY> --resync       re-estampa el ac_hash contra la US viva (tras un ⚠️ de check)\n" +
+      "  edit-us <KEY>                trae la US del tracker, la abrís en tu editor, valida el formato,\n" +
+      "                               muestra qué cambia y la guarda (para el PO)\n" +
+      "      [--no-editor]            no abre $EDITOR (para skills/scripts que ya escribieron el .md)\n" +
+      "      [--bump | --no-bump]     decide el spec_version sin preguntar (sin TTY no se toca y avisa)\n" +
+      "  update-us <KEY> [--us <md>]  empuja al tracker un .md que ya escribiste + re-estampa el ac_hash\n" +
+      "      [--dry-run] [--yes]      sin --yes muestra el diff y pide confirmación · [--no-resync]\n" +
+      "      [--strict]               las advertencias de formato también frenan · [--no-bump] no toca spec_version\n" +
       "  check                        compara vs la US viva → atrasado (ADR-0003)\n" +
-      "  stamp                        estampa la cobertura en el tracker (ADR-0005)\n" +
+      "  check --ci                   gate de CI: exige el link según branch-naming (chore/ y docs/ exentas)\n" +
+      "      [--branch b]             la branch a evaluar (en CI se detecta sola) · [--no-network]\n" +
+      "                               salidas: 0 pasa · 1 falta el link · 2 el QUÉ cambió\n" +
+      "  stamp [<ID>…] [--all]        estampa la cobertura en el tracker (ADR-0005)\n" +
+      "                               sin ID: la US de esta branch; si hay varias, pregunta\n" +
       "  done [--base main] [--force] cierra la US: vuelve a la base, actualiza y borra la branch local (si está mergeada)\n" +
       "  archive [<change>] [--skip-specs]   funde los delta specs del change en las specs canónicas y lo archiva (lo corre el aprobador en la PR)\n" +
       "  pr (alias mr) [--assignee u] [--base b] [--draft] [--yes]   crea TU PR/MR precargada (muestra + confirma)\n" +
@@ -1238,16 +1705,16 @@ switch (cmd) {
       "      Sin --yes no postea nada: muestra el preview y valida que cada hallazgo apunte al diff.\n\n" +
       "Instalación:\n" +
       "  skills install [--global | --local <repo>] [--force] [--dry-run] [--for <asistentes>]   instala las skills de dai (alias: `install`)\n" +
-      "  skills install --from <git-url|path>[#ref] [--for <asistentes>]   instala skills EXTERNAS (por-stack), convertidas para los 3 asistentes (ADR-0013)\n" +
+      "  skills install --from <git-url|npm:pkg|path>[#ref] [--for <asistentes>]   instala skills EXTERNAS (por-stack), convertidas para los 3 asistentes (ADR-0013)\n" +
       "  init [<repo>]                scaffolder interactivo del repo (asistente, gestor, OpenSpec)\n" +
       "       --for <asistentes>      claude|copilot|cursor (combinables con coma) · o both|all (default all)\n" +
       "                               ej: --for claude,cursor · --for copilot · --for all\n" +
       "       --pm md|jira|clickup · --openspec   (con flags salteas las preguntas)\n" +
-      "  sync [<repo>] [--dry-run] [--for <asistentes>]   refresca skills/constitución/templates a la versión del CLI (aditivo; no toca .env ni OpenSpec)\n" +
+      "  sync [<repo>] [--dry-run] [--for <asistentes>]   refresca skills/constitución/templates a la versión del CLI (aditivo; no toca .env.dai ni OpenSpec)\n" +
       "  upgrade [--check] [--dry-run]   (alias: update) actualiza el CLI global a la última (npm i -g …@latest) y avisa si el repo quedó atrasado (ADR-0012)\n" +
       "  docs <destino>               documentación conceptual → <destino>\n" +
       "  doctor                       diagnóstico del entorno\n\n" +
-      "  (config: .env — ver .env.example)\n"
+      "  (config: .env.dai — ver .env.dai.example)\n"
     );
     process.exit(cmd && cmd !== "help" ? 1 : 0);
 }