@dforce2055/dai 0.8.1 → 0.8.2

package/.env.example

@@ -6,8 +6,11 @@
 # md | jira | clickup
 DAI_PM=md
 
-# Plantilla del link al ticket (para `dai ls` / stamp). {id} se reemplaza.
-DAI_TRACKER_URL_TEMPLATE=https://jira.miempresa.com/browse/{id}
+# OPCIONAL. Plantilla del link al ticket (`dai ls`, `dai pr`, stamp). {id} se reemplaza.
+# Con DAI_PM=jira o =clickup, dai ya deduce el link solo: esto es un OVERRIDE, y solo
+# hace falta si tu tracker vive en otra URL (p. ej. un Jira Server con path propio).
+# Si dai no puede saber el link, avisa y deja la PR sin él — nunca escribe el id pelado.
+# DAI_TRACKER_URL_TEMPLATE=https://jira.miempresa.com/browse/{id}
 
 # ── Backend md (local, offline) ──────────────────────────────────────────────
 # Carpeta donde viven las US como <ID>.md (p. ej. ABC-482.md).

package/CHANGELOG.md

@@ -3,6 +3,46 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/). Versionado semver
 (ver `VERSION`).
 
+## [0.8.2] — 2026-07-17
+
+**Dos agujeros que destapó el uso real, y que tienen la misma forma: dai hacía algo
+hacia afuera sin que un humano lo viera, o dejaba que otro le pisara lo que había
+escrito. El [Art. 5](docs/MANIFIESTO.md#art-5) no se cumple solo con no clickear
+Approve.**
+
+### Arreglado
+- **`dai-review` posteaba el comentario sin mostrártelo.** La skill componía el review y
+  lo publicaba de una: el paso 6 decía *"Postear"* y no había gate. Y el comentario sale
+  con **tu token y tu nombre** (`GITHUB_TOKEN`/`GITLAB_TOKEN` son tuyos), así que en la
+  PR de un compañero figura como si lo hubieras escrito vos. El corte estaba puesto en el
+  lugar equivocado: no aprobar sin humano estaba bien, pero publicar un juicio sobre el
+  código de otro, firmado por alguien que no lo leyó, es el mismo problema con otro
+  disfraz. Ahora la skill **muestra el comentario entero y espera un OK explícito** en
+  ese turno; sin "sí", no se postea. Es el tercer corte duro de la skill.
+- **`dai pr` escribía el id de la US disfrazado de link.** Sin `DAI_TRACKER_URL_TEMPLATE`,
+  `trackerUrl(id)` devolvía el **id pelado**; como un string es truthy, `composePrBody` lo
+  escribía igual y la PR quedaba con `- US: 86abc123` en vez de un enlace, sin un solo
+  aviso. Ahora la URL se resuelve por una cadena explícita —template > URL canónica del
+  tracker > derivada del backend > `null`— y **si dai no la sabe, avisa y omite la línea
+  en vez de mentir** (`lib/tracker-url.mjs`).
+- **El bloque de enlaces de `dai pr` no sobrevivía a un edit.** Iba marcado con un
+  comentario suelto, así que cualquier agente que reescribiera *"Enlaces relacionados"*
+  se lo llevaba puesto sin dejar rastro — pasó en PRs reales. Y el propio template lo
+  invitaba: su hint pedía *"US en el tracker, commit ancla, docs, issues"*, o sea justo la
+  sección que `dai pr` acababa de llenar. dai se peleaba consigo mismo y ganaba el que
+  corría último. Ahora el bloque va **delimitado** (`<!-- dai:links:start … end -->`),
+  se **regenera de forma idempotente**, preserva lo que el humano sumó abajo, y el hint
+  del template pide solo lo que dai **no** sabe (docs, issues, PRs relacionadas).
+
+### Cambiado
+- **dai deduce el link al tracker solo.** Con `DAI_PM=jira` o `=clickup` ya no hace falta
+  `DAI_TRACKER_URL_TEMPLATE`: se deriva de la config (`/browse/<KEY>` y
+  `/t/<id>`), y `fetchUS` ahora devuelve la **URL canónica** del tracker — en ClickUp, la
+  que trae el `team_id`, que no se puede deducir del id. La variable queda como
+  **override** para trackers con URL propia. `dai init` dejó de scaffoldearla: era
+  contraproducente, porque el template gana sobre la canónica y le tapaba el `team_id`.
+  Los `.env` que ya la tienen siguen andando igual (el override sigue ganando).
+
 ## [0.8.1] — 2026-07-16
 
 **Primera prueba real en Windows con analistas y devs de una empresa: el ciclo completo
@@ -326,6 +366,8 @@ 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.8.2]: https://github.com/dforce2055/dai/releases/tag/v0.8.2
+[0.8.1]: https://github.com/dforce2055/dai/releases/tag/v0.8.1
 [0.8.0]: https://github.com/dforce2055/dai/releases/tag/v0.8.0
 [0.7.0]: https://github.com/dforce2055/dai/releases/tag/v0.7.0
 [0.6.0]: https://github.com/dforce2055/dai/releases/tag/v0.6.0

