@dforce2055/dai 0.11.0 → 0.13.0

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/link-us.mjs

@@ -41,7 +41,9 @@ export function extractTitle(md) {
 
 // Render del implements.yaml (schema ADR-0004).
 export function renderImplementsYaml({ change, repo, id, version = "v1", ac_hash, autor }) {
-  return `# Link QUÉ↔CÓMO · scaffoldeado por dai link-us. El ÚNICO link autorado a mano.
+  return `# Link QUÉ↔CÓMO · scaffoldeado por dai link-us. El ÚNICO link AUTORADO del método:
+# lo escribe alguien, no se deriva. Todo lo de abajo ya está resuelto salvo 'introduces',
+# que se completa AL TERMINAR de implementar — recién ahí se sabe qué se introdujo.
 # Schema: docs/adr/0004-ubicacion-y-schema-implements.md
 change: ${change}
 repo:   ${repo}
@@ -52,7 +54,8 @@ implements:
     ac_hash: ${ac_hash}
 
 introduces:
-  - <capacidad-tecnica>   # completar: specs técnicas nuevas de este change
+  - <capacidad-tecnica>   # al cerrar la implementación: capacidades técnicas nuevas
+                          # (o borrá el bloque si no hay ninguna)
 
 autor: ${autor}
 `;

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/EJEMPLO-END-TO-END.md

@@ -157,7 +157,7 @@ $ dai link-us ABC-482 --us us.md --change finalizar-compra
 ```
 
 ```yaml
-# implements.yaml — el ÚNICO link autorado a mano (schema ADR-0004)
+# implements.yaml — el ÚNICO link AUTORADO: se escribe, no se deriva (schema ADR-0004)
 change: finalizar-compra
 repo:   frontend
 

package/docs/glosario.md

@@ -20,7 +20,7 @@
 | Término | Qué es |
 |---|---|
 | **Link (QUÉ↔CÓMO)** | La relación entre un requerimiento y su implementación. |
-| **`implements`** | La declaración `implements: <id>@<version>` en el código. El **único** link autorado a mano. |
+| **`implements`** | La declaración `implements: <id>@<version>` en el código. El **único** link autorado (se escribe, no se deriva): lo scaffoldea `dai link-us` y se cierra al terminar de implementar. |
 | **`implements.yaml`** | El archivo, en el change del repo, que contiene ese link. Lo genera `link-us`. Ejemplo lleno + árbol de dónde vive entre los artefactos de OpenSpec: [ADR-0004](adr/0004-ubicacion-y-schema-implements.md). |
 | **Trazabilidad inversa / cobertura** | El mapa "quién implementó este QUÉ". **Se genera, nunca se escribe.** |
 | **Índice / router** | La tabla central que dice qué ID vive en qué repos. Es un router, **no un almacén**: no guarda el detalle. |

package/docs/guias/dev.md

@@ -7,7 +7,10 @@
 
 - El **CÓMO**: diseño técnico, modelo de datos, arquitectura de la solución.
 - Las **tareas técnicas** (las derivas tú, desde la US, con OpenSpec).
-- El **link** (`implements.yaml`): es el **único** que se autora a mano ([Art. 9](../MANIFIESTO.md#art-9)).
+- El **link** (`implements.yaml`): es el **único** que se autora, no se deriva ([Art. 9](../MANIFIESTO.md#art-9)).
+  `dai link-us` lo scaffoldea con el `id`/`version`/`ac_hash` ya resueltos; lo único que queda
+  abierto es `introduces`, y se cierra **al terminar de implementar** —normalmente lo completa
+  el agente que implementó, y tú lo revisas en la PR—.
 - El **código** y su **spec técnica**.
 
 ## Lo que NO tocas
@@ -88,3 +91,10 @@ que está junto a tu `implements.yaml`.
 - `dai check` · `dai pr` · `dai stamp` · `dai done` (limpieza, opcional)
 - `dai update-us` — empuja al tracker una US que refinaste implementando
 - `definition-of-done.md`
+
+> **Ojo con el nombre de los comandos `opsx`.** Acá se escriben en la forma de Claude Code
+> (`/opsx:apply`). En **Copilot y Cursor** los mismos comandos van **con guion**:
+> `/opsx-apply`. No es un alias: es el nombre del archivo que genera OpenSpec para cada
+> asistente. Con la forma equivocada el agente no encuentra el comando, no carga el workflow
+> y se pone a improvisar sin avisar. `dai init` te dice cuál te toca.
+

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