@dforce2055/dai 0.13.2 → 0.13.3

package/CHANGELOG.md

@@ -3,6 +3,55 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/). Versionado semver
 (ver `VERSION`).
 
+## [0.13.3] — 2026-09-02
+
+**Una PR de dai se abría diciendo, en el mismo párrafo, dos cosas que no encajaban: que el
+spec estaba "verificado con dai check: ✅ al día", y a continuación una explicación general
+del método. Tirando de ese hilo aparecieron dos bugs distintos, y los dos eran dai afirmando
+cosas que no le constaban.**
+
+### Arreglado
+- **El relleno del estado reescribía la prosa del template.** `dai pr` hacía un replace
+  **global** de `verificado con `dai check` ✅`, y esa frase estaba dos veces en el molde: en
+  el dato (`## 🔗 Implementa`) y en la prosa que explica el método. Así que a una oración
+  general —igual en todas las PRs— dai le insertaba el estado de *esta* PR, y quedaba
+  publicado: *"verificado con `dai check`: ✅ al día. Sin esto, el código no sabe a qué QUÉ
+  responde…"*. Ni doctrina ni dato. Ahora el relleno se acota a la sección; sin la sección
+  (un template ajeno con otra forma) cae al body entero, porque rellenar de más es
+  recuperable y publicar `ABC-###` no.
+- **`dai pr` decía "❓ sin US" cuando el tracker no contestaba** — dos líneas debajo del id de
+  la US que sí existe. `coverageStatus` colapsaba en un mismo `sin-us` dos cosas que no
+  significan lo mismo: *el tracker contestó y la US no está* y *no hubo respuesta* (sin red,
+  sin token, 5xx, certificado corporativo). Los adaptadores ya distinguían los dos casos
+  (`404 → null`, cualquier otro error → `throw`), y el gate de CI también con su try/catch
+  propio; lo que rompía la distinción era un `.catch(() => null)` en `dai pr`. Hay un estado
+  nuevo, **`sin-respuesta`** (`⚠️ no verificado`), y la PR dice *"no verificado (el tracker no
+  respondió)"*, que es lo único cierto ([#43](https://github.com/dforce2055/dai/issues/43)).
+- **`dai: fetch failed` era todo lo que se llegaba a leer.** Es el mensaje pelado de undici
+  cuando no hay red, el host no resuelve o el certificado no valida: no dice qué se estaba
+  consultando, ni contra qué, ni qué mirar — indistinguible de un bug de dai, el mismo modo de
+  falla que el push por SSH de la 0.13.1. Ahora el error nombra la US, el backend y el host, y
+  distingue red / credencial / error del tracker, con el próximo paso en cada caso.
+- **`dai check` ya no se detenía en la primera US** que no pudiera consultar: lo reporta, sigue
+  con las demás y sale ≠ 0. **`dai stamp`** explicita que no estampa un estado que no pudo
+  verificar — escribir en el tracker de todo el equipo no se deshace.
+
+### Cambiado
+- **El molde de PR adelgaza: la doctrina pasa a comentario HTML.** El encabezado tenía cuatro
+  bloques y un solo dato — la doctrina de los dos activos, una línea que repetía la de arriba
+  (*"este PR está atado a la US vía implements.yaml"*) y la instrucción de borrar la sección si
+  no hay US, que `dai pr` resuelve solo desde la 0.13.2. Nada de eso decía algo sobre *esa* PR,
+  y repetirlo a la vista en cada una entrena a saltear el principio del cuerpo, que es
+  justamente donde va la descripción. Sigue estando para quien edite el molde, invisible al
+  renderizar; y la doctrina vive donde se lee una vez y no quinientas: `docs/glosario.md`,
+  `docs/guias/dev.md`, `governance/ci-rules.md`. Los repos ya inicializados lo reciben con
+  `dai sync`.
+
+### Interno
+- **367 tests** (+9): los dos caminos de la consulta (la US que no está y la que no se pudo
+  consultar), el mensaje de error por tipo de falla, y que el relleno del estado no toque la
+  prosa que lo rodea.
+
 ## [0.13.2] — 2026-09-02
 
 **Una PR se publicaba con la descripción vacía y la lista de cambios diciendo "Cambio 1,