package/VERSION

@@ -1 +1 @@
-0.8.1
+0.8.2

package/cli/dai.mjs

@@ -25,6 +25,7 @@ import { loadEnv } 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 } from "./lib/forge-api.mjs";
+import { trackerUrl } from "./lib/tracker-url.mjs";
 import { composePrBody, prTitle, forgeTool } from "./lib/pr.mjs";
 import { dirsEqual } from "./lib/fsutil.mjs";
 import { parseFlags, parseAssistants, isAssistantToken, asList } from "./lib/args.mjs";
@@ -66,10 +67,9 @@ function runNpmTool(name, args, opts = {}) {
   const win = process.platform === "win32";
   return execFileSync(win ? `${name}.cmd` : name, args, { shell: win, ...opts });
 }
-function trackerUrl(id) {
-  const tpl = process.env.DAI_TRACKER_URL_TEMPLATE;
-  return tpl ? tpl.replace("{id}", id) : id;
-}
+// La URL de la US: template > canónica del tracker > derivada del backend > null.
+// Nunca el id pelado: ver el porqué en lib/tracker-url.mjs.
+const usUrlFor = (id, liveUrl = null) => trackerUrl(id, { env: process.env, liveUrl });
 
 // ── ac-hash ─────────────────────────────────────────────────────────────────
 function cmdAcHash(arg) {
@@ -88,7 +88,7 @@ function cmdLs(opts) {
     for (const im of f.implements || []) {
       if (isPlaceholderId(im.id)) continue;   // saltea plantillas sin completar
       rows.push({ change: f.change, repo: f.repo, id: im.id, version: im.version,
-                  ac_hash: im.ac_hash, link: trackerUrl(im.id) });
+                  ac_hash: im.ac_hash, link: usUrlFor(im.id) });
     }
   }
   if (opts.json) { process.stdout.write(JSON.stringify(rows, null, 2) + "\n"); return; }
