@dforce2055/dai 0.12.0 → 0.13.1

package/CHANGELOG.md

@@ -3,6 +3,132 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/). Versionado semver
 (ver `VERSION`).
 
+## [0.13.1] — 2026-08-24
+
+**Un dev en Windows no podía pushear contra el GitLab de su empresa. `ssh -T` le autenticaba
+perfecto, `git push` moría con `Permission denied (publickey…)`. Dos días buscando el problema
+en la clave, en el token y en los permisos del server: no estaba en ninguno de los tres, y dai
+tapaba la única línea que lo decía.**
+
+Su clave tenía passphrase. En Windows conviven dos `ssh.exe` — el de OpenSSH for Windows, que
+habla con el servicio `ssh-agent`, y el que trae Git for Windows, que no lo ve. `ssh -T` usaba
+el primero (la firma la hacía el agente, passphrase nunca), `git push` usaba el segundo y pedía
+la passphrase por stderr. Ese prompt caía en un pipe de dai: el dev veía un cuelgue sin
+explicación, ssh se rendía, caía a autenticación por password y lo único legible al final era
+un error que acusa a la clave. Todo lo que hacía falta para resolverlo estaba en pantalla, y no
+llegaba.
+
+### Arreglado
+- **`dai pr` se tragaba lo que git y ssh preguntan.** El push corría con `stderr` en `pipe`
+  para no ensuciar la salida, pero git y ssh **preguntan por stderr**: la passphrase de una
+  clave, la confirmación de un host nuevo, el aviso del credential manager. Con el prompt
+  invisible el comando no se cuelga por un bug, se cuelga esperando una respuesta que nadie
+  sabe que tiene que dar. Ahora `stderr` va heredado y el push pregunta a la vista. El error de
+  git se lee en vivo, cuando todavía sirve, en vez de aparecer resumido después del fracaso.
+- **La pista al fallar el push asumía que el remoto era HTTPS.** Decía siempre *"si es la
+  primera vez contra este remoto, autenticá pusheando a mano una vez"*. Eso arregla HTTPS,
+  donde el credential manager pide la credencial la primera vez. Contra un remoto **SSH** el
+  push a mano falla exactamente igual — así que la pista mandaba a repetir un comando condenado
+  y a seguir buscando en el lugar equivocado. Ahora el consejo depende del transporte: en SSH
+  aclara que el token de `gh`/`glab` no interviene en el push, que lo que hay que mirar es la
+  clave, y deriva a `dai doctor`.
+
+### Agregado
+- **`dai doctor` — sección `forge`.** Reporta el remoto `origin` con su forge detectado y, en
+  Windows con remoto SSH, **qué `ssh.exe` va a usar git**: si es el suyo (el de Git for
+  Windows, que no llega al `ssh-agent`), lo advierte, explica el modo de falla y da el fix
+  (`git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"`). Respeta la
+  precedencia real de git —`GIT_SSH_COMMAND` > `GIT_SSH` > `core.sshCommand`— y avisa cuando
+  una variable de entorno está pisando un `core.sshCommand` que ya estaba bien: ese caso es
+  particularmente cruel, porque el dev arregla el config, no funciona, y mirando el
+  `.gitconfig` no hay nada que ver. Fuera de Windows, o con un remoto HTTPS, no opina.
+  Núcleo puro y testeado en `cli/lib/git-ssh.mjs` (14 tests); en `dai.mjs` queda solo el I/O.
+
+## [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
@@ -611,6 +737,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.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
 [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

package/VERSION

@@ -1 +1 @@
-0.12.0
+0.13.1

package/cli/dai.mjs

@@ -28,11 +28,12 @@ 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 { diagnoseGitSsh, pushFailureHint, WINDOWS_OPENSSH } from "./lib/git-ssh.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, prScope, matchBranchToImplements, requiresLink, trackerKeysIn } from "./lib/branch-scope.mjs";
@@ -45,6 +46,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 +227,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 +242,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 +251,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 +259,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 +267,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 +286,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 +300,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 +328,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 ──────────────────────────────────────────────────────────────────
@@ -975,11 +991,21 @@ async function cmdPr(opts) {
     // stdin heredado + GIT_TERMINAL_PROMPT=1: la PRIMERA vez contra un remoto HTTPS
     // corporativo, git/credential-manager necesita poder pedir la credencial. Con stdin
     // ignorado (el default de git()) el login no completaba y el push fallaba en seco.
-    git(["push", "-u", "origin", branch], { stdio: ["inherit", "pipe", "pipe"], env: { ...process.env, GIT_TERMINAL_PROMPT: "1" } });
+    //
+    // stderr heredado, y esto no es cosmético: git y ssh PREGUNTAN por stderr. Con
+    // stderr en 'pipe' el prompt de una clave con passphrase ("Enter passphrase for
+    // key …") caía en el pipe, invisible: el dev veía un cuelgue sin explicación, ssh
+    // se rendía y terminaba cayendo a autenticación por password, y lo único que se
+    // llegaba a leer era un "Permission denied (publickey…)" que acusa a la clave
+    // cuando la clave estaba bien. Que pregunte a la vista.
+    git(["push", "-u", "origin", branch], { stdio: ["inherit", "pipe", "inherit"], env: { ...process.env, GIT_TERMINAL_PROMPT: "1" } });
   } catch (e) {
-    const err = String(e.stderr || e.message || "").trim();
+    // git ya imprimió su error en vivo (stderr heredado); acá solo va la pista, y esa
+    // pista depende del transporte: "pushea a mano una vez" arregla HTTPS y no arregla
+    // nada en SSH, donde el push a mano falla igual (lib/git-ssh.mjs).
+    const err = String(e.stderr || "").trim();
     if (err) process.stderr.write("  " + err.split("\n").join("\n  ") + "\n");
-    process.stdout.write(`  Si es la primera vez contra este remoto, autenticá pusheando a mano una vez:\n    git push -u origin ${branch}\n  y volvé a correr:  dai pr\n`);
+    for (const l of pushFailureHint(remote, branch)) process.stdout.write(`  ${l}\n`);
     fail(`no pude pushear la branch '${branch}'.`, 1);
   }
 
@@ -1263,7 +1289,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);
   }