@@ -808,6 +857,7 @@ ClickUp y Jira Cloud.
 - Tests de las rutas de red (jira/clickup/forge) con `fetch` mockeado. Sin links rotos;
   `files` de npm sin tests ni secretos.
 
+[0.13.3]: https://github.com/dforce2055/dai/releases/tag/v0.13.3
 [0.13.2]: https://github.com/dforce2055/dai/releases/tag/v0.13.2
 [0.13.1]: https://github.com/dforce2055/dai/releases/tag/v0.13.1
 [0.13.0]: https://github.com/dforce2055/dai/releases/tag/v0.13.0

package/VERSION

@@ -1 +1 @@
-0.13.2
+0.13.3

package/cli/dai.mjs

@@ -22,7 +22,7 @@ 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 { loadDaiEnv } from "./lib/env.mjs";
-import { getAdapter, coverageStatus, statusLabel } from "./lib/pm-adapter.mjs";
+import { getAdapter, coverageStatus, statusLabel, fetchLiveUS } 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";
 import { trackerUrl } from "./lib/tracker-url.mjs";
@@ -332,13 +332,18 @@ async function cmdCheck() {
   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 { us: live, unreachable, reason } = await fetchLiveUS(adapter, im.id);
+    const status = coverageStatus(im.ac_hash, live?.ac_hash, { unreachable });
     if (status === "al-dia") process.stdout.write(`✅ ${im.id} al día (${im.version})\n`);
     else if (status === "atrasado") {
       process.stdout.write(`⚠️  ${im.id} ATRASADO: implementaste ${im.ac_hash}, la US viva es ${live.ac_hash}${live.spec_version ? ` (${live.spec_version})` : ""}\n`);
       atrasadas.push(im.id);
       worst = Math.max(worst, 1);
+    } else if (status === "sin-respuesta") {
+      // No es "no hay US": es "no pude preguntar". Antes moría acá con `fetch failed` y sin
+      // chequear las demás; ahora lo dice, sigue, y sale ≠ 0 porque no pudo verificar nada.
+      process.stdout.write(`⚠️  ${reason}\n`);
+      worst = Math.max(worst, 2);
     } else {
       process.stdout.write(`❓ ${im.id}: no encontré la US (backend ${adapter.kind}). ¿Falta el .md o el token?\n`);
       worst = Math.max(worst, 2);
@@ -395,7 +400,11 @@ async function cmdStamp(ids = [], opts = {}) {
   }
 
   for (const r of targets) {
-    const live = await adapter.fetchUS(r.id);
+    // Estampar es ESCRIBIR en el tracker de todo el equipo, y no se deshace: si no se pudo
+    // verificar el estado, no se estampa. (Hoy ya frenaba, por la excepción sin atrapar; acá
+    // queda explícito, con el motivo, y cubierto por un test.)
+    const { us: live, unreachable, reason } = await fetchLiveUS(adapter, r.id);
+    if (unreachable) fail(`${reason}\n  No estampo un estado que no pude verificar.`, 2);
     const status = coverageStatus(r.ac_hash, live?.ac_hash);
     const record = {
       repo: r.repo, change: r.change, version: r.version, ac_hash: r.ac_hash, status,
@@ -960,8 +969,14 @@ async function cmdPr(opts) {
 
   // 2. Estado de trazabilidad (dai check) contra la US viva.
   const adapter = getAdapter(process.env);
-  const live = id ? await Promise.resolve(adapter.fetchUS(id)).catch(() => null) : null;
-  const status = id ? coverageStatus(ac_hash, live?.ac_hash) : null;
+  // El `.catch(() => null)` que había acá convertía "el tracker no contestó" en "no hay US",
+  // y esa afirmación se PUBLICABA en el cuerpo de la PR, al lado del id de la US que sí está.
+  const { us: live, unreachable, reason } = await fetchLiveUS(adapter, id);
+  if (unreachable) {
+    warn(reason);
+    warn("la PR va a decir que no se pudo verificar contra el tracker — no que no hay US.");
+  }
+  const status = id ? coverageStatus(ac_hash, live?.ac_hash, { unreachable }) : null;
   if (status === "atrasado") {
     warn(`la US ${id} está ATRASADA respecto de tu implementación (${ac_hash} ≠ ${live?.ac_hash}).`);
     warn(`resincroniza antes de abrir la PR:  dai link-us ${id} --resync`);

package/cli/lib/pm-adapter.mjs

@@ -21,19 +21,36 @@
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { parseUS, renderCoverage } from "./us.mjs";
+import { parseUS, renderCoverage, explainFetchError } from "./us.mjs";
 import { slugify } from "./link-us.mjs";
 import { jiraAdapter } from "./pm-jira.mjs";
 import { clickupAdapter } from "./pm-clickup.mjs";
 
 // Re-export para compatibilidad (tests y CLI importan estos desde acá).
-export { parseUS, coverageStatus, statusLabel, renderCoverage } from "./us.mjs";
+export { parseUS, coverageStatus, statusLabel, renderCoverage, explainFetchError } from "./us.mjs";
+
+// Consulta la US preservando la diferencia entre "no existe" y "no pude preguntar". Los
+// adaptadores ya la hacen —404 → null, cualquier otro error → throw— pero se perdía en cada
+// caller: `dai pr` la borraba con un `.catch(() => null)` y publicaba "sin US" en la PR, y
+// los demás morían con el `fetch failed` pelado de undici. El gate de CI era el único que la
+// respetaba, con su try/catch propio; esto es ese criterio, compartido.
+//
+//   → { us, unreachable, reason }   ·  unreachable: no hubo respuesta, no sabemos nada
+export async function fetchLiveUS(adapter, id) {
+  if (!id) return { us: null, unreachable: false, reason: null };
+  try {
+    return { us: await adapter.fetchUS(id), unreachable: false, reason: null };
+  } catch (e) {
+    return { us: null, unreachable: true, reason: explainFetchError(e, { kind: adapter.kind, endpoint: adapter.endpoint, id }) };
+  }
+}
 
 // ── backend md (local, offline) ───────────────────────────────────────────────
 function mdAdapter(env) {
   const dir = env.DAI_MD_US_DIR || ".dai/us";
   return {
     kind: "md",
+    endpoint: dir,
     fetchUS(id) {
       const p = join(dir, `${id}.md`);
       if (!existsSync(p)) return null;

package/cli/lib/pm-clickup.mjs

@@ -25,6 +25,7 @@ export function clickupAdapter(env) {
   if (!env.DAI_CLICKUP_TOKEN) throw new Error("falta DAI_CLICKUP_TOKEN en el .env.dai (backend clickup).");
   return {
     kind: "clickup",
+    endpoint: "api.clickup.com",
     async fetchUS(id) {
       const res = await fetch(clickupTaskUrl(id), { headers: clickupAuthHeaders(env) });
       if (res.status === 404) return null;

package/cli/lib/pm-jira.mjs

@@ -139,6 +139,7 @@ export function jiraAdapter(env) {
   if (!base) throw new Error("falta DAI_JIRA_BASE_URL en el .env.dai (backend jira).");
   return {
     kind: "jira",
+    endpoint: trim(base),
     async fetchUS(id) {
       const res = await daiFetch(jiraIssueUrl(base, id), { headers: jiraAuthHeaders(env) });
       if (res.status === 404) return null;

package/cli/lib/pr.mjs

@@ -2,7 +2,12 @@
 // Parte pura y testeable: rellena el template con los datos del link + git + check.
 // Los efectos (git push, gh/glab create) viven en dai.mjs.
 
-const EMOJI = { "al-dia": "✅ al día", atrasado: "⚠️ atrasado", "sin-us": "❓ sin US" };
+// Más explícito que el label del CLI a propósito: esto queda PUBLICADO en la PR, donde
+// quien lee no tiene el contexto de la corrida que la creó.
+const EMOJI = {
+  "al-dia": "✅ al día", atrasado: "⚠️ atrasado", "sin-us": "❓ sin US",
+  "sin-respuesta": "⚠️ no verificado (el tracker no respondió)",
+};
 
 // Las secciones que dai se compromete a entregar llenas. Si alguna sale con el molde
 // del template, la PR se publica vacía y el review no tiene qué mirar (era el bug:
@@ -115,12 +120,21 @@ export function composePrBody(template, d) {
   return upsertLinksBlock(b, d);
 }
 
+// Los placeholders se rellenan DENTRO de la sección, no en todo el body: la misma frase
+// ("verificado con `dai check` ✅") aparecía en la prosa que explica el método, así que un
+// replace global le metía el estado de ESTA PR a una oración general y quedaba
+// "verificado con dai check: ✅ al día. Sin esto, el código no sabe…". dai reescribiendo
+// la prosa de otro es justo lo que el bloque de links ya evitaba con sus marcadores.
+// Sin la sección (un template ajeno con otra forma) se cae al body entero: rellenar de más
+// es recuperable, no rellenar deja la PR con `ABC-###` publicado.
 function fillUsHeader(template, d) {
-  let b = template;
-  b = b.replace(/`ABC-###`/g, `\`${d.id}\``);
-  b = b.replace(/@ `vX`/g, `@ \`${d.version}\``);
-  b = b.replace(/`<hash>`/g, `\`${d.ac_hash}\``);
-  return b.replace(/verificado con `dai check` ✅/g, `verificado con \`dai check\`: ${EMOJI[d.status] || d.status}`);
+  const fill = (t) => t
+    .replace(/`ABC-###`/g, `\`${d.id}\``)
+    .replace(/@ `vX`/g, `@ \`${d.version}\``)
+    .replace(/`<hash>`/g, `\`${d.ac_hash}\``)
+    .replace(/verificado con `dai check` ✅/g, `verificado con \`dai check\`: ${EMOJI[d.status] || d.status}`);
+  const sec = sectionBody(template, "🔗 Implementa");
+  return sec == null ? fill(template) : replaceSection(template, "🔗 Implementa", fill(sec).trim());
 }
 
 // PR de una branch exenta (chore/, docs/, release/…): no implementa una US y no se le

package/cli/lib/us.mjs

@@ -12,12 +12,22 @@ export function parseUS(raw) {
 }
 
 // Compara el hash estampado (implements.yaml) con el hash vivo de la US.
-export function coverageStatus(stampedHash, liveHash) {
+//
+// `sin-us` y `sin-respuesta` NO son lo mismo, y confundirlos es caro: el primero es una
+// RESPUESTA del tracker (preguntamos y la US no está), el segundo es la AUSENCIA de
+// respuesta (sin red, sin token, 5xx, certificado corporativo). Colapsados en un mismo
+// `null`, dai terminaba AFIRMANDO que no había US cuando lo único cierto era que no había
+// podido preguntar — y eso se publicaba en el cuerpo de una PR, al lado del id de la US.
+export function coverageStatus(stampedHash, liveHash, { unreachable = false } = {}) {
+  if (unreachable) return "sin-respuesta";
   if (liveHash == null) return "sin-us";
   return stampedHash === liveHash ? "al-dia" : "atrasado";
 }
 
-const STATUS_LABEL = { "al-dia": "✅ al día", atrasado: "⚠️ atrasado", "sin-us": "❓ sin US" };
+const STATUS_LABEL = {
+  "al-dia": "✅ al día", atrasado: "⚠️ atrasado",
+  "sin-us": "❓ sin US", "sin-respuesta": "⚠️ no verificado",
+};
 export const statusLabel = (s) => STATUS_LABEL[s] || s;
 
 // Render de la cobertura como markdown (lo que un backend "estampa").
@@ -34,3 +44,25 @@ export function renderCoverage(id, r) {
   if (r.commitUrl) lines.push(`- commit: ${r.commit} → ${r.commitUrl}  (ancla durable)`);
   return lines.join("\n") + "\n";
 }
+
+// `fetch failed` es TODO lo que dice undici cuando no hay red, el host no resuelve, el DNS
+// se cayó o el certificado no valida. Sin contexto es indistinguible de un bug de dai: el
+// dev lee "dai: fetch failed" y no sabe ni qué se estaba consultando. Es el mismo modo de
+// falla que el push por SSH de la 0.13.1 — el dato que resuelve el problema existe, y no
+// llega. Acá se le pone alrededor qué, contra qué, y qué mirar.
+export function explainFetchError(err, { kind, endpoint, id } = {}) {
+  const raw = String(err?.message ?? err ?? "").split("\n")[0] || "error desconocido";
+  const donde = [kind, endpoint].filter(Boolean).join(" · ");
+  const cabeza = `no pude consultar ${id ? `la US ${id}` : "el tracker"}${donde ? ` en ${donde}` : ""}: ${raw}`;
+  if (/fetch failed|ENOTFOUND|ECONNREFUSED|EAI_AGAIN|ETIMEDOUT|ECONNRESET|certificate|self.signed/i.test(raw)) {
+    return `${cabeza}\n  No llegó a haber respuesta. Revisá la red y el host del backend; si estás detrás de un\n` +
+           `  proxy corporativo, declará la CA con NODE_EXTRA_CA_CERTS (nunca NODE_TLS_REJECT_UNAUTHORIZED=0).\n` +
+           `  Diagnóstico:  dai doctor`;
+  }
+  if (/\b40[13]\b|unauthorized|forbidden/i.test(raw)) {
+    return `${cabeza}\n  El tracker rechazó las credenciales: revisá el token del .env.dai (¿venció?) y sus permisos.\n` +
+           `  Diagnóstico:  dai doctor`;
+  }
+  if (/\b5\d\d\b/.test(raw)) return `${cabeza}\n  El error es del tracker, no tuyo: probá de nuevo en un rato.`;
+  return cabeza;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforce2055/dai",
-  "version": "0.13.2",
+  "version": "0.13.3",
   "description": "Metodología de desarrollo asistido por IA — CLI de acciones deterministas (trazabilidad QUÉ↔CÓMO).",
   "repository": { "type": "git", "url": "git+https://github.com/dforce2055/dai.git" },
   "homepage": "https://dforce2055.github.io/dai/",

package/templates/pull-request.md

@@ -5,19 +5,23 @@
   Lo puede pre-llenar `dai`/una skill a partir del implements.yaml y el diff.
 -->
 
-> **Un PR en dai entrega dos activos, y el review cubre los dos:**
-> 1. **La implementación** — el código que resuelve la US.
-> 2. **El spec trazable** — el `implements.yaml` con el link a la US y el `@version`
->    (`ac_hash`) verificado con `dai check` ✅. Sin esto, el código no sabe *a qué QUÉ*
->    responde, y el CI bloquea el PR (ver `governance/ci-rules.md`).
-
 ## 🔗 Implementa
 
 - **US:** `ABC-###` @ `vX`  ·  ac_hash: `<hash>`  ·  verificado con `dai check` ✅
-- **Link:** este PR está atado a la US vía `implements.yaml`.
 
-> Si este PR no implementa una US (chore/fix sin ticket), borra esta sección y
-> aclara el motivo — no se le exige link.
+<!--
+  Un PR en dai entrega DOS activos, y el review cubre los dos: la implementación (el código
+  que resuelve la US) y el spec trazable (el `implements.yaml` con el link a la US y el
+  `@version`/`ac_hash` verificado). Sin el link, el código no sabe a qué QUÉ responde y el
+  CI bloquea el PR — ver `governance/ci-rules.md`.
+
+  ¿Chore o fix sin ticket? No hay nada que borrar: `dai pr` lo detecta por el nombre de la
+  branch y escribe "Sin US" con el motivo. No se le exige link.
+
+  Esto es un comentario a propósito: es doctrina del método, igual en las 500 PRs del repo.
+  Repetirla a la vista en cada una entrena a saltear el principio del cuerpo, que es
+  justamente donde va la descripción.
+-->
 
 ## Descripción