@dforce2055/dai 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -3,6 +3,151 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/). Versionado semver
 (ver `VERSION`).
 
+## [0.13.0] — 2026-08-21
+
+**Un dev de backend en Windows siguió el tutorial al pie de la letra y el agente se puso a
+programar sin escribir la propuesta. No era Windows ni era su setup: le estábamos diciendo mal
+el nombre del comando.**
+
+### Arreglado
+- **Los comandos de OpenSpec se documentaban solo en la forma de Claude Code.** OpenSpec
+  genera un archivo distinto por asistente, y el nombre del comando sale del archivo:
+  `.claude/commands/opsx/<id>.md` → `/opsx:propose`, pero
+  `.github/prompts/opsx-<id>.prompt.md` → `/opsx-propose` (Copilot) y
+  `.cursor/commands/opsx-<id>.md` → `/opsx-propose` (Cursor). O sea: **solo Claude usa los
+  dos puntos**, y el tutorial de setup del dev —que es el de Windows + Copilot— mostraba los
+  dos puntos en los tres pasos.
+  El síntoma no se parece en nada a la causa, y ahí está el daño: tipear `/opsx:propose` en
+  Copilot **no da error**. No matchea ningún comando, el workflow nunca se carga, y el agente
+  toma el texto suelto como una charla — se saltea el gate propose → aprobación → apply y
+  arranca a implementar. Se lee como "el bot hace lo que quiere" y se le echa la culpa al
+  asistente, al sistema operativo o al método. Es vibe coding servido por la documentación.
+  Ahora `dai init` imprime la forma que le toca a **tu** asistente (`opsxHint`), el tutorial
+  de Windows lo dice explícito con su propia entrada en *Cuando algo falla*, y la guía del
+  dev aclara que la forma con dos puntos es la de Claude.
+- **`dai check` terminaba con código de error en Windows aunque el chequeo pasara**
+  (`Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c, line 94`).
+  Salía con `process.exit()` inmediatamente después del `fetch` al tracker, y en Windows eso
+  aborta el proceso mientras undici todavía está desarmando sus handles. Imprimía
+  `✅ al día` y devolvía distinto de cero igual: un gate verde reportado como rojo en CI o en
+  un hook de git — justo el modo de falla que apaga un gate.
+  Ahora el código de salida se fija con `process.exitCode` y el event loop drena solo. Cuesta
+  ~40 ms (los sockets keep-alive de undici están *unref'd*) y no cambia nada en macOS/Linux.
+  El mismo tratamiento va para los `.catch()` del dispatcher de **todos** los comandos que
+  salen a la red o spawnean npm (`link-us`, `stamp`, `update-us`, `edit-us`, `forge`,
+  `publish`, `pr`/`mr`, `install`, `init`), con `failSoft()`: ahí el comando ya terminó, así
+  que cortar de una no aportaba nada y podía tapar el mensaje de error con un stack de C.
+  Adentro de un comando `fail()` sigue saliendo de una — ahí sí hay que no volver.
+
+### Agregado
+- **Regla nueva en la constitución: *el diseño se aprueba antes de implementar*.** Al terminar
+  la propuesta el agente para y pide aprobación explícita; si no tiene una herramienta para
+  preguntar, pregunta en texto plano y espera. Vale para los tres asistentes. Es el borde
+  QUÉ↔CÓMO, que sí es dominio de dai: sin esa firma, la implementación no tiene contra qué
+  revisarse — y el gate no puede depender de que el asistente de turno tenga la herramienta
+  correcta. Los repos ya inicializados la reciben con `dai sync`.
+- **`dai doctor` avisa si OpenSpec está por debajo de 1.10.0.** Hasta esa versión, los prompts
+  que OpenSpec generaba para Copilot y Cursor nombraban los comandos en la forma de Claude
+  (`/opsx:apply`, que ahí no existe) e invocaban `AskUserQuestion`/`TodoWrite`, que solo tiene
+  Claude Code. El agente terminaba nombrando comandos inexistentes y salteándose el gate de
+  aprobación porque su única forma de preguntar no existía. Está arreglado upstream
+  ([#727](https://github.com/Fission-AI/OpenSpec/issues/727),
+  [#1307](https://github.com/Fission-AI/OpenSpec/issues/1307),
+  [#1103](https://github.com/Fission-AI/OpenSpec/issues/1103)), pero un equipo que instaló
+  antes se queda con la versión vieja y el síntoma no se parece a la causa.
+- **`dai doctor` reporta los comandos de OpenSpec**, con la forma que le toca a **este** repo:
+  `✓ Copilot: /opsx-explore · /opsx-propose · /opsx-apply · /opsx-archive`. Si no están
+  generados, dice el comando exacto para generarlos —con el tool id que espera OpenSpec, que
+  para Copilot es `github-copilot` y no `copilot`—. Solo mira los asistentes configurados en
+  el repo: tener las skills instaladas globalmente no dice nada de los comandos, que son
+  archivos versionados.
+
+### Cambiado
+- **`introduces` se cierra al TERMINAR de implementar, y lo normal es que lo escriba el
+  agente.** El tutorial del dev pedía completarlo justo después de `dai link-us` — cuando
+  todavía no se puede saber qué capacidades técnicas va a introducir el change; al empezar
+  sería adivinar. Y la skill `link-us` decía explícito "dejar `introduces` para que el dev lo
+  liste", cargándole a mano un dato que sabe mejor quien acaba de implementar.
+  La frase "el único archivo que se autora **a mano**" empujaba el malentendido: lo que dice
+  el ADR-0004 es que es el único registro **autorado** —se escribe, no se deriva—, y `link-us`
+  ya resuelve `id`, `version`, `ac_hash`, `change`, `repo` y `autor` por construcción.
+  Ahora lo dicen igual el archivo generado, la skill, su template, el tutorial (con el paso de
+  cierre después de `/opsx-apply`), la guía del dev, el glosario y el ejemplo end-to-end. El
+  **DoD suma el ítem**: `introduces` cerrado, sin el placeholder `<capacidad-tecnica>`.
+- **El DoD nombra los comandos de OpenSpec sin atarlos a un asistente.** Decía
+  `opsx:apply` → `opsx:archive`, la forma de Claude, en un template que viaja a los tres.
+- **`DAI_JIRA_FIELDS_FILE` sale comentada en el `.env.dai` que genera `dai init`.** Apuntaba
+  al mismo valor que ya usa el CLI por defecto, así que no aportaba nada — pero hacía creer
+  que faltaba un archivo obligatorio, y un dev terminó pidiendo los `customfield_*` de la
+  empresa para un archivo que **solo hace falta para crear** US, no para leerlas.
+
+### Interno
+- **325 tests** (+6 desde 0.12.0): `opsxCommand` y `opsxHint` —que solo Claude lleva los dos
+  puntos, y la línea combinada de `dai init` cuando el repo configura varios asistentes—, el
+  archivo y el tool id de OpenSpec por asistente (`github-copilot`, que no es `copilot`),
+  `OPENSPEC_MIN`, que `DAI_JIRA_FIELDS_FILE` salga comentada, y que la regla nueva de la
+  constitución llegue a los tres asistentes.
+
+## [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 +696,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.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
 [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.13.0

package/cli/dai.mjs

@@ -30,12 +30,12 @@ import { parseFindings, diffPositions, validateFindings, filterFindings, renderF
 import { composePrBody, prTitle, forgeTool } from "./lib/pr.mjs";
 import { dirsEqual } from "./lib/fsutil.mjs";
 import { parseFlags, parseAssistants, isAssistantToken, asList } from "./lib/args.mjs";
-import { versionDrift, planUpgrade } from "./lib/semver.mjs";
+import { versionDrift, planUpgrade, compareVersions } from "./lib/semver.mjs";
 import { parseSource } from "./lib/skills-source.mjs";
-import { skillToCursor, validateSkill, constitution, constitutionCursorRule, envFor, mergeEnv, upsertBlock, reconcileGitignore, stalePromptFiles } from "./lib/bootstrap.mjs";
+import { skillToCursor, validateSkill, constitution, constitutionCursorRule, envFor, mergeEnv, upsertBlock, reconcileGitignore, stalePromptFiles, opsxHint, opsxCommand, OPSX_COMMAND_FILE, OPENSPEC_TOOL, OPENSPEC_MIN } 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";
 
@@ -45,6 +45,13 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 process.stdout.on("error", (e) => { if (e.code === "EPIPE") process.exit(0); throw e; });
 
 function fail(msg, code = 1) { process.stderr.write("dai: " + msg + "\n"); process.exit(code); }
+
+// Igual que fail(), pero sin process.exit(). Lo usan los `.catch()` del dispatcher: ahí el
+// comando YA terminó, así que cortar de una no aporta nada y en Windows cuesta caro — salir
+// de golpe después de un fetch (o de un spawn de npm) aborta el proceso con un assert de
+// libuv y tapa el mensaje de error con un stack de C. Ver la nota en cmdCheckCi.
+// Adentro de un comando `fail()` sigue siendo lo correcto: ahí sí hay que no volver.
+function failSoft(msg, code = 1) { process.stderr.write("dai: " + msg + "\n"); process.exitCode = code; }
 const ok = (m) => process.stdout.write(`✓ ${m}\n`);
 const info = (m) => process.stdout.write(`› ${m}\n`);
 const warn = (m) => process.stdout.write(`⚠ ${m}\n`);
@@ -219,6 +226,13 @@ function gitCommit() { try { return git(["rev-parse", "HEAD"]); } catch { return
 // Quién decide es requiresLink(), leyendo el nombre de la branch.
 //
 // Salidas:  0 = pasa · 1 = falta el link · 2 = hay link pero el QUÉ cambió (atrasado)
+//
+// El código de salida se fija con `process.exitCode`, NO con `process.exit()`. En Windows,
+// salir de golpe justo después de un fetch aborta el proceso con un assert de libuv
+// (`!(handle->flags & UV_HANDLE_CLOSING)`, src\win\async.c) mientras undici todavía está
+// desarmando sus handles. El gate imprimía "al día" y devolvía distinto de cero igual: un
+// verde reportado como rojo en CI o en un hook. Dejar que el loop drene solo cuesta ~40ms
+// (los sockets keep-alive de undici están unref'd) y no cambia nada en macOS/Linux.
 async function cmdCheckCi(opts = {}) {
   const branch = opts.branch || process.env.DAI_CI_BRANCH || ciBranch() || gitBranch();
   const { required, reason } = requiresLink(branch);
@@ -227,7 +241,7 @@ async function cmdCheckCi(opts = {}) {
   info(`branch '${branch || "(desconocida)"}' — ${reason}`);
   if (!required) {
     if (rows.length) info(`igual declara ${rows.length} US (${rows.map((r) => r.id).join(", ")}) — se chequea su cobertura.`);
-    else { ok("gate OK — esta branch no requiere US."); process.exit(0); }
+    else { ok("gate OK — esta branch no requiere US."); return; }
   }
   if (required && rows.length === 0) {
     const ids = trackerKeysIn(branch);
@@ -236,7 +250,7 @@ async function cmdCheckCi(opts = {}) {
       `    Crealo:  dai link-us ${ids[0] || "<ID-DE-LA-US>"}\n` +
       "    Si NO implementa una US (tooling, deps, docs), renombrá la branch con un\n" +
       "    prefijo exento — chore/, docs/, ci/ — según governance/branch-naming.md.\n");
-    process.exit(1);
+    process.exitCode = 1; return;
   }
 
   // Hay link: que además esté al día contra la US viva. Sin token/backend eso no se
@@ -244,7 +258,7 @@ async function cmdCheckCi(opts = {}) {
   // con --no-network (o sin adaptador utilizable) valida el link y no más.
   if (opts.noNetwork) {
     ok(`gate OK — ${rows.length} US linkeada(s): ${rows.map((r) => r.id).join(", ")} (--no-network: no se comparó contra la US viva).`);
-    process.exit(0);
+    process.exitCode = 0; return;
   }
   loadDaiEnv();
   let adapter;
@@ -252,7 +266,7 @@ async function cmdCheckCi(opts = {}) {
   catch (e) {
     warn(`no puedo comparar contra la US viva: ${e.message}`);
     ok(`gate OK igual — el link existe (${rows.map((r) => r.id).join(", ")}). Configurá el backend para chequear también el atraso.`);
-    process.exit(0);
+    process.exitCode = 0; return;
   }
   let worst = 0;
   for (const r of rows) {
@@ -271,7 +285,7 @@ async function cmdCheckCi(opts = {}) {
     }
   }
   if (worst === 0) ok(`gate OK — ${rows.length} US linkeada(s) y al día.`);
-  process.exit(worst);
+  process.exitCode = worst;
 }
 
 // La branch real en CI: en una PR, HEAD es un merge commit detached, así que
@@ -285,6 +299,7 @@ function ciBranch() {
 }
 
 // ── check ──────────────────────────────────────────────────────────────────
+// `process.exitCode` en vez de `process.exit()`: ver la nota en cmdCheckCi.
 async function cmdCheck() {
   loadDaiEnv();
   const adapter = getAdapter(process.env);
@@ -312,7 +327,7 @@ async function cmdCheck() {
     for (const id of atrasadas) process.stdout.write(`    dai link-us ${id} --resync     # re-estampa el ac_hash contra la US viva\n`);
     process.stdout.write("  Después, revisa si tu implementación cubre el criterio nuevo.\n");
   }
-  process.exit(worst);
+  process.exitCode = worst;
 }
 
 // ── stamp ──────────────────────────────────────────────────────────────────
@@ -802,8 +817,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 +867,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 +885,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 (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];
   }
-  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;
+
+  // 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 +945,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`);
@@ -1219,7 +1278,7 @@ async function cmdInit(repo, opts) {
   let installOpenspec = opts.openspec === true;
   if (!hasOpenspec && opts.openspec === undefined && rl) {
     process.stdout.write("\n  OpenSpec es el motor recomendado del CÓMO: convierte la US en design + tasks\n");
-    process.stdout.write("  (comandos /opsx:*). No está en este repo — la trazabilidad de dai anda igual sin\n");
+    process.stdout.write(`  (${opsxHint(want)}). No está en este repo — la trazabilidad de dai anda igual sin\n`);
     process.stdout.write("  él, pero para el flujo completo conviene tenerlo.\n");
     installOpenspec = await askYesNo(rl, "¿Instalar el CLI de OpenSpec ahora? (después ejecutas `openspec init` tú)", false);
   }
@@ -1322,7 +1381,7 @@ async function cmdInit(repo, opts) {
     .filter(Boolean).join(",") || "claude,github-copilot,cursor";
   const osHint = "para sumarlo después:  npm i -g @fission-ai/openspec@latest  &&  openspec init --tools " + osTools;
   if (hasOpenspec) {
-    ok("OpenSpec:     ya inicializado en el repo");
+    ok(`OpenSpec:     ya inicializado en el repo — ${opsxHint(want)}`);
   } else if (openspecPartial) {
     warn("OpenSpec:     hay una carpeta openspec/ a medias. Reinicializa: rm -rf openspec && openspec init --tools " + osTools + " --force");
   } else if (installOpenspec) {
@@ -1335,7 +1394,7 @@ async function cmdInit(repo, opts) {
       try {
         info(`OpenSpec:     inicializando en el repo (--tools ${osTools})…`);
         runNpmTool("openspec", ["init", "--tools", osTools, "--force"], { stdio: "inherit", cwd: repo === "." ? process.cwd() : repo });
-        ok("OpenSpec:     instalado e inicializado — genera design/tasks con /opsx:*");
+        ok(`OpenSpec:     instalado e inicializado — genera design/tasks con ${opsxHint(want)}`);
       } catch {
         warn("OpenSpec:     el CLI está pero falló `openspec init`. Ejecuta a mano en el repo:");
         process.stdout.write(`                  openspec init --tools ${osTools} --force\n`);
@@ -1601,6 +1660,43 @@ function cmdDoctor() {
     else warn("falta constitución Cursor (dai-constitution.mdc)");
   }
 
+  // OpenSpec: los comandos que arman el CÓMO. Se reportan acá porque su nombre CAMBIA
+  // según el asistente, y con la forma equivocada el agente no falla — no encuentra nada,
+  // no avisa, y se pone a improvisar salteándose el gate. Verlo escrito ahorra la tarde.
+  const OPSX_IDS = ["explore", "propose", "apply", "archive"];
+  const opsxPath = (kind, id) => join(cwd, ...OPSX_COMMAND_FILE[kind].replace("<id>", id).split("/"));
+  // Solo los asistentes configurados EN ESTE REPO: los comandos opsx son archivos del
+  // repo, así que tener las skills globales no dice nada sobre ellos. Avisar por los otros
+  // dos le pone dos warnings falsos a quien configuró uno solo, que es el caso normal.
+  const localActive = ASSISTANTS.filter((a) => skillNames.some((n) => existsSync(join(a.local, n))));
+  if (localActive.length && existsSync(join(cwd, "openspec"))) {
+    info("OpenSpec — los comandos van en el chat del asistente, no en la terminal:");
+    for (const a of localActive) {
+      const faltan = OPSX_IDS.filter((id) => !existsSync(opsxPath(a.kind, id)));
+      if (faltan.length === OPSX_IDS.length) {
+        warn(`${a.label}: no hay comandos opsx. Generalos:  openspec init --tools ${OPENSPEC_TOOL[a.kind]} --force`);
+      } else {
+        const hay = OPSX_IDS.filter((id) => existsSync(opsxPath(a.kind, id)));
+        ok(`${a.label}: ${hay.map((id) => opsxCommand(a.kind, id)).join(" · ")}`);
+        if (faltan.length) warn(`${a.label}: faltan ${faltan.join(", ")} — regenerá con \`openspec init --tools ${OPENSPEC_TOOL[a.kind]} --force\``);
+      }
+    }
+    process.stdout.write("    (el nombre sale del archivo que genera OpenSpec: solo Claude usa los dos puntos)\n");
+    // La versión importa para algo más que features: hasta OPENSPEC_MIN, los prompts que
+    // OpenSpec genera para Copilot/Cursor decían `/opsx:apply` (la forma de Claude, que ahí
+    // no existe) e invocaban herramientas que solo tiene Claude Code. El agente terminaba
+    // nombrando comandos inexistentes y salteándose el gate de aprobación sin avisar.
+    let osV = null;
+    try { osV = String(runNpmTool("openspec", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }) ?? "").trim(); } catch { /* sin CLI */ }
+    if (!osV) info("el CLI de OpenSpec no está en el PATH (los comandos igual viven en el repo)");
+    else if (compareVersions(osV, OPENSPEC_MIN) === -1) {
+      warn(`OpenSpec ${osV} — actualiza a ${OPENSPEC_MIN} o mayor:  npm i -g @fission-ai/openspec@latest`);
+      process.stdout.write("    Hasta esa versión, los prompts de Copilot y Cursor nombraban los comandos en la\n");
+      process.stdout.write("    forma de Claude y pedían herramientas que esos asistentes no tienen: el agente se\n");
+      process.stdout.write("    saltea el gate de aprobación y se pone a implementar sin avisar.\n");
+    } else ok(`OpenSpec ${osV}`);
+  }
+
   info("adaptador de PM:");
   const pm = process.env.DAI_PM || "md";
   ok(`DAI_PM=${pm}`);
@@ -1649,23 +1745,23 @@ const { opts, pos } = parseFlags(rest);
 switch (cmd) {
   case "ac-hash": cmdAcHash(pos[0]); break;
   case "ls":      cmdLs(opts); break;
-  case "link-us": cmdLinkUs(pos[0], opts).catch((e) => fail(String(e.message))); break;
-  case "check":   (opts.ci ? cmdCheckCi(opts) : cmdCheck()).catch((e) => fail(String(e.message))); break;
-  case "stamp":   cmdStamp(pos, opts).catch((e) => fail(String(e.message))); break;
-  case "update-us": cmdUpdateUs(pos[0], opts).catch((e) => fail(String(e.message))); break;
-  case "edit-us": cmdEditUs(pos[0], opts).catch((e) => fail(String(e.message))); break;
-  case "forge":   cmdForge(pos[0], pos[1], opts).catch((e) => fail(String(e.message))); break;
-  case "publish": cmdPublish(pos[0], opts).catch((e) => fail(String(e.message))); break;
+  case "link-us": cmdLinkUs(pos[0], opts).catch((e) => failSoft(String(e.message))); break;
+  case "check":   (opts.ci ? cmdCheckCi(opts) : cmdCheck()).catch((e) => failSoft(String(e.message))); break;
+  case "stamp":   cmdStamp(pos, opts).catch((e) => failSoft(String(e.message))); break;
+  case "update-us": cmdUpdateUs(pos[0], opts).catch((e) => failSoft(String(e.message))); break;
+  case "edit-us": cmdEditUs(pos[0], opts).catch((e) => failSoft(String(e.message))); break;
+  case "forge":   cmdForge(pos[0], pos[1], opts).catch((e) => failSoft(String(e.message))); break;
+  case "publish": cmdPublish(pos[0], opts).catch((e) => failSoft(String(e.message))); break;
   case "pr":
-  case "mr":      cmdPr(opts).catch((e) => fail(String(e.message))); break;   // `mr` = alias para GitLab (merge request)
+  case "mr":      cmdPr(opts).catch((e) => failSoft(String(e.message))); break;   // `mr` = alias para GitLab (merge request)
   case "done":    cmdDone(opts); break;
   case "archive": cmdArchive(pos[0], opts); break;
-  case "install": cmdInstall(opts).catch((e) => fail(String(e.message))); break;   // alias de `dai skills install`
+  case "install": cmdInstall(opts).catch((e) => failSoft(String(e.message))); break;   // alias de `dai skills install`
   case "skills":
-    if (pos[0] === "install" || pos[0] === undefined) cmdInstall(opts).catch((e) => fail(String(e.message)));
+    if (pos[0] === "install" || pos[0] === undefined) cmdInstall(opts).catch((e) => failSoft(String(e.message)));
     else fail(`subcomando de skills desconocido: '${pos[0]}' (por ahora: install)`, 2);
     break;
-  case "init":    cmdInit(pos[0], opts).catch((e) => fail(String(e.message))); break;
+  case "init":    cmdInit(pos[0], opts).catch((e) => failSoft(String(e.message))); break;
   case "sync":    cmdSync(pos[0], opts); break;
   case "upgrade":
   case "update":  cmdUpgrade(opts); break;
@@ -1699,6 +1795,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/bootstrap.mjs

@@ -106,6 +106,44 @@ export function validateSkill(md) {
 // cada `/comando` con una copia vieja y sin templates.
 export const stalePromptFiles = (skills) => skills.map((n) => `${n}.prompt.md`);
 
+// OpenSpec nombra sus comandos DISTINTO según el asistente, y no es cosmético:
+//   Claude  .claude/commands/opsx/<id>.md         → /opsx:propose   (namespace anidado)
+//   Copilot .github/prompts/opsx-<id>.prompt.md   → /opsx-propose   (nombre aplanado)
+//   Cursor  .cursor/commands/opsx-<id>.md         → /opsx-propose
+// Tipear `/opsx:propose` en Copilot no matchea NADA: el agente no carga el workflow y se
+// pone a improvisar — se saltea el gate propose → aprobación → apply sin avisarle a nadie.
+// Decirle la forma correcta al dev es la diferencia entre el método y vibe coding.
+export function opsxCommand(kind, name = "propose") {
+  return kind === "claude" ? `/opsx:${name}` : `/opsx-${name}`;
+}
+
+// El archivo del que sale ese nombre — lo que hay que mirar cuando el comando "no existe".
+export const OPSX_COMMAND_FILE = {
+  claude:  ".claude/commands/opsx/<id>.md",
+  copilot: ".github/prompts/opsx-<id>.prompt.md",
+  cursor:  ".cursor/commands/opsx-<id>.md",
+};
+
+// Desde esta versión, OpenSpec escribe el nombre del comando que ENTIENDE cada asistente
+// dentro del cuerpo del prompt (antes todos decían `/opsx:apply`, la forma de Claude) y no
+// invoca herramientas que solo existen en Claude Code (`AskUserQuestion`, `TodoWrite`).
+// Con una anterior, un dev de Copilot ve un agente que le nombra comandos inexistentes y
+// que se pasa de largo el gate de aprobación porque su única forma de preguntar no existe.
+export const OPENSPEC_MIN = "1.10.0";
+
+// El id con el que OpenSpec conoce a cada asistente en `openspec init --tools`.
+export const OPENSPEC_TOOL = { claude: "claude", copilot: "github-copilot", cursor: "cursor" };
+
+// La misma info, resumida para una sola línea de `dai init` (que puede haber configurado
+// varios asistentes a la vez).
+export function opsxHint(want, name = "propose") {
+  const dash = [want?.copilot && "Copilot", want?.cursor && "Cursor"].filter(Boolean).join(" y ");
+  const forms = [];
+  if (want?.claude) forms.push(`${opsxCommand("claude", name)} (Claude)`);
+  if (dash) forms.push(`${opsxCommand("copilot", name)} (${dash})`);
+  return forms.join(" · ") || opsxCommand("claude", name);
+}
+
 // Transforma un SKILL.md (Claude) en un SKILL.md de Cursor.
 // Conserva name/description/body y ajusta solo el frontmatter.
 export function skillToCursor(md) {
@@ -140,8 +178,10 @@ export function envFor(pm) {
       "# La clave del PROYECTO (p. ej. PROJ), no la de un ticket (PROJ-123).\n" +
       "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";
+      "# Solo si tu Jira exige campos propios AL CREAR una US (lo usa grill-user-story,\n" +
+      "# no hace falta para leerlas). El default ya es .dai/jira-fields.json; descomentá\n" +
+      "# solo para apuntar a otra ruta. Si el archivo no existe, se ignora.\n" +
+      "# DAI_JIRA_FIELDS_FILE=.dai/jira-fields.json\n";
   }
   return head + "DAI_PM=md\nDAI_MD_US_DIR=.dai/us\n";
 }
@@ -230,6 +270,7 @@ export function constitution(kind) {
 ## Reglas
 
 - **No vibe coding:** toda implementación arranca de una US con criterios testeables.
+- **El diseño se aprueba antes de implementar:** cuando termines la propuesta (proposal / design / tasks), **para y pide aprobación explícita**. No sigas de largo porque "ya está claro": el CÓMO lo firma la persona, y una implementación que empieza antes de esa firma no tiene contra qué revisarse. Si no tienes una herramienta para preguntar, pregunta en texto plano y espera la respuesta.
 - **TDD:** test primero, por la interfaz pública; sobrevive a un refactor.
 - **El link se autora una vez** (\`implements.yaml\`); la cobertura se **deriva** (nunca a mano).
 - **Verifica el comportamiento, no solo que compile:** que pase el chequeo estático o el build no prueba que funcione; ejercita el flujo real antes de darlo por hecho.