@@ -1366,7 +1392,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) {
@@ -1379,7 +1405,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`);
@@ -1645,6 +1671,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}`);
@@ -1676,6 +1739,44 @@ function cmdDoctor() {
       : warn("DAI_CLICKUP_LIST_ID vacío — solo hace falta para `dai publish` (crear tareas)");
   }
 
+  // ── forge: el CÓMO sale del repo por acá ─────────────────────────────────────
+  // Si el push no sale, no hay PR; sin PR no hay link QUÉ↔CÓMO. El chequeo del cliente
+  // ssh existe porque su modo de fallar miente: ver lib/git-ssh.mjs.
+  const remote = gitRemote();
+  info("forge:");
+  if (!remote) warn("no hay remoto 'origin' — `dai pr` no tiene dónde publicar la branch");
+  else {
+    const p = parseRemote(remote);
+    ok(`remoto origin: ${remote}${p ? `  (${detectForge(p.host)})` : ""}`);
+    let sshConfig = null;
+    try { sshConfig = git(["config", "--get", "core.sshCommand"]) || null; } catch { /* sin valor: git sale 1 */ }
+    const d = diagnoseGitSsh({
+      platform: process.platform,
+      remote,
+      config: sshConfig,
+      env: { GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND, GIT_SSH: process.env.GIT_SSH },
+      hasWindowsOpenSsh: existsSync(WINDOWS_OPENSSH),
+    });
+    if (d.status === "ok") ok(`git usa el OpenSSH de Windows (ve al ssh-agent)`);
+    if (d.status === "ok-por-env") {
+      ok(`git usa el OpenSSH de Windows (ve al ssh-agent)`);
+      warn(`pero viene de ${d.source}, no del config: se pierde al cerrar la terminal.`);
+      process.stdout.write(`    Para que quede:  git config --global core.sshCommand "${WINDOWS_OPENSSH}"\n`);
+    }
+    if (d.status === "bundled" || d.status === "otro-ssh") {
+      warn(d.status === "bundled"
+        ? "git usa su propio ssh (Git for Windows), que NO ve al ssh-agent de Windows."
+        : `git usa ${d.bin} (por ${d.source}), que probablemente no vea al ssh-agent de Windows.`);
+      process.stdout.write(`    Si tu clave tiene passphrase, cada push te la va a pedir — y si el prompt no llega,\n`);
+      process.stdout.write(`    ssh cae a password y falla con "Permission denied (publickey…)", que acusa a la clave.\n`);
+      if (d.fix) process.stdout.write(`    → git config --global core.sshCommand "${d.fix}"\n`);
+      if (d.shadowed) process.stdout.write(`    Ojo: ${d.source} está seteada y pisa tu core.sshCommand. Límpiala primero.\n`);
+    }
+    if (d.status === "bundled-sin-openssh") {
+      warn("git usa su propio ssh y no encontré el OpenSSH de Windows: si el push pide passphrase, instálalo (Configuración → Características opcionales → Cliente OpenSSH).");
+    }
+  }
+
   // ── version-drift del scaffold vs el CLI (ADR-0010) ──────────────────────────
   if (existsSync(join(process.cwd(), ".dai", "VERSION"))) { info("versión del scaffold:"); reportDrift(); }
 }
