@dforce2055/dai 0.13.1 → 0.13.2

package/CHANGELOG.md

@@ -3,6 +3,77 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/). Versionado semver
 (ver `VERSION`).
 
+## [0.13.2] — 2026-09-02
+
+**Una PR se publicaba con la descripción vacía y la lista de cambios diciendo "Cambio 1,
+Cambio 2". No siempre: a veces salía perfecta. Lo raro es que "Enlaces relacionados", que
+vive en el mismo template, nunca falló — y ahí estaba la pista. Y de yapa, el paquete de npm
+adelgaza de 3.7 MB a 703 kB: cargaba las capturas del sitio.**
+
+`dai pr` rellenaba cada sección **solo si tenía el dato** y, si no lo tenía, devolvía el
+molde del template intacto, en silencio. La "Descripción" quedaba en su comentario HTML, que
+no se renderiza: en GitHub y en GitLab la sección se ve **vacía**. El bloque de enlaces nunca
+falló porque su código siempre escribe — si no encuentra la sección, la agrega. Esa
+disciplina ahora vale para todo el cuerpo de la PR.
+
+Detrás del bug había algo más de fondo: **no existía forma de escribir la descripción**.
+`dai pr` no aceptaba ningún texto, así que el propósito de la PR solo podía salir del título
+de la US y de los subjects de los commits. Ni el dev ni su agente podían hacerlo bien aunque
+quisieran.
+
+### Arreglado
+- **La PR salía con el molde del template sin llenar.** Tres caminos llevaban al mismo
+  resultado, los tres silenciosos: (1) el tracker no contestaba —sin token, sin red, `DAI_PM`
+  mal seteado— y sin el título de la US no se llenaba "Descripción"; (2) la branch base no
+  existía **en local** —clones `--single-branch`, repos donde se trabaja sobre `develop` y la
+  base es `main`— y `git log base..HEAD` fallaba dentro de un `catch` vacío, dejando "Cambios
+  realizados" con `Cambio 1 / Cambio 2`; (3) una branch exenta (`chore/`, `docs/`) nunca
+  llenaba "Descripción", ni siquiera pudiendo. Ese mismo `catch` vacío también se comía el
+  chequeo de *"sin commits sobre la base no hay PR"*.
+- **La branch base ahora se resuelve** a `main` o, si no está en local, a `origin/main`.
+- **Las secciones se reconocen aunque el repo tenga su propio molde** (`## 📝 Descripción del
+  cambio`, `### CAMBIOS REALIZADOS`): antes el match era exacto, no encontraba la sección y
+  devolvía el body sin tocar — otra vez, sin decir nada. Ignora los `##` que estén dentro de
+  un bloque de código y, si la sección no existe, la agrega.
+
+### Agregado
+- **`dai pr --description "…"` y `--description-file <archivo.md>`** — el propósito de un
+  cambio no se deriva de git ni del tracker. dai llena la US, el estado del check, los commits
+  y los links; el porqué lo escribe quien crea la PR. **dai no lo inventa: lo pide.**
+- **`--changes` y `--changes-file`** — reemplazan el detalle de "Cambios realizados" cuando los
+  commits no cuentan bien la historia. Sin ellos, siguen saliendo de los commits de la branch.
+- **La constitución que escriben `dai init` y `dai sync` lo dice**, para que el agente que
+  corre `dai pr` sepa que la descripción es suya. Los repos ya inicializados la reciben con
+  `dai sync`.
+
+### Cambiado
+- ⚠️ **`dai pr` no publica una PR que saldría con el molde sin llenar.** Con `--yes` o sin TTY
+  —el camino de un agente o de CI— **aborta** y dice qué flag pasar; en terminal avisa y decide
+  la persona. **Si tenés automatización con `dai pr --yes` sin `--description`, se va a frenar**:
+  es justamente lo que publicaba las PRs vacías. El molde también se detecta en la cabecera
+  (`ABC-###`), la misma familia de los issues #31/#33.
+
+### Arreglado — el paquete de npm
+- **`npm i -g @dforce2055/dai` bajaba las capturas del sitio.** `files[]` lista `docs`
+  entero, y ahí adentro viven las de los tutoriales (`docs/public/tutoriales/*.png`): **2.9 MB
+  de los 3.7 MB del paquete**, que el CLI no abre nunca. El test de higiene que ya cubría el
+  sitio (`index.html`, `onboarding.html`) no las veía porque entraban por otra puerta.
+  **3.7 MB → 703 kB**, 130 → 117 archivos, cero PNG en el tarball ([#37](https://github.com/dforce2055/dai/issues/37)).
+- **`dai docs` copiaba imágenes que no se veían.** Los `.md` referencian las capturas con la
+  ruta absoluta del sitio (`![…](/tutoriales/x.png)`, que VitePress resuelve contra
+  `docs/public/`); fuera del sitio esa ruta apunta a la raíz del filesystem, así que en la
+  copia **ya estaban rotas**, con los 2.9 MB adentro y todo. Ahora `dai docs` no copia
+  `public/` —son assets del sitio, no documentación para leer desde un repo— y **absolutiza**
+  esos links contra el sitio publicado: la doc copiada por fin muestra las capturas.
+
+### Interno
+- **358 tests** (+19). Uno por cada camino que dejaba pasar el molde del template —tracker
+  caído, sin commits, branch sin US, template propio del repo, headings dentro de un fence, y
+  el caso peor (sin tracker y sin commits a la vez)— más los de la reescritura de links y dos
+  de higiene que fijan la regla del paquete: que `files[]` declare la exclusión, y que no
+  aparezcan imágenes versionadas bajo `docs/` fuera de esa carpeta. Si mañana una captura
+  aterriza en otro lado, el test obliga a decidir ahí, no midiendo el tarball.
+
 ## [0.13.1] — 2026-08-24
 
 **Un dev en Windows no podía pushear contra el GitLab de su empresa. `ssh -T` le autenticaba
@@ -737,6 +808,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.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
 [0.12.0]: https://github.com/dforce2055/dai/releases/tag/v0.12.0

package/README.md

@@ -103,7 +103,8 @@ dai link-us <ID>                # trae la US del tracker → branch + implements
 ```bash
 dai check                       # ¿tu código sigue al día con la US?  ✅ / ⚠️ atrasado
 # revisas tu propio código + smoke test local antes de la PR
-dai pr --assignee <compañero>   # crea la PR precargada y se la asigna a un compañero
+dai pr --assignee <compañero> \
+  --description "Qué resuelve y por qué"   # crea la PR precargada y se la asigna a un compañero
 ```
 ```text
 /dai-review <PR>                # tu compañero deja un review inline (comentario por línea); un humano aprueba
@@ -201,14 +202,14 @@ flowchart TD
 | `dai link-us <ID> --resync` | re-estampa el `ac_hash` contra la US viva (tras un ⚠️ de check) |
 | `dai check` | compara tu código vs la US viva → ✅ al día / ⚠️ atrasado (exit code = gate de PR) |
 | `dai ls [--json]` | lista las US que implementa el repo + su link al tracker |
-| `dai pr [--assignee u] [--base b] [--draft] [--yes] [--us ID] [--title t]` · alias **`dai mr`** | crea TU PR/MR precargada: pregunta la branch base (default `main`), muestra el texto y confirma antes de publicar. Detecta el forge (GitHub→PR con `gh` · GitLab→MR con `glab`); `mr` es el mismo comando, más natural en GitLab. **La US la resuelve la branch** (la nombra `dai link-us`): si hay varias vivas y ninguna coincide, **pregunta** en vez de elegir por vos (sin TTY falla pidiendo `--us <ID>`), y una branch `chore/`/`docs/` sale **sin US** en lugar de heredar la de otro |
+| `dai pr [--assignee u] [--base b] [--draft] [--yes] [--us ID] [--title t] [--description t\|--description-file f] [--changes t\|--changes-file f]` · alias **`dai mr`** | crea TU PR/MR precargada: pregunta la branch base (default `main`), muestra el texto y confirma antes de publicar. Detecta el forge (GitHub→PR con `gh` · GitLab→MR con `glab`); `mr` es el mismo comando, más natural en GitLab. **La US la resuelve la branch** (la nombra `dai link-us`): si hay varias vivas y ninguna coincide, **pregunta** en vez de elegir por vos (sin TTY falla pidiendo `--us <ID>`), y una branch `chore/`/`docs/` sale **sin US** en lugar de heredar la de otro. **La descripción la escribís vos (o tu agente) con `--description`**: dai llena la US, los commits y los links, pero no inventa el propósito de un cambio — si "Descripción" o "Cambios realizados" quedarían con el molde del template, con `--yes` o sin TTY **no publica** y te dice qué falta |
 | `dai stamp` | estampa la cobertura inversa en el tracker (branch + commit-ancla) |
 | `dai done [--base main] [--force]` | cierra la US: vuelve a la base, `fetch --prune` + `pull`, y borra la branch local **si está mergeada** (chequeo estricto; `--force` la borra igual). Redes: no estar en la base, sin cambios sueltos, sin commits sin pushear |
 | `dai archive [<change>] [--skip-specs]` | **funde los delta specs del change en las specs canónicas** (`openspec/specs/`) y lo archiva. Lo corre el **aprobador** de la PR (gate de aprobación, [ADR-0011](docs/adr/0011-archive-gate-de-aprobacion.md)); detecta el change activo o le pasás el nombre. Envuelve `openspec archive` |
 | `dai forge review <ref> --from <review.json>` `[--dry-run\|--yes]` | **review inline**: un resumen + un comentario anclado a cada `archivo:línea`, clasificado low/medium/high. **Valida cada posición contra el diff** (descarta lo que el modelo inventó) antes de postear; sin `--yes` muestra el preview y no postea nada. Modo desatendido: `--min-severity`/`--min-confidence`/`--max-comments`. El review sale con `event: COMMENT`, nunca `APPROVE` ([ADR-0016](docs/adr/0016-review-inline.md)) |
 | `dai forge comment <ref> --body-file <f>` · `dai forge pr <ref>` | comentar / leer una PR/MR (GitHub/GitLab) — el fallback simple, sin anclar |
 | `dai ac-hash <us.md>` | calcula el hash de los criterios de aceptación de una US |
-| `dai doctor` · `dai docs <dest>` · `dai version` | diagnóstico del entorno (incluye **version-drift** del scaffold) · copiar la doc · versión (`dai version` avisa si tu repo quedó atrás) |
+| `dai doctor` · `dai docs <dest>` · `dai version` | diagnóstico del entorno (incluye **version-drift** del scaffold) · copiar la doc (sin los assets del sitio; los links a las capturas apuntan al sitio publicado) · versión (`dai version` avisa si tu repo quedó atrás) |
 
 > **🆕 Mantené tu repo al día — `dai sync`.** Las skills, la constitución y los templates son un
 > *caché derivable* del CLI. Cuando actualizás `dai` (`dai upgrade`), **`dai doctor` y

package/VERSION

@@ -1 +1 @@
-0.13.1
+0.13.2

package/cli/dai.mjs

@@ -27,7 +27,8 @@ import { branchUrl, commitUrl, parseRemote, detectForge } from "./lib/forge-url.
 import { parsePrRef, getPR, postComment, postReview } from "./lib/forge-api.mjs";
 import { trackerUrl } from "./lib/tracker-url.mjs";
 import { parseFindings, diffPositions, validateFindings, filterFindings, renderFindingBody, renderReviewSummary } from "./lib/review-findings.mjs";
-import { composePrBody, prTitle, forgeTool } from "./lib/pr.mjs";
+import { composePrBody, prTitle, forgeTool, bodyGaps } from "./lib/pr.mjs";
+import { absolutizeSiteLinks } from "./lib/docs-links.mjs";
 import { diagnoseGitSsh, pushFailureHint, WINDOWS_OPENSSH } from "./lib/git-ssh.mjs";
 import { dirsEqual } from "./lib/fsutil.mjs";
 import { parseFlags, parseAssistants, isAssistantToken, asList } from "./lib/args.mjs";
@@ -216,6 +217,27 @@ function gitUser() {
 function gitRemote() { try { return git(["remote", "get-url", "origin"]); } catch { return null; } }
 function gitBranch() { try { return git(["rev-parse", "--abbrev-ref", "HEAD"]); } catch { return null; } }
 function gitCommit() { try { return git(["rev-parse", "HEAD"]); } catch { return null; } }
+// ¿Existe esta ref como commit? Devuelve la ref si sí, null si no. Sirve para caer de
+// `main` a `origin/main` sin adivinar: en muchos repos la base solo existe en el remoto.
+function resolveRev(ref) {
+  try { git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]); return ref; } catch { return null; }
+}
+// Un texto que se puede pasar inline (`--description "…"`) o por archivo
+// (`--description-file notas.md`). Un agente casi siempre quiere el archivo: markdown
+// multilínea no sobrevive entero a la línea de comandos.
+function textOpt(opts, name) {
+  const file = opts[`${name}File`];
+  if (file !== undefined) {
+    if (file === true) fail(`--${name}-file necesita la ruta de un archivo.`, 1);
+    const path = Array.isArray(file) ? file[file.length - 1] : file;
+    try { return readFileSync(path, "utf8"); }
+    catch { fail(`no pude leer --${name}-file '${path}'.`, 1); }
+  }
+  const v = opts[name];
+  if (v === true) fail(`--${name} necesita un texto (o usá --${name}-file <archivo>).`, 1);
+  if (Array.isArray(v)) return v.join("\n");
+  return typeof v === "string" ? v : null;
+}
 
 // ── check --ci: el gate de governance/ci-rules.md, ejecutable ────────────────
 //
@@ -879,9 +901,16 @@ async function cmdPr(opts) {
   let base = opts.base;
   if (!base) { const ans = await ask("  ¿Contra qué branch va la PR? (main) "); base = ans || "main"; }
 
+  // La base puede no existir LOCAL (clones con --single-branch, repos donde el dev
+  // trabaja sobre develop y la base es main, corporativos con la base solo en origin).
+  // Antes el catch vacío se comía el error y seguía de largo: ni se contaban los commits
+  // (→ "Cambios realizados" salía con el molde) ni frenaba el chequeo de abajo.
+  const baseRev = resolveRev(base) || resolveRev(`origin/${base}`);
+  if (!baseRev) warn(`no encuentro la branch base '${base}' (ni local ni en origin/${base}). Trae la base primero:  git fetch origin ${base}`);
+
   // Sin commits sobre la base no hay PR.
   let ahead = null;
-  try { ahead = Number(git(["rev-list", "--count", `${base}..HEAD`])); } catch { /* base no existe local */ }
+  try { ahead = Number(git(["rev-list", "--count", `${baseRev}..HEAD`])); } catch { /* base ausente */ }
   if (ahead === 0) {
     fail(`no hay commits en '${branch}' por encima de '${base}'. Una PR necesita cambios: haz commit primero (git commit).`, 1);
   }
@@ -944,7 +973,13 @@ async function cmdPr(opts) {
     : join(ROOT, "templates", "pull-request.md");
   // 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 */ }
+  if (baseRev) {
+    try { commits = git(["log", `${baseRev}..HEAD`, "--pretty=%s"]).split("\n").filter(Boolean); } catch { /* rango inválido */ }
+  }
+  // El texto que escribe quien crea la PR (el dev o su agente). Es la ÚNICA fuente de
+  // una descripción de verdad: dai lee git y el tracker, no el porqué del cambio.
+  const description = textOpt(opts, "description");
+  const changes = textOpt(opts, "changes");
   // La canónica del tracker (live.url) gana sobre la derivada; el template gana sobre todo.
   const usUrl = id ? usUrlFor(id, live?.url) : null;
   if (id && !usUrl) {
@@ -952,7 +987,8 @@ async function cmdPr(opts) {
     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, noUsReason: id ? null : scope.reason,
+    id, version, ac_hash, status, usUrl, usTitle: live?.title, commits, description, changes,
+    noUsReason: id ? null : scope.reason,
     branch, branchUrl: branchUrl(remote, branch), commit, commitUrl: commitUrl(remote, commit),
   });
   // Sin US el título sale del último commit: describe lo que hay adentro, en vez de
@@ -969,6 +1005,27 @@ async function cmdPr(opts) {
   process.stdout.write(`  ─────────────────────────────────────────────────────\n\n${body}\n`);
   process.stdout.write(`  ─────────────────────────────────────────────────────\n`);
 
+  // 4b. Gate: una PR con el molde del template sin llenar no se puede revisar.
+  // Pasaba en repos reales — "Descripción" con el comentario HTML (que no se renderiza:
+  // la sección se ve VACÍA) y "Cambios realizados" con `Cambio 1/Cambio 2` — cada vez
+  // que el tracker no respondía o la base no estaba local. dai NO inventa la descripción:
+  // la pide. Sin TTY (el camino del agente) frena; en terminal avisa y decidís vos.
+  const gaps = bodyGaps(body);
+  if (gaps.length) {
+    const how =
+      `  Escribí el texto y pasáselo a dai:\n` +
+      `    dai pr --description "Qué resuelve este cambio y por qué (2–4 líneas)."\n` +
+      `    dai pr --description-file notas.md --changes-file cambios.md   (markdown multilínea)\n` +
+      `  El detalle de "Cambios realizados" sale de los commits si no pasás --changes.\n`;
+    if (opts.yes || !process.stdin.isTTY) {
+      closeRl();
+      fail(`la PR saldría con el molde del template sin llenar: ${gaps.join(", ")}.\n` +
+           `  Una PR sin descripción no se puede revisar, así que no la publico.\n${how}`, 1);
+    }
+    warn(`la PR va a salir con el molde sin llenar: ${gaps.join(", ")}.`);
+    process.stdout.write(how);
+  }
+
   // Archivo de paso para gh/glab: en el temp del sistema, NO en el repo (no lo ensucia).
   const bodyFile = join(mkdtempSync(join(tmpdir(), "dai-pr-")), "body.md");
   if (!opts.yes) {
@@ -1431,8 +1488,28 @@ async function cmdInit(repo, opts) {
 function cmdDocs(dest) {
   if (!dest) fail("uso: dai docs <destino>");
   mkdirSync(dest, { recursive: true });
-  cpSync(join(ROOT, "docs"), dest, { recursive: true });
+  // `public/` son los assets del sitio (VitePress), no documentación para leer desde el
+  // repo de nadie: las capturas de los tutoriales ni siquiera viajan en el paquete npm
+  // (issue #37). Se saltea, y los links que las nombran se absolutizan contra el sitio.
+  cpSync(join(ROOT, "docs"), dest, { recursive: true, filter: (src) => !/[/\\]public([/\\]|$)/.test(src) });
+  let reescritos = 0;
+  for (const f of walkMd(dest)) {
+    const md = readFileSync(f, "utf8");
+    const out = absolutizeSiteLinks(md);
+    if (out !== md) { writeFileSync(f, out); reescritos++; }
+  }
   ok(`documentación copiada a ${dest}`);
+  if (reescritos) info(`${reescritos} documento(s) con capturas: los links apuntan al sitio publicado.`);
+}
+
+// Los .md de un árbol, para la reescritura de links de cmdDocs.
+function walkMd(dir, out = []) {
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    if (statSync(p).isDirectory()) walkMd(p, out);
+    else if (name.endsWith(".md")) out.push(p);
+  }
+  return out;
 }
 
 // ── archive: funde los delta specs del change en los specs canónicos y lo archiva ─
@@ -1845,6 +1922,10 @@ switch (cmd) {
       "  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" +
       "      [--us <ID>] [--title t]  la US la resuelve la branch; si hay varias, pregunta (sin TTY, falla)\n" +
+      "      --description <texto>    QUÉ resuelve la PR y por qué → sección 'Descripción' (o --description-file <f>)\n" +
+      "      --changes <texto>        detalle de 'Cambios realizados' (default: los commits) (o --changes-file <f>)\n" +
+      "                               sin descripción y sin commits, con --yes o sin TTY, dai NO publica: la PR\n" +
+      "                               saldría con el molde del template y no se podría revisar\n" +
       "  forge comment <ref> --body-file <f> · forge pr <ref>   comentar/leer una PR ajena (github/gitlab)\n" +
       "  forge review <ref> --from <review.json> [--dry-run|--yes]  review inline: resumen + comentario por línea\n" +
       "      --min-severity low|medium|high · --min-confidence 0..1 · --max-comments N · --base <branch>\n" +

package/cli/lib/bootstrap.mjs

@@ -277,6 +277,7 @@ export function constitution(kind) {
 - **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.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.
+- **La PR la escribe quien la crea:** \`dai pr\` precarga la US, el estado del check, los commits y los links, pero **la Descripción la escribes tú**: \`dai pr --description "qué resuelve y por qué"\` (o \`--description-file <archivo.md>\` para markdown multilínea, y \`--changes\` si los commits no cuentan bien la historia). dai **no inventa** el propósito de un cambio: si la Descripción o los Cambios realizados quedarían con el molde del template, no publica la PR. Una PR sin descripción no se puede revisar.
 - **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.
 - Separa el QUÉ (funcional) del CÓMO (técnico); no mezcles.
@@ -293,7 +294,7 @@ export function constitution(kind) {
 
 - **Skills (el QUÉ):** \`doc-to-backlog\` (un doc → backlog) · \`grill-intent\` (Gate 0) · \`grill-epic\` (épicas) · \`grill-user-story\` (la US)
 - **Skills (el CÓMO):** \`link-us\`, \`tdd\`, \`dai-review\`
-- **CLI:** \`dai link-us <ID>\` · \`dai check\` · \`dai stamp\` · \`dai pr\` · \`dai ls\`
+- **CLI:** \`dai link-us <ID>\` · \`dai check\` · \`dai stamp\` · \`dai pr --description "…"\` · \`dai ls\`
 - **Formatos:** \`.dai/templates/\` · **Governance:** \`.dai/governance/\`
 
 Detalle completo de la metodología: ${REPO_URL}

package/cli/lib/docs-links.mjs

@@ -0,0 +1,23 @@
+// dai · reescribir los links absolutos del sitio cuando la doc se copia afuera.
+//
+// Los .md de docs/ son la fuente del sitio (VitePress, `base: "/dai/docs/"`), así que las
+// capturas se referencian con la ruta absoluta del sitio: `![…](/tutoriales/x.png)`, que
+// VitePress resuelve contra docs/public/. Fuera del sitio esa ruta no resuelve a nada: en
+// una copia hecha con `dai docs`, `/tutoriales/x.png` apunta a la raíz del filesystem (o
+// del repo, si lo renderiza GitHub). O sea que la imagen ya estaba rota en la copia,
+// tuviera o no el paquete los 2.9 MB de PNG adentro (issue #37).
+//
+// Al copiar, esos links se vuelven absolutos contra el sitio publicado: la doc copiada
+// muestra las capturas, y el paquete de npm no las carga.
+
+export const SITE_DOCS = "https://dforce2055.github.io/dai/docs";
+
+// Rutas absolutas del sitio que aparecen en los .md. Se listan a propósito en vez de
+// reescribir toda `](/…)`: un link a `/etc/hosts` en un ejemplo no es un link del sitio.
+const SITE_PATHS = /\]\(\/(tutoriales\/[^)\s]+)\)/g;
+
+// Devuelve el markdown con los links del sitio apuntando al sitio publicado.
+// Idempotente: una URL ya absoluta no matchea (el patrón exige `](/`).
+export function absolutizeSiteLinks(md) {
+  return String(md).replace(SITE_PATHS, (_, path) => `](${SITE_DOCS}/${path})`);
+}

package/cli/lib/pr.mjs

@@ -4,48 +4,134 @@
 
 const EMOJI = { "al-dia": "✅ al día", atrasado: "⚠️ atrasado", "sin-us": "❓ sin US" };
 
-// Reemplaza el cuerpo de una sección (## Heading … hasta el próximo ## o el final)
-// por content. Tolerante: si no encuentra la sección, devuelve el body igual.
-// Sin flag `m`: `$` = fin de string (no fin de línea), así no corta antes de tiempo.
+// 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:
+// "Descripción" con el comentario HTML y "Cambios realizados" con `Cambio 1/Cambio 2`).
+// `dai pr` las verifica con bodyGaps() antes de publicar.
+export const OWNED_SECTIONS = ["Descripción", "Cambios realizados"];
+
+// ── Secciones ────────────────────────────────────────────────────────────────
+// Normaliza un heading para compararlo: sin acentos, sin emoji ni puntuación, minúscula.
+// Un repo puede traer su propio template ("## 📝 Descripción del cambio") y dai igual
+// tiene que reconocer la sección: con el match exacto de antes no la encontraba y
+// devolvía el body intacto EN SILENCIO, que es la forma más cara de fallar.
+const norm = (s) => String(s).normalize("NFD").replace(/[\u0300-\u036f]/gu, "")
+  .replace(/[^\p{L}\p{N}]+/gu, " ").trim().toLowerCase();
+
+// Ubica una sección markdown (## Heading … hasta el próximo heading de igual o menor
+// nivel). Ignora lo que esté dentro de un bloque de código: un `## ` en un fence es
+// texto, no estructura. Devuelve null si no está.
+function findSection(lines, heading) {
+  const want = norm(heading);
+  let start = -1, level = 0, fence = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s*(```|~~~)/.test(lines[i])) { fence = !fence; continue; }
+    if (fence) continue;
+    const m = /^(#{2,6})[ \t]+(.+?)[ \t]*$/.exec(lines[i]);
+    if (!m) continue;
+    if (start === -1) { if (norm(m[2]).startsWith(want)) { start = i; level = m[1].length; } }
+    else if (m[1].length <= level) return { start, end: i, level };
+  }
+  return start === -1 ? null : { start, end: lines.length, level };
+}
+
+// El cuerpo crudo de una sección, o null si la sección no existe.
+export function sectionBody(body, heading) {
+  const lines = body.split("\n");
+  const at = findSection(lines, heading);
+  return at ? lines.slice(at.start + 1, at.end).join("\n") : null;
+}
+
+// Reemplaza el cuerpo de una sección por content. Tolerante: si no encuentra la
+// sección, devuelve el body igual (para eso está upsertSection).
 export function replaceSection(body, heading, content) {
-  const esc = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const re = new RegExp(`(^|\\n)(##[ \\t]*${esc}[ \\t]*\\n)([\\s\\S]*?)(\\n##\\s|$)`, "i");
-  if (!re.test(body)) return body;
-  return body.replace(re, (m, pre, h, _b, tail) => `${pre}${h}\n${content}\n${tail}`);
+  const lines = body.split("\n");
+  const at = findSection(lines, heading);
+  if (!at) return body;
+  return [...lines.slice(0, at.start + 1), "", content, "", ...lines.slice(at.end)].join("\n");
+}
+
+// Como replaceSection, pero si la sección no está la agrega al final con su heading.
+// Misma disciplina que el bloque de enlaces: dai siempre entrega el dato, nunca lo
+// pierde porque el template del repo no tenía dónde ponerlo. content null = no sé
+// nada → no toco (y bodyGaps lo va a reportar; dai no inventa contenido).
+export function upsertSection(body, heading, content) {
+  if (content == null || !String(content).trim()) return body;
+  if (findSection(body.split("\n"), heading)) return replaceSection(body, heading, content);
+  return `${body.replace(/\s*$/, "")}\n\n## ${heading}\n\n${content}\n`;
+}
+
+// ── Detección del molde sin llenar ───────────────────────────────────────────
+// Moldes conocidos del template: líneas que no dicen nada sobre ESTE cambio.
+const MOCK_LINES = [/^-?\s*\[[ x]\]\s*cambio\s*\d+\s*$/i, /^cambio\s*\d+\s*$/i, /^-?\s*\[[ x]\]\s*$/];
+
+// ¿El cuerpo de una sección es puro molde? Los comentarios HTML no cuentan como
+// contenido: no se renderizan, así que en la PR publicada la sección se ve VACÍA
+// (por eso el bug pasaba desapercibido hasta que alguien abría la PR).
+export function isPlaceholder(text) {
+  const lines = String(text ?? "").replace(/<!--[\s\S]*?-->/g, "").split("\n").map((l) => l.trim()).filter(Boolean);
+  if (!lines.length) return true;
+  return lines.every((l) => MOCK_LINES.some((re) => re.test(l)));
+}
+
+// Qué le falta al body para ser revisable. Vacío = la PR se puede publicar.
+// `dai pr` lo usa como gate: sin TTY (el camino del agente) falla en vez de publicar
+// una PR que nadie puede revisar.
+export function bodyGaps(body) {
+  const gaps = OWNED_SECTIONS.filter((h) => {
+    const s = sectionBody(body, h);
+    return s === null || isPlaceholder(s);
+  });
+  // Placeholders de la cabecera: la PR saldría diciendo `ABC-###` (issues #31/#33).
+  if (/ABC-###|`<hash>`|@ `vX`/.test(body)) gaps.push("🔗 Implementa");
+  return gaps;
+}
+
+// ── Composición ──────────────────────────────────────────────────────────────
+// Descripción: lo que escribió quien crea la PR (agente o dev) gana; si no, se deriva
+// de la US. Si dai no sabe nada, devuelve null: no inventa el propósito de un cambio.
+export function descriptionFor(d) {
+  const explicit = String(d.description ?? "").trim();
+  if (explicit) return explicit;
+  if (d.usTitle) return `Implementa la US **${d.usTitle}** (\`${d.id}\`). Ver los criterios de aceptación en el tracker.`;
+  return null;
 }
 
-// Rellena el template del PR con los datos precargados. Tolerante: reemplaza los
-// placeholders que encuentra y deja el resto para que el humano lo edite.
+// Cambios realizados: el detalle explícito gana; si no, los commits de la branch
+// (como `gh pr create --fill`). Sin ninguno de los dos, null.
+export function changesFor(d) {
+  const explicit = String(d.changes ?? "").trim();
+  if (explicit) return explicit;
+  if (d.commits && d.commits.length) return d.commits.map((c) => `- [x] ${c}`).join("\n");
+  return null;
+}
+
+// Rellena el template del PR con los datos precargados. Tolerante con el resto del
+// template (checklists, secciones propias del repo): dai suma, no borra.
 export function composePrBody(template, d) {
+  let b = d.id ? fillUsHeader(template, d) : fillNoUsHeader(template, d);
+  b = upsertSection(b, "Descripción", descriptionFor(d));
+  b = upsertSection(b, "Cambios realizados", changesFor(d));
+  return upsertLinksBlock(b, d);
+}
+
+function fillUsHeader(template, d) {
   let b = template;
-  if (!d.id) return composePrBodyNoUs(b, d);
   b = b.replace(/`ABC-###`/g, `\`${d.id}\``);
   b = b.replace(/@ `vX`/g, `@ \`${d.version}\``);
   b = b.replace(/`<hash>`/g, `\`${d.ac_hash}\``);
-  b = b.replace(/verificado con `dai check` ✅/g, `verificado con \`dai check\`: ${EMOJI[d.status] || d.status}`);
-
-  // Descripción: default desde la US (el humano lo pule).
-  if (d.usTitle) b = replaceSection(b, "Descripción", `Implementa la US **${d.usTitle}** (\`${d.id}\`). Ver los criterios de aceptación en el tracker.`);
-  // Cambios realizados: de los commits de la branch (como gh pr create --fill).
-  if (d.commits && d.commits.length) {
-    b = replaceSection(b, "Cambios realizados", d.commits.map((c) => `- [x] ${c}`).join("\n"));
-  }
-  return upsertLinksBlock(b, d);
+  return b.replace(/verificado con `dai check` ✅/g, `verificado con \`dai check\`: ${EMOJI[d.status] || d.status}`);
 }
 
 // PR de una branch exenta (chore/, docs/, release/…): no implementa una US y no se le
 // exige link. Lo que NO puede pasar es que salga con la US de otro ni con el placeholder
 // `ABC-###` del template — las dos cosas pasaron en repos reales (issues #31, #33).
 // Se dice explícitamente que no hay US, y por qué.
-function composePrBodyNoUs(template, d) {
-  let b = replaceSection(template, "🔗 Implementa",
+function fillNoUsHeader(template, d) {
+  return replaceSection(template, "🔗 Implementa",
     `- **Sin US:** esta PR no implementa una User Story.\n` +
     (d.noUsReason ? `- **Motivo:** ${d.noUsReason}.\n` : "") +
     `- No se le exige link (\`governance/branch-naming.md\`).`);
-  if (d.commits && d.commits.length) {
-    b = replaceSection(b, "Cambios realizados", d.commits.map((c) => `- [x] ${c}`).join("\n"));
-  }
-  return upsertLinksBlock(b, d);
 }
 
 // ── Bloque de enlaces ────────────────────────────────────────────────────────

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

@@ -239,7 +239,9 @@ código + spec trazable) — y la asigna a un partner:
 ```
 $ dai check
 ✅ ABC-482 al día (v1)
-$ dai pr --assignee mgomez
+$ dai pr --assignee mgomez \
+    --description "Permite comprar sin crear cuenta: el checkout acepta un email de
+                   contacto y genera la orden como invitado. Baja el abandono del paso 2."
 ✓ PR #123 creada → …/pull/123   (base: main · US: ABC-482 @ v1 · dai check ✅)
 ```
 

package/docs/guias/dev.md

@@ -35,8 +35,11 @@
    (anti vibe-coding). Ajustas y **commiteas** lo que haga falta.
 6. **Creas la PR** → con el smoke verde y **todo commiteado** (lo que quede sin commitear
    **no entra** en la PR), corres `dai check` (gate: ¿al día con la US?) y en verde `dai pr`
-   arma la PR **precargada** (US + estado del check + links; los **dos activos**: código +
-   spec trazable) y la asignas a un partner.
+   arma la PR **precargada** (US + estado del check + commits + links; los **dos activos**:
+   código + spec trazable) y la asignas a un partner. **La descripción la escribes tú**
+   (`--description "…"`, o `--description-file notas.md`): dai llena lo que puede derivar,
+   pero no inventa el propósito de un cambio — y si esa sección quedaría con el molde del
+   template, **no publica la PR**. Una PR sin descripción no se puede revisar.
 7. **Review de un partner** → un compañero revisa tu PR y **firma** aprobación/rechazo
    (Art. 5). Se apoya en la skill `/dai-review` para un primer pase: un **review inline**
    (resumen + un comentario por línea), que le muestra el preview y espera su OK antes de postear.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforce2055/dai",
-  "version": "0.13.1",
+  "version": "0.13.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/",
@@ -27,6 +27,7 @@
     "cli/dai.mjs",
     "cli/lib",
     "docs",
+    "!docs/public/tutoriales",
     "templates",
     "governance",
     "skills",

package/templates/pull-request.md

@@ -21,10 +21,19 @@
 
 ## Descripción
 
-<!-- Breve propósito de este PR, en términos de negocio (2–4 líneas). -->
+<!--
+  Breve propósito de este PR, en términos de negocio (2–4 líneas).
+  Lo precarga `dai pr --description "…"` (o `--description-file <archivo.md>`).
+  dai NO lo inventa: si esta sección queda sin llenar, `dai pr` no publica la PR.
+-->
 
 ## Cambios realizados
 
+<!--
+  Lo precarga `dai pr` con los commits de la branch; `--changes` / `--changes-file`
+  lo reemplazan por el detalle que quieras contar.
+-->
+
 - [ ] Cambio 1
 - [ ] Cambio 2