@dforce2055/dai 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -3,6 +3,66 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/). Versionado semver
 (ver `VERSION`).
 
+## [0.12.0] — 2026-08-13
+
+**La PR deja de robarle la US a otro. `dai pr` resolvía el link recorriendo todo el repo y
+quedándose con el último `implements.yaml`; ahora lo resuelve la rama, que es la que sabe la
+respuesta — y cuando no puede saberlo, pregunta en vez de elegir en silencio. Más el tutorial
+de setup del dev, la contraparte del que ya tenía el funcional.**
+
+### Arreglado
+- **`dai pr` armaba la PR con la US equivocada** (issues [#31](https://github.com/dforce2055/dai/issues/31),
+  [#32](https://github.com/dforce2055/dai/issues/32), [#33](https://github.com/dforce2055/dai/issues/33)).
+  Recorría **todos** los `implements.yaml` del repo —archivados incluidos, porque era el
+  único comando que no pasaba `{ includeArchived: false }`— y el `break` cortaba solo el
+  bucle interno, así que ganaba el **último** en orden de lectura. La rama, que la nombra el
+  propio `dai link-us`, no entraba en la decisión.
+  El síntoma es silencioso y por eso duele: la PR sale con el título, el link y el
+  `dai check ✅` de **otra** US. En repos reales convivieron dos PRs con el mismo título y
+  contenidos que no tenían nada que ver, y una PR de archivado apareció rotulada con la
+  historia de un compañero. Es exactamente el modo de falla que la constitución quiere
+  evitar — el link QUÉ↔CÓMO queda mal y nadie se entera, porque **nadie lee el
+  `implements.yaml` en la lista de PRs: leen el título**.
+  Ahora decide `prScope` (`cli/lib/branch-scope.mjs`), hermana de `stampScope`: la rama
+  nombra una US viva → esa; una sola US viva → esa; varias candidatas → **pregunta** con TTY
+  y **falla** sin TTY, listándolas.
+- **Una rama exenta ya no hereda la US del repo.** Un `chore/`/`docs/`/`release/` que no
+  nombra ninguna US genera la PR **sin** US —título del último commit y la sección
+  *Implementa* diciendo que no hay historia— en lugar de colgarle la de otro o dejar el
+  placeholder `ABC-###` del template.
+- **`dai done` anunciaba `US cerrada:` con todas las US del repo**, archivadas incluidas.
+  Cerrar una rama informaba el cierre de medio sprint. Mismo defecto de clase, en un mensaje.
+- **Ctrl+D en las preguntas de `dai pr`** cancela en vez de cortar con `Aborted with Ctrl+D`.
+  Todas ellas preceden a una acción hacia afuera (push + PR): ahí abortar es lo seguro.
+
+### Agregado
+- **`dai pr --us <ID>`** — el escape hatch explícito, y la única salida cuando hay ambigüedad
+  y no hay TTY (un pipeline). Acepta también un change ya archivado.
+- **El preview dice de dónde salió la US**: `US: ABC-482 — la branch '…' nombra ABC-482`.
+  Cuando el título está mal, es lo único que lo delata.
+- **[Tutorial de setup para desarrolladores (Windows)](docs/tutoriales/setup-dev.md)** — el
+  otro lado del que ya existía para el funcional: Node, dai, git + SSH + `glab`, las skills
+  en Copilot, OpenSpec, el `.env.dai` contra Jira, y el ciclo completo sobre una US real
+  (`link-us` → `check` → `mr` → `stamp` → `done`). El troubleshooting sale de lo que pasó de
+  verdad en Windows corporativo: el push HTTPS que necesita completar el credential manager,
+  el proxy con su propio certificado, el gate de CI.
+
+### Versionado
+
+**Minor → 0.12.0.** `dai pr` **cambia de comportamiento**: donde antes elegía una US en
+silencio, ahora pregunta (o falla), y una rama exenta genera la PR sin US. En el papel es
+incompatible; en la práctica el comportamiento viejo era el bug de los issues #31/#32/#33.
+Suma la flag `--us`, aditiva. El contrato del modelo (`ac_hash`, schema de `implements.yaml`)
+queda intacto.
+
+### Interno
+- **319 tests** (+12 desde 0.11.0): `prScope` ×10 —la rama manda sobre el orden de
+  directorio, los archivados no compiten, una `chore/` no hereda, la ambigüedad no se
+  resuelve sola— y el cuerpo/título de una PR sin US ×2.
+- `requiresLink()` devuelve además `kind` (`always` / `exempt` / `untyped`): es lo que separa
+  "exenta por tipo" de "la rama no dice nada", y lo que `dai pr` necesitaba para no heredar
+  la US de otro sin romper el gate de CI.
+
 ## [0.11.0] — 2026-07-22
 
 **Ronda de fixes reportados usándola, más el eslabón que faltaba: editar el QUÉ. `dai stamp`
@@ -551,6 +611,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.12.0]: https://github.com/dforce2055/dai/releases/tag/v0.12.0
 [0.11.0]: https://github.com/dforce2055/dai/releases/tag/v0.11.0
 [0.10.0]: https://github.com/dforce2055/dai/releases/tag/v0.10.0
 [0.9.0]: https://github.com/dforce2055/dai/releases/tag/v0.9.0

package/README.md

@@ -201,7 +201,7 @@ 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]` · 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 |
+| `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 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` |

package/VERSION

@@ -1 +1 @@
-0.11.0
+0.12.0

package/cli/dai.mjs

@@ -35,7 +35,7 @@ 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 { flattenImplements, stampScope, prScope, matchBranchToImplements, 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";
 
@@ -802,8 +802,12 @@ function cmdDone(opts) {
   }
 
   // La US que se cierra (informativo) — leerla ANTES de cambiar de branch.
-  const usIds = [];
-  for (const f of discoverImplements(process.cwd())) for (const im of f.implements || []) if (!isPlaceholderId(im.id)) usIds.push(im.id);
+  // Solo la de ESTA branch: antes listaba todas las del repo (archivadas incluidas), así
+  // que cerrar una branch anunciaba el cierre de medio sprint — el mismo defecto que
+  // `dai pr` en los issues #31/#32/#33, acá en un mensaje.
+  const usIds = matchBranchToImplements(
+    branch, flattenImplements(discoverImplements(process.cwd(), { includeArchived: false })),
+  ).map((r) => r.id);
 
   // Ir a la base y actualizar.
   info(`Cambiando a '${base}' y actualizando…`);
@@ -848,7 +852,10 @@ async function cmdPr(opts) {
   const ask = async (q) => {
     if (!process.stdin.isTTY) return null;   // no interactivo → sin preguntas
     if (!_rl) _rl = createInterface({ input: process.stdin, output: process.stdout });
-    return (await _rl.question(q)).trim();
+    // Ctrl+D (EOF) → "" = cancelar, no un crash: todas estas preguntas preceden a una
+    // acción hacia afuera (push + PR), y ahí abortar es la respuesta segura.
+    try { return (await _rl.question(q)).trim(); }
+    catch { process.stdout.write("\n"); return ""; }
   };
   const closeRl = () => { if (_rl) { _rl.close(); _rl = null; } };
 
@@ -863,19 +870,53 @@ async function cmdPr(opts) {
     fail(`no hay commits en '${branch}' por encima de '${base}'. Una PR necesita cambios: haz commit primero (git commit).`, 1);
   }
 
-  // 1. Resolver el link (US) de la branch actual.
-  const found = discoverImplements(process.cwd());
-  let entry = null;
-  for (const f of found) for (const im of f.implements || []) {
-    if (!isPlaceholderId(im.id)) { entry = { f, im }; break; }
+  // 1. Resolver el link (US) de ESTA branch (issues #31, #32, #33).
+  //    Antes se recorrían todos los implements.yaml del repo —archivados incluidos— y
+  //    ganaba el último: la branch, que es la que sabe la respuesta, no entraba en la
+  //    decisión. La PR salía titulada con la historia de otro y nadie se enteraba,
+  //    porque el `dai check ✅` del body era el de esa otra US.
+  const rows = flattenImplements(discoverImplements(process.cwd(), { includeArchived: false }));
+  const allRows = flattenImplements(discoverImplements(process.cwd()));
+  const scope = prScope({ branch, rows, allRows, ids: opts.us ? [String(opts.us)] : [] });
+  let entry = scope.target;
+
+  if (scope.mode === "explicit" && !entry) {
+    closeRl();
+    fail(`no encontré implements.yaml para '${opts.us}'.\n` +
+         `  US en este repo: ${allRows.map((r) => r.id).join(", ") || "(ninguna)"}`, 1);
+  }
+  if (scope.mode === "none") {
+    closeRl();
+    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), renombrá la branch a `chore/…` o creá la PR con tu forge: `glab mr create` / `gh pr create`.", 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;
+  if (scope.mode === "ambiguous") {
+    // Elegir en silencio es EL bug: la PR sale publicada con el link QUÉ↔CÓMO de otra US.
+    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) {
+      closeRl();
+      fail("no sé con qué US titular la PR. Decilo explícitamente:  dai pr --us <ID>", 1);
+    }
+    const ans = await ask(`  ¿Con qué US titulo la PR? (número, Enter=cancelar) `);
+    if (!ans) { closeRl(); info("Cancelado — no se creó la PR."); return; }
+    const n = Number(ans);
+    if (!Number.isInteger(n) || n < 1 || n > scope.candidates.length) {
+      closeRl();
+      fail(`respuesta inválida: '${ans}'. Se esperaba un número entre 1 y ${scope.candidates.length}.`, 1);
+    }
+    entry = scope.candidates[n - 1];
+  }
+
+  // De dónde salió la US: en el preview, el título sin justificación no delata nada
+  // cuando está mal (sugerencia del issue #32).
+  const usWhy = entry ? (scope.mode === "ambiguous" ? "la elegiste vos" : scope.reason) : scope.reason;
+  const { id, version, ac_hash } = entry || {};
 
   // 2. Estado de trazabilidad (dai check) contra la US viva.
   const adapter = getAdapter(process.env);
-  const live = await Promise.resolve(adapter.fetchUS(id)).catch(() => null);
-  const status = coverageStatus(ac_hash, live?.ac_hash);
+  const live = id ? await Promise.resolve(adapter.fetchUS(id)).catch(() => null) : null;
+  const status = id ? coverageStatus(ac_hash, live?.ac_hash) : 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`);
@@ -889,22 +930,25 @@ async function cmdPr(opts) {
   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) {
+  const usUrl = id ? usUrlFor(id, live?.url) : null;
+  if (id && !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.dai (p. ej. https://tu-tracker/browse/{id}).`);
   }
   const body = composePrBody(readFileSync(tplPath, "utf8"), {
-    id, version, ac_hash, status, usUrl, usTitle: live?.title, commits,
+    id, version, ac_hash, status, usUrl, usTitle: live?.title, commits, noUsReason: id ? null : scope.reason,
     branch, branchUrl: branchUrl(remote, branch), commit, commitUrl: commitUrl(remote, commit),
   });
-  const title = prTitle(opts, id, live?.title);
+  // Sin US el título sale del último commit: describe lo que hay adentro, en vez de
+  // pedirle prestada la historia a otro (issue #31).
+  const title = prTitle(opts, id, live?.title, commits[0] || branch);
   const forge = detectForge(parseRemote(remote)?.host);
   const tool = forgeTool(forge);
 
   // 4. Mostrar y pedir confirmación (acción hacia afuera).
   process.stdout.write(`\n  ── Pull Request a crear ──────────────────────────────\n`);
   process.stdout.write(`  título:   ${title}\n  de:       ${branch}\n  a:        ${base}\n`);
+  process.stdout.write(`  US:       ${id || C.dim("(sin US)")}  ${C.dim(`— ${usWhy}`)}\n`);
   process.stdout.write(`  forge:    ${forge} (${tool})${opts.assignee ? `\n  asignar:  ${opts.assignee}` : ""}${opts.draft ? "\n  draft:    sí" : ""}\n`);
   process.stdout.write(`  ─────────────────────────────────────────────────────\n\n${body}\n`);
   process.stdout.write(`  ─────────────────────────────────────────────────────\n`);
@@ -1699,6 +1743,7 @@ switch (cmd) {
       "  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" +
+      "      [--us <ID>] [--title t]  la US la resuelve la branch; si hay varias, pregunta (sin TTY, falla)\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/branch-scope.mjs

@@ -56,17 +56,22 @@ export function trackerKeysIn(branch) {
 //   chore/, docs/, ci/…  → nunca
 //   fix/ y el resto → solo si el nombre trae un ID con pinta de key de tracker
 // `main`/`develop`/sin branch → no (no es una branch de trabajo).
+//
+// `kind` distingue POR QUÉ no se exige, que no es lo mismo para todos los comandos:
+// una `chore/` está exenta POR TIPO (el repo declara que ahí no hay producto), mientras
+// que `mi-branch` simplemente no dice nada. `dai pr` usa esa diferencia para no colgarle
+// la US viva del repo a una PR de archivado (issue #31).
 export function requiresLink(branch) {
   const t = branchType(branch);
-  if (ALWAYS.has(t)) return { required: true, reason: `'${t}/' es trabajo de producto: requiere US` };
-  if (EXEMPT.has(t)) return { required: false, reason: `'${t}/' está exenta de US (governance/branch-naming.md)` };
-  if (t === "") return { required: false, reason: "sin prefijo tipo/, no es una branch de trabajo: sin gate de link" };
+  if (ALWAYS.has(t)) return { required: true, kind: "always", reason: `'${t}/' es trabajo de producto: requiere US` };
+  if (EXEMPT.has(t)) return { required: false, kind: "exempt", reason: `'${t}/' está exenta de US (governance/branch-naming.md)` };
+  if (t === "") return { required: false, kind: "untyped", reason: "sin prefijo tipo/, no es una branch de trabajo: sin gate de link" };
   // Tipo desconocido (fix/, spike/, lo que el repo use): si nombró un ID, lo tomamos
   // como intención de implementar una US y se lo exigimos. Si no, no inventamos.
   const keyish = trackerKeysIn(branch).length > 0;
   return keyish
-    ? { required: true, reason: `'${t}/' con un ID en el nombre: se toma como trabajo de producto` }
-    : { required: false, reason: `'${t}/' sin ID en el nombre: no exige US (governance/branch-naming.md)` };
+    ? { required: true, kind: "always", reason: `'${t}/' con un ID en el nombre: se toma como trabajo de producto` }
+    : { required: false, kind: "untyped", reason: `'${t}/' sin ID en el nombre: no exige US (governance/branch-naming.md)` };
 }
 
 // Aplana los implements descubiertos a filas { path, change, repo, id, version, ac_hash },
@@ -142,3 +147,54 @@ export function stampScope({ branch, rows, allRows = rows, ids = [], all = false
     reason: `hay ${hit.length > 1 ? hit.length : rows.length} US vivas y la branch '${branch}' no dice cuál`,
   };
 }
+
+// La decisión de `dai pr`: ¿con qué US se titula y se linkea ESTA PR?
+//
+//   { mode, target, candidates, reason, missing }
+//
+//   mode "explicit"  → el id que pidió el usuario (dai pr --us ABC-482)
+//   mode "branch"    → la branch nombra una US viva del repo: esa
+//   mode "only"      → hay una sola US viva y la branch no está exenta: esa
+//   mode "exempt"    → branch exenta por tipo (chore/, docs/…) que no nombra US: PR SIN US
+//   mode "ambiguous" → varias candidatas y ninguna pista: NO elige, pregunta
+//   mode "none"      → la branch pide US y el repo no tiene ninguna viva
+//
+// Es la misma pregunta que resuelve stampScope, con dos diferencias que importan
+// (issues #31, #32, #33 — antes `dai pr` recorría TODOS los implements.yaml del repo,
+// archivados incluidos, y se quedaba con el último):
+//
+//   1. Una PR implementa UNA US, no cuatro: no hay modo "all", y el resultado es un
+//      único `target`.
+//   2. Una branch exenta NO hereda la US viva del repo. Una PR de `chore/archive-specs`
+//      titulada con la historia de un compañero es peor que una sin título lindo: la
+//      lista de PRs es la única superficie donde el equipo lee la trazabilidad.
+//
+// `rows` viene del discover SIN archivados; `allRows` incluye los archivados y solo se
+// usa para resolver un id explícito (reabrir la PR de un change ya archivado) y para
+// listar qué US conoce el repo cuando el id pedido no está.
+export function prScope({ branch, rows, allRows = rows, ids = [] }) {
+  if (ids.length) {
+    const want = String(ids[0]).toLowerCase();
+    const target = allRows.find((r) => String(r.id).toLowerCase() === want) || null;
+    // `missing` conserva la grafía del usuario: devolverle su ABC-404 en minúsculas lo
+    // manda a dudar del case en vez de del id.
+    return { mode: "explicit", target, candidates: allRows, missing: target ? [] : [ids[0]], reason: `pediste --us ${ids[0]}` };
+  }
+
+  const hit = matchBranchToImplements(branch, rows);
+  if (hit.length === 1) {
+    return { mode: "branch", target: hit[0], candidates: rows, reason: `la branch '${branch}' nombra ${hit[0].id}` };
+  }
+  if (hit.length > 1) {
+    return { mode: "ambiguous", target: null, candidates: hit, reason: `la branch '${branch}' nombra ${hit.length} US vivas` };
+  }
+
+  // La branch no nombra ninguna US viva.
+  const req = requiresLink(branch);
+  if (req.kind === "exempt") {
+    return { mode: "exempt", target: null, candidates: rows, reason: `${req.reason} y su nombre no nombra ninguna US` };
+  }
+  if (rows.length === 0) return { mode: "none", target: null, candidates: [], reason: "no hay implements.yaml vivo en el repo" };
+  if (rows.length === 1) return { mode: "only", target: rows[0], candidates: rows, reason: "es la única US viva del repo" };
+  return { mode: "ambiguous", target: null, candidates: rows, reason: `hay ${rows.length} US vivas y la branch '${branch}' no dice cuál` };
+}

package/cli/lib/pr.mjs

@@ -18,6 +18,7 @@ export function replaceSection(body, heading, content) {
 // placeholders que encuentra y deja el resto para que el humano lo edite.
 export function composePrBody(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}\``);
@@ -32,6 +33,21 @@ export function composePrBody(template, d) {
   return upsertLinksBlock(b, d);
 }
 
+// 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",
+    `- **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 ────────────────────────────────────────────────────────
 // 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
@@ -70,8 +86,12 @@ export function upsertLinksBlock(body, d) {
 }
 
 // Título del PR: el pasado a mano, o "<ID>: <título de la US>", o solo el ID.
-export function prTitle(opts, id, usTitle) {
+// Sin US (branch exenta) cae al `fallback` — el subject del último commit: describe
+// lo que hay adentro. Inventar un título con la US de otro es el bug de los issues
+// #31/#33, y el título es lo ÚNICO que se ve en la lista de PRs.
+export function prTitle(opts, id, usTitle, fallback = "") {
   if (opts.title) return opts.title;
+  if (!id) return fallback;
   if (usTitle) return `${id}: ${usTitle}`;
   return id;
 }

package/docs/tutoriales/index.md

@@ -2,6 +2,15 @@
 
 Guías de **setup operativo** — lo que haces una vez por máquina para trabajar con dai.
 
+## De cero a publicar
+
+- [**Setup para analistas funcionales y PMs (Windows)**](./setup-funcional) — el camino
+  completo sin git ni repositorio: Node, dai, las skills en Copilot, el token de Jira y una
+  épica + US de prueba publicadas de verdad.
+- [**Setup para desarrolladores (Windows)**](./setup-dev) — el otro lado: Node, dai, git + SSH
+  + `glab`, las skills en Copilot, OpenSpec y el ciclo completo sobre una US real
+  (`link-us` → `check` → `mr` → `stamp`).
+
 ## Preparar el entorno
 
 - [**Configurar git**](./configurar-git) — tu identidad (nombre + correo) para que los