@@ -394,8 +394,14 @@ async function cmdPr(opts) {
   // Commits de la branch (para precargar "Cambios realizados").
   let commits = [];
   try { commits = git(["log", `${base}..HEAD`, "--pretty=%s"]).split("\n").filter(Boolean); } catch { /* base local ausente */ }
+  // La canónica del tracker (live.url) gana sobre la derivada; el template gana sobre todo.
+  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}).`);
+  }
   const body = composePrBody(readFileSync(tplPath, "utf8"), {
-    id, version, ac_hash, status, usUrl: trackerUrl(id), usTitle: live?.title, commits,
+    id, version, ac_hash, status, usUrl, usTitle: live?.title, commits,
     branch, branchUrl: branchUrl(remote, branch), commit, commitUrl: commitUrl(remote, commit),
   });
   const title = prTitle(opts, id, live?.title);

package/cli/lib/bootstrap.mjs

@@ -92,10 +92,15 @@ export function skillToCursor(md) {
 }
 
 // Contenido del .env según el backend de PM elegido (tokens vacíos, a completar).
+//
+// Sin DAI_TRACKER_URL_TEMPLATE a propósito: con jira/clickup, dai deduce el link solo
+// (lib/tracker-url.mjs). Scaffoldearlo era peor que no ponerlo — el template GANA sobre
+// 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";
   if (pm === "clickup") {
-    return head + "DAI_PM=clickup\nDAI_CLICKUP_TOKEN=\nDAI_CLICKUP_LIST_ID=\nDAI_TRACKER_URL_TEMPLATE=https://app.clickup.com/t/{id}\n";
+    return head + "DAI_PM=clickup\nDAI_CLICKUP_TOKEN=\nDAI_CLICKUP_LIST_ID=\n";
   }
   if (pm === "jira") {
     return head +
@@ -107,8 +112,7 @@ export function envFor(pm) {
       "DAI_JIRA_PROJECT=\n" +
       "DAI_JIRA_ISSUETYPE=Story\n" +
       "# Campos propios que tu Jira exige al crear. Si el archivo no existe, se ignora.\n" +
-      "DAI_JIRA_FIELDS_FILE=.dai/jira-fields.json\n" +
-      "DAI_TRACKER_URL_TEMPLATE=\n";
+      "DAI_JIRA_FIELDS_FILE=.dai/jira-fields.json\n";
   }
   return head + "DAI_PM=md\nDAI_MD_US_DIR=.dai/us\n";
 }

package/cli/lib/pm-adapter.mjs

@@ -7,9 +7,12 @@
 //   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 } | null
+//   fetchUS(id)          → { id, title, spec_version, ac_hash, url } | null
 //   stamp(id, record)    → destino donde quedó la cobertura
 //   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.
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";

package/cli/lib/pm-clickup.mjs

@@ -29,7 +29,9 @@ export function clickupAdapter(env) {
       const res = await fetch(clickupTaskUrl(id), { headers: clickupAuthHeaders(env) });
       if (res.status === 404) return null;
       if (!res.ok) throw new Error(`clickup ${res.status}: ${await res.text()}`);
-      return { id, ...parseUS(clickupTaskToText(await res.json())) };
+      const j = await res.json();
+      // `url` es la canónica (/t/<team_id>/<id>): la sabe ClickUp, no la deducimos.
+      return { id, ...parseUS(clickupTaskToText(j)), url: j.url || null };
     },
     async stamp(id, record) {
       const res = await fetch(clickupCommentUrl(id), {

package/cli/lib/pm-jira.mjs

@@ -143,7 +143,7 @@ export function jiraAdapter(env) {
       const res = await daiFetch(jiraIssueUrl(base, id), { headers: jiraAuthHeaders(env) });
       if (res.status === 404) return null;
       if (!res.ok) throw new Error(`jira ${res.status}: ${await res.text()}`);
-      return { id, ...parseUS(jiraIssueToText(await res.json())) };
+      return { id, ...parseUS(jiraIssueToText(await res.json())), url: `${trim(base)}/browse/${id}` };
     },
     async stamp(id, record) {
       const res = await daiFetch(jiraCommentUrl(base, id), {

package/cli/lib/pr.mjs

@@ -29,15 +29,44 @@ export function composePrBody(template, d) {
   if (d.commits && d.commits.length) {
     b = replaceSection(b, "Cambios realizados", d.commits.map((c) => `- [x] ${c}`).join("\n"));
   }
-  // Bloque de enlaces (lo agrega dai; el humano completa el resto del template).
-  const links = ["", "<!-- Enlaces precargados por `dai pr` -->"];
-  if (d.usUrl) links.push(`- US: ${d.usUrl}`);
+  return upsertLinksBlock(b, d);
+}
+
+// ── Bloque de enlaces ────────────────────────────────────────────────────────
+// Delimitado y regenerable a propósito. Con el comentario suelto de antes, cualquier
+// agente que reescribiera "Enlaces relacionados" se lo llevaba puesto sin dejar rastro
+// (pasó en PRs reales). Con marcadores, el bloque se detecta, se preserva y se
+// regenera — y quien edite el body ve que es de dai y que se pisa solo.
+export const LINKS_START = "<!-- dai:links:start · generado por `dai pr` — no editar a mano -->";
+export const LINKS_END = "<!-- dai:links:end -->";
+
+// Los links que dai sabe. Sin URL no inventa la línea: prefiere no decir nada.
+export function renderLinks(d) {
+  const links = [LINKS_START];
+  if (d.usUrl) links.push(`- US \`${d.id}\`: ${d.usUrl}`);
   if (d.branchUrl) links.push(`- branch \`${d.branch}\`: ${d.branchUrl}`);
   if (d.commitUrl) links.push(`- commit \`${(d.commit || "").slice(0, 8)}\`: ${d.commitUrl}`);