@@ -1693,23 +1794,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;

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.

package/cli/lib/git-ssh.mjs

@@ -0,0 +1,107 @@
+// dai · qué cliente SSH usa git, y si ese cliente llega al agente (Windows).
+//
+// En Windows conviven dos ssh.exe: el de OpenSSH for Windows (C:\Windows\System32\
+// OpenSSH), que habla con el servicio `ssh-agent`, y el que trae Git for Windows
+// (MSYS), que NO lo ve. Con una clave con passphrase el síntoma es desconcertante:
+// `ssh -T` autentica (la firma la hace el agente) y `git push` pide la passphrase o,
+// si nadie la contesta, cae a autenticación por password y muere con
+// "Permission denied (publickey…)" — un error que apunta al lugar equivocado y se
+// come una mañana buscando el problema en la clave, en el token o en el server.
+//
+// Núcleo puro: el I/O (git config, existsSync) vive en dai.mjs.
+
+export const WINDOWS_OPENSSH = "C:/Windows/System32/OpenSSH/ssh.exe";
+
+// ¿Por dónde habla el remoto? Decide qué consejo tiene sentido cuando el push falla.
+export function remoteTransport(remote) {
+  const r = String(remote ?? "").trim();
+  if (!r) return null;
+  if (/^ssh:\/\//i.test(r)) return "ssh";
+  if (/^https?:\/\//i.test(r)) return "https";
+  if (/^[\w.-]+@[^:]+:/.test(r)) return "ssh";   // scp-like: git@host:org/repo.git
+  return null;                                    // git://, file://, ruta local…
+}
+
+// El binario de un core.sshCommand / GIT_SSH_COMMAND, que puede traer argumentos y
+// comillas:  `"C:/Program Files/Git/usr/bin/ssh.exe" -v`  →  la ruta sola.
+export function sshBinaryOf(cmd) {
+  const s = String(cmd ?? "").trim();
+  if (!s) return null;
+  if (s[0] === '"' || s[0] === "'") {
+    const end = s.indexOf(s[0], 1);
+    return end === -1 ? s.slice(1) : s.slice(1, end);
+  }
+  const sp = s.search(/\s/);
+  return sp === -1 ? s : s.slice(0, sp);
+}
+
+// ¿Esa ruta es el OpenSSH de Windows? Normalizado: mayúsculas y `\` vs `/` varían
+// según quién haya escrito el config (git acepta las dos formas).
+export function isWindowsOpenSsh(bin) {
+  const p = String(bin ?? "").replace(/\\/g, "/").toLowerCase();
+  return /(^|\/)system32\/openssh\/ssh(\.exe)?$/.test(p);
+}
+
+// Diagnóstico del cliente ssh que va a usar git. Entradas ya resueltas por el
+// llamador; acá no se toca el disco ni se lanza un proceso.
+//   platform          — process.platform
+//   remote            — url de origin (o null)
+//   config            — `git config --get core.sshCommand` (o null si no está)
+//   env               — { GIT_SSH_COMMAND, GIT_SSH }
+//   hasWindowsOpenSsh — existsSync(WINDOWS_OPENSSH)
+//
+// status:
+//   n/a               → no aplica (no es Windows, o el remoto no habla SSH)
+//   ok                → apunta al OpenSSH de Windows por core.sshCommand
+//   ok-por-env        → apunta bien, pero desde una env var: se pierde al cerrar la terminal
+//   otro-ssh          → apunta a otro ssh (el de MSYS, plink…)
+//   bundled           → nadie lo configuró: git usa el suyo, que no ve el agente
+//   bundled-sin-openssh → igual, pero no hay OpenSSH de Windows que recomendar
+export function diagnoseGitSsh({ platform, remote, config, env = {}, hasWindowsOpenSsh = false } = {}) {
+  if (platform !== "win32") return { status: "n/a", reason: "no-windows" };
+  const transport = remoteTransport(remote);
+  if (transport !== "ssh") return { status: "n/a", reason: transport ? "remoto-https" : "sin-remoto" };
+
+  // Precedencia real de git: GIT_SSH_COMMAND > GIT_SSH > core.sshCommand.
+  const [source, raw] =
+    env.GIT_SSH_COMMAND ? ["GIT_SSH_COMMAND", env.GIT_SSH_COMMAND]
+    : env.GIT_SSH ? ["GIT_SSH", env.GIT_SSH]
+    : config ? ["core.sshCommand", config]
+    : ["default", null];
+
+  // Una env var pisando un core.sshCommand que ya estaba bien: el dev "arregló" el
+  // config, no funciona, y no hay forma de verlo mirando el .gitconfig.
+  const shadowed = source !== "default" && source !== "core.sshCommand" && Boolean(config);
+
+  if (source === "default") {
+    return hasWindowsOpenSsh
+      ? { status: "bundled", source, bin: null, fix: WINDOWS_OPENSSH, shadowed }
+      : { status: "bundled-sin-openssh", source, bin: null, fix: null, shadowed };
+  }
+
+  const bin = sshBinaryOf(raw);
+  if (isWindowsOpenSsh(bin)) {
+    return { status: source === "core.sshCommand" ? "ok" : "ok-por-env", source, bin, fix: null, shadowed };
+  }
+  return { status: "otro-ssh", source, bin, fix: hasWindowsOpenSsh ? WINDOWS_OPENSSH : null, shadowed };
+}
+
+// Qué decirle al dev cuando `git push` falla. El consejo de "pusheá a mano una vez"
+// solo aplica a HTTPS, donde el credential manager pide la credencial la primera vez;
+// contra un remoto SSH el push a mano falla EXACTAMENTE igual, así que mandarlo por ahí
+// es hacerle perder el tiempo mientras el problema real (la clave, el agente) sigue ahí.
+export function pushFailureHint(remote, branch) {
+  if (remoteTransport(remote) === "ssh") {
+    return [
+      `El remoto habla SSH: en el push no interviene el token de gh/glab, solo tu clave.`,
+      `Prueba a mano — así ves lo que ssh pregunta (p. ej. la passphrase de tu clave):`,
+      `  git push -u origin ${branch}`,
+      `Si te la pide en cada push, tu clave está en un agente que git no ve:  dai doctor`,
+    ];
+  }
+  return [
+    `Si es la primera vez contra este remoto, autentica pusheando a mano una vez:`,
+    `  git push -u origin ${branch}`,
+    `y vuelve a ejecutar:  dai pr`,
+  ];
+}

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/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/setup-dev.md

@@ -135,7 +135,7 @@ dai init --for copilot --pm jira
 ```
 
 Te va a preguntar si quieres instalar **OpenSpec**: responde **`s`**. Es el motor del CÓMO —
-convierte la US en `design.md` + `tasks.md` con los comandos `/opsx:*`. Un dev sí lo usa.
+convierte la US en `design.md` + `tasks.md` con los comandos `/opsx-*`. Un dev sí lo usa.
 
 Lo que deja:
 
@@ -262,28 +262,40 @@ Trae la US de Jira, calcula el `ac_hash` de sus criterios y deja dos cosas:
 ✓ archivo: openspec/changes/finalizar-la-compra-del-carrito/implements.yaml  (ac_hash 380d814b)
 ```
 
-Ese `implements.yaml` es **el único archivo que se autora a mano** en todo el método
-([ADR-0004](../adr/0004-ubicacion-y-schema-implements.md)):
+Ese `implements.yaml` es el **único registro autorado** del método
+([ADR-0004](../adr/0004-ubicacion-y-schema-implements.md)): el resto de la trazabilidad se
+**deriva**, este se escribe. "Autorado" significa que lo escribe alguien —no que lo tipees tú
+ahora—, y `dai link-us` ya te lo dejó casi entero:
 
 ```yaml
 change: finalizar-la-compra-del-carrito
 repo:   tienda
 
 implements:
-  - id: PROJ-125
-    version: v1
-    ac_hash: 380d814b
+  - id: PROJ-125          # ← ya está: lo puso link-us desde el ID que validó
+    version: v1           # ← ya está
+    ac_hash: 380d814b     # ← ya está: calculado sobre los criterios de la US
 
 introduces:
-  - <capacidad-tecnica>   # completar: specs técnicas nuevas de este change
+  - <capacidad-tecnica>   # ← lo ÚNICO pendiente, y NO se completa ahora
 
-autor: tu.nombre
+autor: tu.nombre          # ← ya está
 ```
 
-Completa `introduces` con las capacidades técnicas nuevas del change (o bórralo si no hay).
+> **No completes `introduces` todavía.** Es lo que este change **introduce** en el repo: las
+> capacidades técnicas nuevas. Recién al terminar de implementar se sabe cuáles son —al
+> empezar sería adivinar—, así que se completa **al cerrar la implementación**, no acá.
+
+**Y normalmente no lo escribes tú: lo escribe el agente.** Cuando `/opsx-apply` termina de
+aplicar las tareas, el que implementó es el que sabe qué capacidades quedaron: pídele que
+complete `introduces` (o que borre el bloque si el change no introdujo ninguna) como último
+paso. **Tú lo revisas en la MR** — el archivo va versionado con el código justamente para que
+se lea en la revisión, igual que cualquier otro cambio.
 
 > **El key no se tipea nunca a mano.** La rama y el `implements.yaml` salen los dos del mismo
-> ID validado: por eso el link no puede quedar mal escrito.
+> ID validado: por eso el link no puede quedar mal escrito. El campo que sí requiere criterio
+> humano —`introduces`— es el único que queda abierto, y no es un dato del tracker: es tu
+> lectura de lo que el change agregó.
 
 > **Si te dice que la US no tiene criterios de aceptación**, frena: no es un problema de tu
 > setup. Esa US no cumple el [DoR](../../templates/definition-of-ready.md) y vuelve al PO.
@@ -291,14 +303,36 @@ Completa `introduces` con las capacidades técnicas nuevas del change (o bórral
 ### 2. Arma el CÓMO y programa
 
 ```
-/opsx:explore     → entender el terreno
-/opsx:propose     → design.md + tasks.md sobre la rama ya linkeada
-/opsx:apply       → el agente implementa las tareas con test primero (/tdd)
+/opsx-explore     → entender el terreno
+/opsx-propose     → design.md + tasks.md sobre la rama ya linkeada
+/opsx-apply       → el agente implementa las tareas con test primero (/tdd)
 ```
 
+> **En Copilot los comandos van con guion, no con dos puntos.** OpenSpec nombra sus comandos
+> según el asistente: en Claude Code son `/opsx:propose` (namespace anidado), y en Copilot y
+> Cursor son `/opsx-propose`, por el nombre del archivo que generan
+> (`.github/prompts/opsx-propose.prompt.md`). Mucha documentación —la de OpenSpec incluida—
+> muestra solo la forma de Claude.
+>
+> Si tipeas `/opsx:propose` en Copilot **no falla con un error**: no encuentra nada, se queda
+> con tu texto suelto y se pone a improvisar. Se ve como un agente que "hace lo que quiere",
+> que se saltea el gate y que arranca a programar sin haber escrito la propuesta. Si te pasa
+> eso, lo primero que hay que mirar es cómo escribiste el comando.
+
 Tú validas el diseño, decides qué comportamientos importa testear y **revisas lo que escribió
 el agente**: eres responsable del código, no la IA.
 
+Cuando `/opsx-apply` termina, cierra el link — es el momento en que ya se sabe qué introdujo
+el change:
+
+```
+Completa `introduces` en el implements.yaml con las capacidades técnicas que agregó este
+change (o borra el bloque si no agregó ninguna).
+```
+
+Revisa lo que puso. `introduces` no es un dato del tracker: es la lectura de lo que el change
+agregó al repo, y viaja versionado para que se lea en la MR.
+
 ### 3. Commitea y comprueba el link
 
 ```powershell
@@ -382,12 +416,58 @@ chat de Copilot en modo *Agent*, escribiendo `/` adelante.
 |---|---|---|
 | Los comandos de **dai** | **PowerShell**, parado en el repositorio | `dai link-us` · `dai check` · `dai mr` · `dai stamp` · `dai done` |
 | Las **skills** (empiezan con `/`) | El **chat de Copilot**, modo *Agent* | `/link-us` · `/tdd` · `/dai-review` · `/grill-intent` |
-| Los comandos de **OpenSpec** | El **chat de Copilot** | `/opsx:explore` · `/opsx:propose` · `/opsx:apply` |
+| Los comandos de **OpenSpec** | El **chat de Copilot** | `/opsx-explore` · `/opsx-propose` · `/opsx-apply` (con **guion**: ver arriba) |
 
 ---
 
 ## Cuando algo falla
 
+### El agente no respeta los pasos: implementa sin escribir la propuesta
+
+Síntoma: le pides `/opsx:explore` o `/opsx:propose` y el agente te explica el método, te pide
+que le pegues el ticket a mano, o directamente se pone a escribir código sin haber generado
+`proposal.md` / `design.md` / `tasks.md`. Hay que frenarlo a mano en cada paso.
+
+Casi siempre es **el nombre del comando**. En Copilot son `/opsx-explore`, `/opsx-propose`,
+`/opsx-apply` — **con guion**. Con los dos puntos, Copilot no encuentra ningún comando, no
+avisa, y toma tu texto como una charla suelta: el workflow nunca se cargó. Comprueba qué
+tienes disponible:
+
+```powershell
+dai doctor
+```
+
+En el apartado **OpenSpec** te dice los comandos exactos de tu asistente:
+
+```
+› OpenSpec — los comandos van en el chat del asistente, no en la terminal:
+✓ Copilot: /opsx-explore · /opsx-propose · /opsx-apply · /opsx-archive
+```
+
+Si dice que no hay comandos, falta inicializar OpenSpec:
+
+```powershell
+openspec init --tools github-copilot --force
+```
+
+Después **reinicia VS Code**: los comandos nuevos no aparecen hasta que se recarga.
+
+Con el nombre correcto el agente frena al terminar la propuesta y espera tu aprobación antes
+de implementar.
+
+Si aun así se pasa de largo —o si te nombra comandos con dos puntos que no existen—, mira la
+versión de OpenSpec: `dai doctor` te avisa si está vieja. Hasta la **1.10.0**, los prompts que
+OpenSpec generaba para Copilot pedían herramientas que Copilot no tiene, y su única forma de
+frenar a preguntarte no existía. Actualiza:
+
+```powershell
+npm i -g @fission-ai/openspec@latest
+openspec init --tools github-copilot --force
+```
+
+En cualquier caso, **la aprobación del diseño es tuya**: si ves que arrancó a programar sin
+que hayas dicho que sí, páralo y pídele la propuesta.
+
 ### `dai link-us` dice que no encontró la US en jira
 
 Por orden de frecuencia:
@@ -455,6 +535,26 @@ $env:NODE_EXTRA_CA_CERTS="C:\ruta\ca-empresa.pem"
 > lo proponga un asistente. Eso no arregla nada: **apaga la verificación entera**, y por esa
 > conexión viaja tu token de Jira.
 
+### `dai check` imprime el ✅ y después tira `Assertion failed … UV_HANDLE_CLOSING`
+
+```
+✅ PROJ-125 al día (v1)
+Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c, line 94
+```
+
+El resultado que ves es el bueno: el chequeo terminó bien. Lo que revienta después es el
+**cierre del proceso** de Node en Windows, desarmando la conexión que se usó para consultar
+Jira. Es un problema de Node, no de tu configuración ni de tu US.
+
+Ya está corregido en dai. Actualiza:
+
+```powershell
+dai upgrade
+```
+
+Importaba arreglarlo porque el proceso terminaba con un código de error aunque el chequeo
+hubiera pasado: un `dai check` verde se reportaba rojo en el CI o en un hook de git.
+
 ### El CI falla con "falta el link"
 
 Es el gate de [`governance/ci-rules.md`](https://github.com/dforce2055/dai/blob/main/governance/ci-rules.md),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforce2055/dai",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Metodología de desarrollo asistido por IA — CLI de acciones deterministas (trazabilidad QUÉ↔CÓMO).",
   "repository": { "type": "git", "url": "git+https://github.com/dforce2055/dai.git" },
   "homepage": "https://dforce2055.github.io/dai/",

package/skills/link-us/SKILL.md

@@ -25,7 +25,7 @@ Es la contraparte técnica de `grill-user-story`: donde esa produce el QUÉ (en
    - Nombre: `feature/ABC-###-<slug>` donde `<slug>` sale del título (minúsculas, sin acentos, `-` como separador).
    - Base según convención del repo (`main` o `develop`). Verificar que la branch no exista ya.
    - No permitir crear la branch si el key no fue validado en el paso 1.
-4. **Generar el link.** Crear `openspec/changes/<change-id>/implements.yaml` a partir de [templates/implements.yaml](templates/implements.yaml), completando `id`, `version`, `ac_hash`, `repo` y `autor`. Dejar `introduces` para que el dev liste las capacidades técnicas nuevas.
+4. **Generar el link.** Crear `openspec/changes/<change-id>/implements.yaml` a partir de [templates/implements.yaml](templates/implements.yaml), completando `id`, `version`, `ac_hash`, `repo` y `autor`. Dejar `introduces` con el placeholder: **no se completa ahora**. Al arrancar no se sabe qué capacidades técnicas va a introducir el change — eso se sabe al terminar de implementarlo, y ahí lo completa quien implementó (agente o dev), con el dev revisándolo en la PR.
 5. **Hand-off.** Ofrecer seguir con `opsx:explore` → `opsx:propose` para armar el change (proposal/design/tasks) sobre la branch ya creada y linkeada.
 
 ## Guardrails (por qué esta skill existe)

package/skills/link-us/templates/implements.yaml

@@ -1,5 +1,6 @@
 # Link QUÉ↔CÓMO · lo genera link-us / `dai link-us`, lo versiona git junto al código.
-# Es el ÚNICO link autorado a mano. La cobertura inversa la deriva `dai stamp`.
+# Es el ÚNICO link AUTORADO (se escribe, no se deriva): lo scaffoldea `link-us` y se cierra
+# al terminar de implementar. La cobertura inversa la deriva `dai stamp`.
 # Schema: docs/adr/0004-ubicacion-y-schema-implements.md
 
 change: <change-id>              # ← identidad del CÓMO (nombre local del change/spec). Auto-contenido.
@@ -11,6 +12,7 @@ implements:                      # FORWARD: qué QUÉ del negocio cumple este ch
     ac_hash: <autogenerado>      # ← lo calcula `dai ac-hash`. Dispara el ⚠️ si el QUÉ cambia.
 
 introduces:                      # capacidades TÉCNICAS nuevas que agrega este change (opcional)
-  - <capacidad-tecnica>          #   p. ej. guard-carrito-vacio
+  - <capacidad-tecnica>          #   p. ej. guard-carrito-vacio. Se completa AL TERMINAR de
+                                 #   implementar, no al crear el link: recién ahí se sabe.
 
 autor: <dev>                     # quién implementa

package/templates/definition-of-done.md

@@ -24,6 +24,9 @@
 - [ ] Existe `implements.yaml` con `id`, `version` y `ac_hash`. *(Art. 9)*
 - [ ] El **`ac_hash` coincide** con el de la US vigente (no se implementó una versión atrasada). *(Art. 11)*
 - [ ] La rama sigue la convención (`feature/ABC-###-<slug>`) → ver `governance/branch-naming.md`.
+- [ ] **`introduces` está cerrado**: lista las capacidades técnicas que el change agregó, o el
+      bloque se borró porque no agregó ninguna. No queda el placeholder `<capacidad-tecnica>`:
+      es el único campo que se completa **al terminar**, y sin cerrarlo el link queda a medias.
 
 ### Revisión
 - [ ] Pasó el **primer pase de IA** (`dai-review`): sin problemas de correctitud.
@@ -31,7 +34,9 @@
 - [ ] Cumple los estándares del repo (lint, tipos, convenciones).
 
 ### Cierre
-- [ ] El change se promovió (`opsx:apply` → `opsx:archive`) si aplica.
+- [ ] El change se promovió (los comandos `apply` → `archive` de OpenSpec) si aplica.
+      *(Se escriben `/opsx:apply` en Claude Code y `/opsx-apply` en Copilot y Cursor —
+      `dai doctor` te dice cuál usa este repo.)*
 - [ ] El **CI estampó la cobertura** en el gestor (no la escribió una persona). *(Art. 10)*
 - [ ] La US quedó en estado **implementada**.