-  return b.replace(/(##\s*Enlaces relacionados\s*\n)(<!--[\s\S]*?-->)?/i,
-    (m, h) => `${h}${links.join("\n")}\n`) === b
-    ? b + "\n" + links.join("\n") + "\n"   // si no había sección Enlaces, apéndela
-    : b.replace(/(##\s*Enlaces relacionados\s*\n)(<!--[\s\S]*?-->)?/i, (m, h) => `${h}${links.join("\n")}\n`);
+  links.push(LINKS_END);
+  return links.join("\n");
+}
+
+// Inserta o reemplaza el bloque de dai. Idempotente: correrlo N veces da lo mismo.
+export function upsertLinksBlock(body, d) {
+  const block = renderLinks(d);
+  // 1. ¿Ya está el bloque delimitado? Se reemplaza entero (regenerar, no duplicar).
+  const delimited = /<!--\s*dai:links:start[\s\S]*?dai:links:end\s*-->/i;
+  if (delimited.test(body)) return body.replace(delimited, block);
+  // 2. ¿Está la sección del template? El bloque va debajo del heading, PRESERVANDO el
+  //    hint HTML si lo hay: es la guía para quien edite (y es invisible al renderizar).
+  //    dai suma, no borra — borrar el texto de otro es justo lo que estamos arreglando.
+  //    (el `\s*` tolera la línea en blanco entre el heading y el hint; como solo matchea
+  //     espacios, no puede saltar a la sección siguiente para buscarse un comentario)
+  const heading = /(^|\n)(##[^\n]*Enlaces relacionados[^\n]*\n)(\s*<!--[\s\S]*?-->[ \t]*\n)?/i;
+  if (heading.test(body)) {
+    return body.replace(heading, (m, pre, h, hint) => `${pre}${h}${hint || ""}\n${block}\n`);
+  }
+  // 3. Ni bloque ni sección: se apéndea con su propio heading.
+  return `${body.replace(/\s*$/, "")}\n\n## Enlaces relacionados\n\n${block}\n`;
 }
 
 // Título del PR: el pasado a mano, o "<ID>: <título de la US>", o solo el ID.

package/cli/lib/tracker-url.mjs

@@ -0,0 +1,36 @@
+// dai · la URL de la US en el tracker. Puro, sync, sin red (ADR-0007: config por .env).
+//
+// Cadena de resolución, del más específico al más general:
+//   1. DAI_TRACKER_URL_TEMPLATE — override explícito del usuario: siempre gana.
+//   2. La URL que devolvió el tracker en `fetchUS` — la canónica (ClickUp la trae con
+//      el team_id; la derivada no puede saberlo). Solo existe si hubo red.
+//   3. Derivada del backend + su config — determinística y offline.
+//   4. `null` — dai NO sabe la URL.
+//
+// El paso 4 es el que importa. Antes devolvíamos el `id` pelado, y como un string es
+// truthy, quien consumía esto lo escribía igual — un id disfrazado de enlace, sin un
+// solo aviso. Preferimos no decir nada antes que mentir: quien llama decide si omite
+// la línea o avisa.
+
+// URL web de la US deducida del backend, sin salir a la red.
+export function deriveTrackerUrl(id, env = {}) {
+  if (!id) return null;
+  const kind = String(env.DAI_PM || "md").toLowerCase();
+  if (kind === "clickup") {
+    // /t/<id> redirige a la canónica /t/<team_id>/<id>. Sin token no sabemos el team.
+    return `https://app.clickup.com/t/${encodeURIComponent(id)}`;
+  }
+  if (kind === "jira") {
+    const base = String(env.DAI_JIRA_BASE_URL || "").replace(/\/+$/, "");
+    return base ? `${base}/browse/${encodeURIComponent(id)}` : null;
+  }
+  return null;   // md: la US es un archivo local, no tiene URL web
+}
+
+// La URL final, o null si no hay forma de saberla. `liveUrl` es la que trajo fetchUS.
+export function trackerUrl(id, { env = {}, liveUrl = null } = {}) {
+  if (!id) return null;
+  const tpl = env.DAI_TRACKER_URL_TEMPLATE;
+  if (tpl) return String(tpl).replace(/\{id\}/g, id);
+  return liveUrl || deriveTrackerUrl(id, env);
+}

package/docs/PROBAR.md

@@ -65,8 +65,9 @@ Si esto anda, el flujo está bien. Pasa al tracker real.
 cat > .env <<'EOF'
 DAI_PM=clickup
 DAI_CLICKUP_TOKEN=pk_XXXXXXXX
-DAI_TRACKER_URL_TEMPLATE=https://app.clickup.com/t/{id}
 EOF
+# El link a la tarea lo deduce dai solo. Solo si tu tracker vive en otra URL:
+#   DAI_TRACKER_URL_TEMPLATE=https://mi-tracker/t/{id}
 dai doctor                       # confirma DAI_PM=clickup y el token
 
 dai link-us 86cxyz               # trae la US de ClickUp → branch + implements.yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforce2055/dai",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "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/skills/dai-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dai-review
-description: "Revisa una Pull/Merge Request de un repo remoto (GitHub o GitLab) de forma consciente de la metodología dai, y deja un comentario estándar en español con errores y mejoras. Corre `dai check` (¿la US está atrasada?), valida el Definition of Done, hace el review de código (correctitud + calidad), compone el comentario estándar y lo postea — vía el MCP del forge si está disponible, o vía `dai forge comment` (token) si no. Invocar como /dai-review <URL-de-la-PR o número>. Usar en el paso 6 de SCRUM-CON-IA (code review), antes de que un partner humano firme."
+description: "Revisa una Pull/Merge Request de un repo remoto (GitHub o GitLab) de forma consciente de la metodología dai, y deja un comentario estándar en español con errores y mejoras. Corre `dai check` (¿la US está atrasada?), valida el Definition of Done, hace el review de código (correctitud + calidad), compone el comentario estándar, TE LO MUESTRA Y ESPERA TU OK, y recién entonces lo postea — vía el MCP del forge si está disponible, o vía `dai forge comment` (token) si no. Nunca postea sin aprobación explícita: sale con tu nombre y tu token. Invocar como /dai-review <URL-de-la-PR o número>. Usar en el paso 6 de SCRUM-CON-IA (code review), antes de que un partner humano firme."
 ---
 
 # dai-review — review de PR consciente de la metodología
@@ -39,7 +39,11 @@ Mismo comentario estándar, dos formas de dejarlo (elige la disponible, en este
    - 🟡 **Mejoras** de calidad (reuso, simplicidad, eficiencia).
    - ✅ Lo que está **bien** (refuerza lo bueno).
 5. **Componer el comentario estándar** (ver formato abajo).
-6. **Postear** por MCP o `dai forge comment`. Confirmar el link al comentario.
+6. **Mostrarlo y esperar el OK.** Imprimí el comentario **entero**, tal cual va a salir,
+   y preguntá: _"¿lo posteo así, lo edito, o lo descarto?"_ **Frená ahí.** Si te piden
+   cambios, aplicalos y volvé a mostrarlo. No hay atajo: sin un "sí" explícito en este
+   turno, no se postea. Un "sí" de una PR anterior no cuenta para esta.
+7. **Postear** por MCP o `dai forge comment`. Confirmar el link al comentario.
 
 ## El comentario estándar
 
@@ -64,12 +68,20 @@ Es el mismo que emite `renderReviewComment` del CLI — respeta esta forma:
 _Revisión asistida por dai. La aprobación la firma un humano (Art. 5 del manifiesto)._
 ```
 
-## Dos cortes duros
+## Tres cortes duros
 
 1. **No aprobar.** La skill **comenta**, no firma la aprobación. Eso es de un humano.
-2. **Hallazgos concretos.** Nada de "mejorar la calidad" en abstracto: archivo, línea,
+2. **No postear sin OK.** El comentario sale **con el token del humano y con su nombre**
+   (`GITHUB_TOKEN`/`GITLAB_TOKEN` son suyos): en la PR de un compañero figura como si lo
+   hubiera escrito él. Publicar un juicio sobre el código de otro, firmado por alguien
+   que no lo leyó, es tan grave como aprobar sin mirar. El paso 6 no es opcional.
+3. **Hallazgos concretos.** Nada de "mejorar la calidad" en abstracto: archivo, línea,
    y el porqué. Si no es accionable, no va.
 
+> **Por qué el corte 2 existe:** esta skill posteaba directo. El Art. 5 estaba bien
+> leído en la letra —no clickeaba Approve— y mal puesto en la práctica: te dejaba
+> firmar en público un review que nunca viste. Que salga bueno era suerte, no diseño.
+
 ## Relación con el modelo
 
 - Es el paso 6 de [`SCRUM-CON-IA.md`](../../docs/SCRUM-CON-IA.md).

package/templates/pull-request.md

@@ -42,7 +42,11 @@
 
 ## Enlaces relacionados
 
-<!-- US en el tracker, commit ancla, docs, issues. -->
+<!--
+  La US, la branch y el commit ancla los precarga `dai pr` en el bloque `dai:links`
+  de abajo: NO los escribas a mano ni reescribas ese bloque (se regenera y te lo pisa).
+  Acá abajo sumá solo lo que dai no sabe: docs, issues, PRs relacionadas, dependencias.
+-->
 
 ---