@dforce2055/dai 0.13.3 → 0.14.0

package/.env.dai.example

@@ -12,6 +12,21 @@ DAI_PM=md
 # Si dai no puede saber el link, avisa y deja la PR sin él — nunca escribe el id pelado.
 # DAI_TRACKER_URL_TEMPLATE=https://jira.miempresa.com/browse/{id}
 
+# ── Flujo de branches (dai pr · dai done) ────────────────────────────────────
+# Las DOS ramas de vida larga del repo. No se configura "la base" de las PR: la base sale
+# del TIPO de branch, y con eso dai deja de adivinar.
+#   feature/ · fix/     → PR contra DAI_BRANCH_DEV
+#   release/ · hotfix/  → PR contra DAI_BRANCH_PROD, con confirmación explícita
+#
+# Rama que INTEGRA el desarrollo (la que se despliega a test). Sin declarar, dai usa la
+# rama default del remoto (origin/HEAD) y avisa que la está adivinando.
+# DAI_BRANCH_DEV=testing
+
+# Rama que DESPLIEGA A PRODUCCIÓN. `dai pr` la marca en el preview y pide confirmación
+# antes de publicar; con --yes hace falta --to-prod. Sin declarar, dai no marca ninguna
+# rama como producción: no adivina cuál es.
+# DAI_BRANCH_PROD=main
+
 # ── Backend md (local, offline) ──────────────────────────────────────────────
 # Carpeta donde viven las US como <ID>.md (p. ej. ABC-482.md).
 DAI_MD_US_DIR=.dai/us

package/CHANGELOG.md

@@ -3,6 +3,67 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/). Versionado semver
 (ver `VERSION`).
 
+## [0.14.0] — 2026-09-08
+
+**`dai pr` proponía mergear a `main` en un repo donde `main` despliega a producción, y el
+preview no lo destacaba de ninguna forma. Tirando de ese hilo apareció que el problema no
+era el default: era pedirle a alguien que configure "la base", cuando la base no es una
+constante — es consecuencia del tipo de branch. Y de yapa, el hallazgo más caro de la
+versión: `dai <comando> --help` no imprimía ayuda, ejecutaba el comando.**
+
+### Cambiado
+- **La base de una PR sale del mapa de ramas del repo, no de un `main` fijo.** Se declaran
+  las **dos ramas de vida larga** en el `.env.dai` —`DAI_BRANCH_DEV` (la que integra) y
+  `DAI_BRANCH_PROD` (la que despliega a producción)— y `dai pr` deriva la base del **tipo de
+  branch**: `feature/` y `fix/` integran, `release/` y `hotfix/` van contra producción.
+  `--base` gana siempre. Sin nada declarado, dai cae a la rama default del remoto
+  (`origin/HEAD`) **y avisa que la está adivinando** — antes decía `main` sin más.
+  `dai done` usa el mismo mapa (tenía el mismo `main` hardcodeado) y `dai doctor` lo reporta.
+  El preview ahora dice **de dónde salió** la base, que era la mitad que faltaba
+  ([#46](https://github.com/dforce2055/dai/issues/46)).
+- **Apuntarle a producción pide confirmación explícita.** Si la base es `DAI_BRANCH_PROD`,
+  el preview la marca `⚠️ DESPLIEGA A PRODUCCIÓN` y hay que **escribir el nombre de la rama**
+  para seguir; con `--yes` hace falta `--to-prod`. Sin la variable declarada dai no marca
+  ninguna rama como producción: no adivina cuál es, y un gate inventado sobre una suposición
+  es peor que no tenerlo.
+- **`dai <comando> --help` imprime ayuda en vez de ejecutar el comando.** Vale para todos:
+  `dai help`, `dai --help`, `dai -h`, `dai help <cmd>`, `dai <cmd> --help`, `dai <cmd> -h` y
+  `dai <cmd> help`. Siempre por `stdout` y siempre con código 0; un comando desconocido sigue
+  saliendo por `stderr` con código ≠ 0, que es lo que deja `dai foo --help` usable dentro de
+  un script. Cada comando tiene ayuda propia (qué hace, uso, opciones, ejemplo).
+
+### Corregido
+- **`dai pr` dejaba una MR con el diff al día y la descripción vieja.** Con una MR ya abierta
+  pusheaba la branch, fallaba al crear porque la MR existía, y la única señal era el comando
+  crudo del forge. Quedaba una MR que **miente sobre lo que contiene**, que es peor que un
+  error porque parece que salió bien. Ahora la detecta **antes** de pushear
+  (`gh pr list --head` / `glab mr list --source-branch`), el preview dice
+  `── Pull Request a ACTUALIZAR (#12) ──` y actualiza título y descripción. Si la detección no
+  pudo correr y el forge responde *"already exists"*, la busca y la actualiza igual; si tampoco
+  puede, lo dice con todas las letras: *"NO toqué su descripción: quedó la vieja"*. También
+  avisa si la MR abierta apunta a otra base que la pedida ([#46](https://github.com/dforce2055/dai/issues/46)).
+- **`dai link-us` estampaba `version: v1` en una US que declaraba `v4`.** El regex del
+  `spec_version` exigía separador y la US lo escribía pegado (`specversion`) — y estaba
+  **duplicado en dos módulos**, que es exactamente por qué se podía arreglar en uno y seguir
+  roto en el otro. Ahora vive en un solo lugar y tolera `spec_version`, `spec version`,
+  `spec-version` y `specversion`. Sin `spec_version` declarado **no se inventa un `v1`**: queda
+  `pendiente` con aviso, porque ese número se publica en el cuerpo de la PR y se estampa en el
+  tracker como si fuera un dato. `dai check` además avisa cuando el número del link no coincide
+  con el de la US viva ([#46](https://github.com/dforce2055/dai/issues/46)).
+- **`dai pr` no podía abrir la PR de un repo sin US.** En un repo que no se trackea a sí mismo
+  con User Stories —el de dai, sin ir más lejos— una branch `fix/` sin ID moría pidiendo un
+  link que no puede existir, y aconsejaba renombrarla a `chore/`, que para un fix es el consejo
+  equivocado. Ahora, si la branch no exige link **y** el repo no declara ninguna US, la PR sale
+  "Sin US" con el motivo. Una `feature/` sin link sigue fallando: ahí falta de verdad.
+- **`.env.dai` no estaba en el `.gitignore` de este repo**, aunque `dai init` lo agrega en todos
+  los que scaffoldea. Faltaba justo en el que se publica en npm.
+
+### Interno
+- **408 tests** (+41): el mapa de ramas y la derivación por tipo de branch, la detección y
+  actualización de una PR existente en los dos forges, las variantes del `spec_version`, y la
+  convención de ayuda — con un test que recorre los `case` del dispatcher y **falla si alguno se
+  agrega sin ayuda**, para que la convención no dependa de acordarse.
+
 ## [0.13.3] — 2026-09-02
 
 **Una PR de dai se abría diciendo, en el mismo párrafo, dos cosas que no encajaban: que el
@@ -857,6 +918,7 @@ ClickUp y Jira Cloud.
 - Tests de las rutas de red (jira/clickup/forge) con `fetch` mockeado. Sin links rotos;
   `files` de npm sin tests ni secretos.
 
+[0.14.0]: https://github.com/dforce2055/dai/releases/tag/v0.14.0
 [0.13.3]: https://github.com/dforce2055/dai/releases/tag/v0.13.3
 [0.13.2]: https://github.com/dforce2055/dai/releases/tag/v0.13.2
 [0.13.1]: https://github.com/dforce2055/dai/releases/tag/v0.13.1

package/README.md

@@ -202,13 +202,14 @@ flowchart TD
 | `dai link-us <ID> --resync` | re-estampa el `ac_hash` contra la US viva (tras un ⚠️ de check) |
 | `dai check` | compara tu código vs la US viva → ✅ al día / ⚠️ atrasado (exit code = gate de PR) |
 | `dai ls [--json]` | lista las US que implementa el repo + su link al tracker |
-| `dai pr [--assignee u] [--base b] [--draft] [--yes] [--us ID] [--title t] [--description t\|--description-file f] [--changes t\|--changes-file f]` · alias **`dai mr`** | crea TU PR/MR precargada: pregunta la branch base (default `main`), muestra el texto y confirma antes de publicar. Detecta el forge (GitHub→PR con `gh` · GitLab→MR con `glab`); `mr` es el mismo comando, más natural en GitLab. **La US la resuelve la branch** (la nombra `dai link-us`): si hay varias vivas y ninguna coincide, **pregunta** en vez de elegir por vos (sin TTY falla pidiendo `--us <ID>`), y una branch `chore/`/`docs/` sale **sin US** en lugar de heredar la de otro. **La descripción la escribís vos (o tu agente) con `--description`**: dai llena la US, los commits y los links, pero no inventa el propósito de un cambio — si "Descripción" o "Cambios realizados" quedarían con el molde del template, con `--yes` o sin TTY **no publica** y te dice qué falta |
+| `dai pr [--assignee u] [--base b] [--draft] [--yes] [--us ID] [--title t] [--description t\|--description-file f] [--changes t\|--changes-file f]` · alias **`dai mr`** | crea **o actualiza** TU PR/MR precargada: propone la branch base **según el tipo de rama** (`feature/`/`fix/` → `DAI_BRANCH_DEV` · `release/`/`hotfix/` → `DAI_BRANCH_PROD`; `--base` gana, y si no hay nada declarado cae a la rama default del remoto **avisando que adivina**), muestra el texto y confirma antes de publicar. Contra la rama de producción pide una **confirmación explícita** (escribir el nombre de la rama; con `--yes` hace falta `--to-prod`). Si la branch **ya tiene una PR/MR abierta**, actualiza su título y su descripción en lugar de fallar dejando el diff al día y el body viejo. Detecta el forge (GitHub→PR con `gh` · GitLab→MR con `glab`); `mr` es el mismo comando, más natural en GitLab. **La US la resuelve la branch** (la nombra `dai link-us`): si hay varias vivas y ninguna coincide, **pregunta** en vez de elegir por vos (sin TTY falla pidiendo `--us <ID>`), y una branch `chore/`/`docs/` sale **sin US** en lugar de heredar la de otro. **La descripción la escribís vos (o tu agente) con `--description`**: dai llena la US, los commits y los links, pero no inventa el propósito de un cambio — si "Descripción" o "Cambios realizados" quedarían con el molde del template, con `--yes` o sin TTY **no publica** y te dice qué falta |
 | `dai stamp` | estampa la cobertura inversa en el tracker (branch + commit-ancla) |
-| `dai done [--base main] [--force]` | cierra la US: vuelve a la base, `fetch --prune` + `pull`, y borra la branch local **si está mergeada** (chequeo estricto; `--force` la borra igual). Redes: no estar en la base, sin cambios sueltos, sin commits sin pushear |
+| `dai done [--base b] [--force]` | cierra la US: vuelve a la base (se resuelve igual que en `dai pr`), `fetch --prune` + `pull`, y borra la branch local **si está mergeada** (chequeo estricto; `--force` la borra igual). Redes: no estar en la base, sin cambios sueltos, sin commits sin pushear |
 | `dai archive [<change>] [--skip-specs]` | **funde los delta specs del change en las specs canónicas** (`openspec/specs/`) y lo archiva. Lo corre el **aprobador** de la PR (gate de aprobación, [ADR-0011](docs/adr/0011-archive-gate-de-aprobacion.md)); detecta el change activo o le pasás el nombre. Envuelve `openspec archive` |
 | `dai forge review <ref> --from <review.json>` `[--dry-run\|--yes]` | **review inline**: un resumen + un comentario anclado a cada `archivo:línea`, clasificado low/medium/high. **Valida cada posición contra el diff** (descarta lo que el modelo inventó) antes de postear; sin `--yes` muestra el preview y no postea nada. Modo desatendido: `--min-severity`/`--min-confidence`/`--max-comments`. El review sale con `event: COMMENT`, nunca `APPROVE` ([ADR-0016](docs/adr/0016-review-inline.md)) |
 | `dai forge comment <ref> --body-file <f>` · `dai forge pr <ref>` | comentar / leer una PR/MR (GitHub/GitLab) — el fallback simple, sin anclar |
 | `dai ac-hash <us.md>` | calcula el hash de los criterios de aceptación de una US |
+| `dai help [<comando>]` · `dai <comando> --help` | ayuda del CLI. Pedir ayuda **nunca ejecuta el comando**: sale por `stdout` y termina con 0. Valen `--help`, `-h` y `dai <comando> help` — las tres formas, en todos los comandos |
 | `dai doctor` · `dai docs <dest>` · `dai version` | diagnóstico del entorno (incluye **version-drift** del scaffold) · copiar la doc (sin los assets del sitio; los links a las capturas apuntan al sitio publicado) · versión (`dai version` avisa si tu repo quedó atrás) |
 
 > **🆕 Mantené tu repo al día — `dai sync`.** Las skills, la constitución y los templates son un

package/VERSION

@@ -1 +1 @@
-0.13.3
+0.14.0

package/cli/dai.mjs

@@ -28,6 +28,8 @@ 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, bodyGaps } from "./lib/pr.mjs";
+import { resolveBase, isProdBranch, branchFlow, baseHint, parseOriginHead } from "./lib/branch-flow.mjs";
+import { listPrCmd, parsePrList, updatePrCmd, isAlreadyExistsError, describeUpdate } from "./lib/pr-remote.mjs";
 import { absolutizeSiteLinks } from "./lib/docs-links.mjs";
 import { diagnoseGitSsh, pushFailureHint, WINDOWS_OPENSSH } from "./lib/git-ssh.mjs";
 import { dirsEqual } from "./lib/fsutil.mjs";
@@ -39,7 +41,8 @@ import { parseFieldsFile, parseFieldOverrides, resolveJiraFields } from "./lib/j
 import { assertProjectKey } from "./lib/pm-jira.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";
+import { validateUS, renderValidation, parseSpecVersion, bumpSpecVersion, setSpecVersion, PENDING_VERSION } from "./lib/us-format.mjs";
+import { isHelpToken, wantsHelp, helpTopic, helpFor, globalUsage } from "./lib/help.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -150,13 +153,14 @@ function cmdLs(opts) {
 async function cmdLinkUs(key, opts) {
   if (!isValidKey(key)) fail(`key inválido: '${key}'. Sin espacios ni barras (ej.: ABC-482 o 86cxyz).`, 1);
 
-  let title, hash, version = "v1";
+  let title, hash, version = null;
   if (opts.us) {
     // Fuente local: un .md con la US.
     const md = readFileSync(opts.us, "utf8");
     hash = acHash(md);
     if (hash == null) fail(`la US en ${opts.us} no tiene una sección 'Criterios de aceptación' con criterios testeables → sin ac_hash.\n  Agregá los criterios bajo '## Criterios de aceptación', o corré /grill-user-story para pulir la US.`, 2);
     title = opts.title || extractTitle(md);
+    version = parseSpecVersion(md);
   } else {
     // Fuente tracker: traer la US del adaptador (mismo hash que usará `dai check`).
     loadDaiEnv();
@@ -166,7 +170,16 @@ async function cmdLinkUs(key, opts) {
     hash = us.ac_hash;
     if (hash == null) fail(`la US ${key} no tiene una sección 'Criterios de aceptación' con criterios testeables → sin ac_hash, no se puede linkear.\n  Agregá la sección en el tracker, o corré /grill-user-story ${key} para pulir la US (te interroga y la re-publica).`, 2);
     title = opts.title || us.title;
-    version = us.spec_version || "v1";
+    version = us.spec_version;
+  }
+
+  // Sin spec_version NO se inventa un `v1`: ese número se publica en la PR y se estampa en
+  // el tracker como si fuera un dato, y `dai check` lo reporta con un ✅ que da por buena
+  // una versión que no existe (issue #46). Un placeholder visible dice la verdad.
+  if (!version) {
+    version = PENDING_VERSION;
+    warn(`la US ${key} no declara spec_version — el link queda con 'version: ${PENDING_VERSION}'.`);
+    process.stdout.write(`    Agregá la fila 'spec_version | v1' a la metadata de la US y re-estampá:  dai link-us ${key} --resync\n`);
   }
 
   // ── modo resync: re-estampar el ac_hash en el implements.yaml existente ──────
@@ -222,6 +235,14 @@ function gitCommit() { try { return git(["rev-parse", "HEAD"]); } catch { return
 function resolveRev(ref) {
   try { git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]); return ref; } catch { return null; }
 }
+// La rama default del remoto (`origin/HEAD`). Es mejor fallback que un `main` fijo, pero
+// sigue siendo un fallback: en un repo con ramas de ambiente, la default del remoto suele
+// ser justo la de producción. Por eso el preview siempre dice de dónde salió la base.
+function originHeadBranch() {
+  try { return parseOriginHead(git(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"])); }
+  catch { return null; }
+}
+
 // Un texto que se puede pasar inline (`--description "…"`) o por archivo
 // (`--description-file notas.md`). Un agente casi siempre quiere el archivo: markdown
 // multilínea no sobrevive entero a la línea de comandos.
@@ -297,7 +318,7 @@ async function cmdCheckCi(opts = {}) {
     try { live = await adapter.fetchUS(r.id); } catch (e) { netErr = String(e.message).split("\n")[0]; }
     if (netErr) { warn(`${r.id}: no pude leer la US (${netErr}) — no bloqueo por un problema de red/credencial.`); continue; }
     const status = coverageStatus(r.ac_hash, live?.ac_hash);
-    if (status === "al-dia") ok(`${r.id} al día (${r.version})`);
+    if (status === "al-dia") { ok(`${r.id} al día (${r.version})`); versionDriftHint(r, live); }
     else if (status === "atrasado") {
       process.stderr.write(`✗ gate: ${r.id} ATRASADO — implementaste ${r.ac_hash}, la US viva es ${live.ac_hash}.\n` +
         `    El QUÉ cambió. Resincronizá y revisá que lo cubras:  dai link-us ${r.id} --resync\n`);
@@ -321,6 +342,18 @@ function ciBranch() {
     (e.GITHUB_REF_NAME && !/^\d+\/merge$/.test(e.GITHUB_REF_NAME) ? e.GITHUB_REF_NAME : null) || null;
 }
 
+// El ac_hash dice si el QUÉ cambió; el `version` del link es el número que se PUBLICA
+// (en el body de la PR, en el stamp del tracker). Que coincidan no es cosmético: un link
+// al día con `version: v1` contra una US en v4 estampa una versión que no existe, y el ✅
+// lo hace pasar por verificado (issue #46). No cambia el exit code — el hash manda.
+function versionDriftHint(im, live) {
+  const declared = String(im?.version ?? "").trim();
+  const real = String(live?.spec_version ?? "").trim();
+  if (!real || declared === real) return;
+  warn(`${im.id}: el link declara version '${declared || "(vacío)"}' y la US viva dice '${real}'.`);
+  process.stdout.write(`    Ese número se publica en la PR y se estampa en el tracker. Corregilo:  dai link-us ${im.id} --resync\n`);
+}
+
 // ── check ──────────────────────────────────────────────────────────────────
 // `process.exitCode` en vez de `process.exit()`: ver la nota en cmdCheckCi.
 async function cmdCheck() {
@@ -334,7 +367,10 @@ async function cmdCheck() {
     n++;
     const { us: live, unreachable, reason } = await fetchLiveUS(adapter, im.id);
     const status = coverageStatus(im.ac_hash, live?.ac_hash, { unreachable });
-    if (status === "al-dia") process.stdout.write(`✅ ${im.id} al día (${im.version})\n`);
+    if (status === "al-dia") {
+      process.stdout.write(`✅ ${im.id} al día (${im.version})\n`);
+      versionDriftHint(im, live);
+    }
     else if (status === "atrasado") {
       process.stdout.write(`⚠️  ${im.id} ATRASADO: implementaste ${im.ac_hash}, la US viva es ${live.ac_hash}${live.spec_version ? ` (${live.spec_version})` : ""}\n`);
       atrasadas.push(im.id);
@@ -833,8 +869,13 @@ async function cmdUpdateUs(id, opts = {}) {
 
 // ── done: cierra una US — vuelve a la base, actualiza y borra la branch local ──
 function cmdDone(opts) {
-  const base = opts.base || "main";
+  loadDaiEnv();
+  // Misma resolución que `dai pr`: el `main` fijo mandaba a checkout+pull a la rama
+  // equivocada en cualquier repo que integre contra develop/testing (issue #46).
+  if (opts.base === true) fail("--base necesita el nombre de una branch (ej: --base develop).", 1);
+  const baseFlag = Array.isArray(opts.base) ? opts.base[opts.base.length - 1] : (typeof opts.base === "string" ? opts.base : null);
   const branch = gitBranch();
+  const { base, source: baseSource } = resolveBase({ flag: baseFlag, branch, env: process.env, originHead: originHeadBranch() });
   if (!branch || branch === "HEAD") fail("no estás en una branch.", 1);
   if (branch === base) fail(`ya estás en '${base}' — nada que cerrar.`, 1);
 
@@ -857,7 +898,7 @@ function cmdDone(opts) {
   ).map((r) => r.id);
 
   // Ir a la base y actualizar.
-  info(`Cambiando a '${base}' y actualizando…`);
+  info(`Cambiando a '${base}' y actualizando… ${C.dim(`(base: ${baseSource})`)}`);
   try { git(["checkout", base]); } catch (e) { fail(`no pude cambiar a '${base}': ${String(e.message).split("\n")[0]}`, 1); }
   try { git(["fetch", "--prune"]); } catch { /* sin remoto */ }
   try { git(["pull", "--ff-only"]); } catch { warn(`no pude hacer 'pull --ff-only' en '${base}' (¿divergió?). Revisa a mano.`); }
@@ -879,6 +920,23 @@ function cmdDone(opts) {
   info("La branch remota (si existe) la maneja el forge (auto-delete on merge) o bórrala tú.");
 }
 
+// El comando del forge, listo para copiar y pegar. Cuando dai no llega, deja al dev
+// parado exactamente donde estaba, no un paso atrás.
+function shellHint(tool, cmd) {
+  return `  Comando listo para correr a mano:\n    ${tool} ${cmd.map((c) => /\s/.test(c) ? `'${c}'` : c).join(" ")}\n`;
+}
+
+// La PR/MR abierta de esta branch, si la hay.
+//   { number, url, title, base } → existe · null → no hay · undefined → no se pudo saber
+// El `undefined` importa: sin binario, sin auth o con un glab viejo, dai no puede afirmar
+// que NO existe, así que sigue por el camino de crear (que también sabe reconocerla).
+function findExistingPr(tool, branch) {
+  try {
+    const out = execFileSync(tool, listPrCmd(tool, branch), { encoding: "utf8", cwd: process.cwd(), stdio: ["ignore", "pipe", "pipe"] });
+    return parsePrList(tool, out);
+  } catch { return undefined; }
+}
+
 // ── pr: crea TU PROPIA PR/MR precargada desde el template + el link ────────────
 // (Distinto de dai-review, que revisa la PR de OTRO. Tu PR la creas y revisas tú.)
 async function cmdPr(opts) {
@@ -906,9 +964,18 @@ async function cmdPr(opts) {
   };
   const closeRl = () => { if (_rl) { _rl.close(); _rl = null; } };
 
-  // Elegir la branch base (default main). Se pregunta justo después del aviso de cambios.
-  let base = opts.base;
-  if (!base) { const ans = await ask("  ¿Contra qué branch va la PR? (main) "); base = ans || "main"; }
+  // Elegir la branch base. El default NO es `main` fijo: sale de la config del repo
+  // (DAI_BRANCH_DEV / DAI_BRANCH_PROD) o de la rama default del remoto, y el preview lo dice.
+  // Con `main` hardcodeado, en un repo donde main DESPLIEGA A PRODUCCIÓN la MR quedaba
+  // proponiendo un merge a PRO y nada lo destacaba (issue #46).
+  if (opts.base === true) { closeRl(); fail("--base necesita el nombre de una branch (ej: --base develop).", 1); }
+  const baseFlag = Array.isArray(opts.base) ? opts.base[opts.base.length - 1] : (typeof opts.base === "string" ? opts.base : null);
+  let { base, source: baseSource, reason: baseWhy } = resolveBase({ flag: baseFlag, branch, env: process.env, originHead: originHeadBranch() });
+  if (!baseFlag) {
+    const ans = await ask(`  ¿Contra qué branch va la PR? (${base}) `);
+    if (ans) { base = ans; baseSource = "lo respondiste vos"; baseWhy = null; }
+  }
+  const toProd = isProdBranch(base, process.env);
 
   // La base puede no existir LOCAL (clones con --single-branch, repos donde el dev
   // trabaja sobre develop y la base es main, corporativos con la base solo en origin).
@@ -1012,13 +1079,40 @@ async function cmdPr(opts) {
   const forge = detectForge(parseRemote(remote)?.host);
   const tool = forgeTool(forge);
 
+  // ¿Ya hay una PR/MR abierta para esta branch? Si la hay, esto es una ACTUALIZACIÓN, y
+  // hay que decirlo ANTES de confirmar: el bug del issue #46 era pushear (el diff quedaba
+  // al día), fallar al crear, y dejar la MR con la descripción vieja sin avisar.
+  //   null → no hay ninguna abierta · undefined → no se pudo saber (sin binario, sin auth)
+  const existing = findExistingPr(tool, branch);
+
   // 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`);
+  const accion = existing ? `a ACTUALIZAR (#${existing.number})` : "a crear";
+  process.stdout.write(`\n  ── Pull Request ${accion} ──────────────────────────────\n`);
+  process.stdout.write(`  título:   ${title}\n  de:       ${branch}\n`);
+  process.stdout.write(`  a:        ${base}  ${C.dim(`(${baseSource}${baseWhy ? ` — ${baseWhy}` : ""})`)}${toProd ? `   ${C.b("⚠️  DESPLIEGA A PRODUCCIÓN")}` : ""}\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`);
+  const hint = baseHint(baseSource, base);
+  if (hint) info(hint);
+  if (existing) for (const l of describeUpdate(existing, { base, tool })) warn(l);
+
+  // 4a. Gate de producción: proponer un merge a la rama que despliega a PRO no puede salir
+  // de un default ni colarse con un `--yes` puesto por costumbre. Que lo diga alguien.
+  if (toProd) {
+    warn(`'${base}' está declarada como rama de PRODUCCIÓN (DAI_BRANCH_PROD).`);
+    if (!opts.toProd) {
+      if (opts.yes || !process.stdin.isTTY) {
+        closeRl();
+        fail(`no publico una PR contra producción sin que lo digas explícitamente.\n` +
+             `  Si es a propósito:            dai pr --base ${base} --to-prod --yes\n` +
+             `  Si era otra la base:          dai pr --base <rama-de-integracion>`, 1);
+      }
+      const a = await ask(`  Escribí '${base}' para confirmar que esta PR va a PRODUCCIÓN (Enter = cancelar): `);
+      if (String(a ?? "").trim() !== base) { closeRl(); info("Cancelado — no se creó la PR."); return; }
+    }
+  }
 
   // 4b. Gate: una PR con el molde del template sin llenar no se puede revisar.
   // Pasaba en repos reales — "Descripción" con el comentario HTML (que no se renderiza:
@@ -1044,8 +1138,8 @@ async function cmdPr(opts) {
   // Archivo de paso para gh/glab: en el temp del sistema, NO en el repo (no lo ensucia).
   const bodyFile = join(mkdtempSync(join(tmpdir(), "dai-pr-")), "body.md");
   if (!opts.yes) {
-    if (!process.stdin.isTTY) { closeRl(); writeFileSync(bodyFile, body); info(`Body guardado en ${bodyFile}. Revisa y re-ejecuta con --yes para crear.`); return; }
-    const a = (await ask(`  ¿Publico la branch y creo el PR con ${tool}? (s/N) `) || "").toLowerCase();
+    if (!process.stdin.isTTY) { closeRl(); writeFileSync(bodyFile, body); info(`Body guardado en ${bodyFile}. Revisa y re-ejecuta con --yes para ${existing ? "actualizar" : "crear"}.`); return; }
+    const a = (await ask(`  ¿Publico la branch y ${existing ? `actualizo la PR/MR #${existing.number}` : `creo el PR`} con ${tool}? (s/N) `) || "").toLowerCase();
     closeRl();
     if (!["s", "si", "sí", "y", "yes"].includes(a)) {
       writeFileSync(bodyFile, body);
@@ -1081,6 +1175,29 @@ async function cmdPr(opts) {
     fail(`no pude pushear la branch '${branch}'.`, 1);
   }
 
+  // Actualizar la PR/MR que ya está abierta: mismo body, misma disciplina. La alternativa
+  // —fallar y dejarla con la descripción vieja— es la que rompía el issue #46.
+  const doUpdate = (number) => {
+    const ucmd = updatePrCmd(tool, { number, title, body, bodyFile });
+    try {
+      info(`Actualizando la PR/MR #${number} con ${tool}…`);
+      const out = execFileSync(tool, ucmd, { encoding: "utf8", cwd: process.cwd() });
+      process.stdout.write(out);
+      ok(`PR/MR #${number} actualizada: título + descripción${existing?.url ? ` — ${existing.url}` : ""}.`);
+      try { rmSync(bodyFile); } catch { /* noop */ }
+      return true;
+    } catch (e) {
+      const msg = String(e.stderr || e.message || "");
+      warn(`no pude actualizar la PR/MR #${number} con ${tool}. El body quedó en ${bodyFile}.`);
+      if (msg.trim()) process.stdout.write(`  ${tool} dijo:\n  ${msg.trim().split("\n").join("\n  ")}\n`);
+      process.stdout.write(shellHint(tool, ucmd));
+      process.stdout.write(`  Si preferís no editarla: cerrá la PR/MR y volvé a correr \`dai pr\`.\n`);
+      process.exitCode = 1;
+      return false;
+    }
+  };
+  if (existing) { doUpdate(existing.number); return; }
+
   const cmd = tool === "gh"
     ? ["pr", "create", "--title", title, "--body-file", bodyFile, "--base", base,
        ...(opts.assignee ? ["--assignee", opts.assignee] : []), ...(opts.draft ? ["--draft"] : [])]
@@ -1094,7 +1211,18 @@ async function cmdPr(opts) {
     try { rmSync(bodyFile); } catch { /* noop */ }
   } catch (e) {
     const msg = String(e.stderr || e.message || "");
-    const manual = `  Comando listo para correr a mano:\n    ${tool} ${cmd.map((c) => /\s/.test(c) ? `'${c}'` : c).join(" ")}\n`;
+    const manual = shellHint(tool, cmd);
+    if (isAlreadyExistsError(msg) || isAlreadyExistsError(String(e.stdout || ""))) {
+      // La detección de arriba no la vio (glab viejo, `--output json` no soportado, sin
+      // permiso de lectura). El forge sí sabe que existe: se busca de nuevo y se actualiza.
+      warn("el forge dice que YA hay una PR/MR abierta para esta branch, así que no se creó otra.");
+      const found = findExistingPr(tool, branch);
+      if (found) { doUpdate(found.number); return; }
+      warn(`tampoco pude averiguar su número con ${tool}, así que NO toqué su descripción: quedó la vieja.`);
+      process.stdout.write(`  Abrila y pegá el body de ${bodyFile}, o cerrala y volvé a correr \`dai pr\`.\n`);
+      process.exitCode = 1;
+      return;
+    }
     if (e.code === "ENOENT") {
       // El binario del forge no está instalado (el caso más común detrás de "no salió la MR").
       const doc = tool === "glab" ? "https://gitlab.com/gitlab-org/cli/-/releases" : "https://cli.github.com";
@@ -1869,6 +1997,20 @@ function cmdDoctor() {
     }
   }
 
+  // ── flujo de branches: contra qué integra este repo, y qué rama es producción ──
+  // Sin esto declarado, `dai pr` adivina la base — y en un repo con ramas de ambiente
+  // adivinar significa proponer un merge a producción sin que nada lo destaque (issue #46).
+  info("flujo de branches (dai pr · dai done):");
+  const flow = branchFlow(process.env);
+  if (flow.dev) ok(`integración: ${flow.dev}  (DAI_BRANCH_DEV) — ahí van las PR de feature/ y fix/`);
+  else {
+    const { base: adivinada, source: src } = resolveBase({ env: process.env, originHead: originHeadBranch() });
+    warn(`sin DAI_BRANCH_DEV: las PR van a '${adivinada}', que sale de ${src}, no de tu config.`);
+    process.stdout.write("    Declaralo una vez en el .env.dai:  DAI_BRANCH_DEV=<rama-que-integra>\n");
+  }
+  if (flow.prod) ok(`producción: ${flow.prod}  (DAI_BRANCH_PROD) — ahí van release/ y hotfix/, con confirmación explícita`);
+  else info("sin DAI_BRANCH_PROD: dai no marca ninguna rama como producción (no adivina cuál es)");
+
   // ── version-drift del scaffold vs el CLI (ADR-0010) ──────────────────────────
   if (existsSync(join(process.cwd(), ".dai", "VERSION"))) { info("versión del scaffold:"); reportDrift(); }
 }
@@ -1881,8 +2023,21 @@ function cmdVersion() {
 
 let [cmd, ...rest] = process.argv.slice(2);
 if (cmd === "--version" || cmd === "-v") cmd = "version";
-if (cmd === "--help" || cmd === "-h") cmd = "help";
 const { opts, pos } = parseFlags(rest);
+
+// ── Convención de ayuda (vale para TODOS los comandos) ────────────────────────
+// Pedir ayuda nunca ejecuta nada: sale por stdout y termina con 0. Antes el `--help`
+// caía en `opts` y el comando corría igual — `dai stamp --help` dejaba un comentario en
+// el tracker y `dai pr --help` publicaba una branch. Los agentes lo pisan seguido, porque
+// probar `<cmd> --help` antes de usar un comando es exactamente lo que hay que hacer.
+if (isHelpToken(cmd) || cmd === undefined || wantsHelp({ opts, pos })) {
+  const { text, known } = helpFor(helpTopic(isHelpToken(cmd) ? null : cmd, pos));
+  if (known) { process.stdout.write(text); process.exit(0); }
+  process.stderr.write(`dai: no conozco el comando '${helpTopic(isHelpToken(cmd) ? null : cmd, pos)}'.\n\n`);
+  process.stderr.write(text);
+  process.exit(1);
+}
+
 switch (cmd) {
   case "ac-hash": cmdAcHash(pos[0]); break;
   case "ls":      cmdLs(opts); break;
@@ -1910,53 +2065,10 @@ switch (cmd) {
   case "doctor":  cmdDoctor(); break;
   case "version": cmdVersion(); break;
   default:
-    process.stderr.write(
-      "Uso: dai <comando> [args]\n\n" +
-      "Trazabilidad:\n" +
-      "  ac-hash <us.md>              calcula el ac_hash (ADR-0001)\n" +
-      "  ls [--json]                  lista lo que implementa el repo (ADR-0005)\n" +
-      "  publish <us.md>              crea la US en el tracker (Jira/ClickUp/md) y devuelve el key\n" +
-      "      [--parent KEY]           la cuelga de su épica · [--issuetype T] p. ej. Epic\n" +
-      "      [--field alias=valor]    campos propios que exige tu Jira (.dai/jira-fields.json); repetible\n" +
-      "  link-us <KEY> [--us <md>]    crea branch + implements.yaml; sin --us trae la US del tracker (ADR-0004)\n" +
-      "  link-us <KEY> --resync       re-estampa el ac_hash contra la US viva (tras un ⚠️ de check)\n" +
-      "  edit-us <KEY>                trae la US del tracker, la abrís en tu editor, valida el formato,\n" +
-      "                               muestra qué cambia y la guarda (para el PO)\n" +
-      "      [--no-editor]            no abre $EDITOR (para skills/scripts que ya escribieron el .md)\n" +
-      "      [--bump | --no-bump]     decide el spec_version sin preguntar (sin TTY no se toca y avisa)\n" +
-      "  update-us <KEY> [--us <md>]  empuja al tracker un .md que ya escribiste + re-estampa el ac_hash\n" +
-      "      [--dry-run] [--yes]      sin --yes muestra el diff y pide confirmación · [--no-resync]\n" +
-      "      [--strict]               las advertencias de formato también frenan · [--no-bump] no toca spec_version\n" +
-      "  check                        compara vs la US viva → atrasado (ADR-0003)\n" +
-      "  check --ci                   gate de CI: exige el link según branch-naming (chore/ y docs/ exentas)\n" +
-      "      [--branch b]             la branch a evaluar (en CI se detecta sola) · [--no-network]\n" +
-      "                               salidas: 0 pasa · 1 falta el link · 2 el QUÉ cambió\n" +
-      "  stamp [<ID>…] [--all]        estampa la cobertura en el tracker (ADR-0005)\n" +
-      "                               sin ID: la US de esta branch; si hay varias, pregunta\n" +
-      "  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" +
-      "      --description <texto>    QUÉ resuelve la PR y por qué → sección 'Descripción' (o --description-file <f>)\n" +
-      "      --changes <texto>        detalle de 'Cambios realizados' (default: los commits) (o --changes-file <f>)\n" +
-      "                               sin descripción y sin commits, con --yes o sin TTY, dai NO publica: la PR\n" +
-      "                               saldría con el molde del template y no se podría revisar\n" +
-      "  forge comment <ref> --body-file <f> · forge pr <ref>   comentar/leer una PR ajena (github/gitlab)\n" +
-      "  forge review <ref> --from <review.json> [--dry-run|--yes]  review inline: resumen + comentario por línea\n" +
-      "      --min-severity low|medium|high · --min-confidence 0..1 · --max-comments N · --base <branch>\n" +
-      "      Sin --yes no postea nada: muestra el preview y valida que cada hallazgo apunte al diff.\n\n" +
-      "Instalación:\n" +
-      "  skills install [--global | --local <repo>] [--force] [--dry-run] [--for <asistentes>]   instala las skills de dai (alias: `install`)\n" +
-      "  skills install --from <git-url|npm:pkg|path>[#ref] [--for <asistentes>]   instala skills EXTERNAS (por-stack), convertidas para los 3 asistentes (ADR-0013)\n" +
-      "  init [<repo>]                scaffolder interactivo del repo (asistente, gestor, OpenSpec)\n" +
-      "       --for <asistentes>      claude|copilot|cursor (combinables con coma) · o both|all (default all)\n" +
-      "                               ej: --for claude,cursor · --for copilot · --for all\n" +
-      "       --pm md|jira|clickup · --openspec   (con flags salteas las preguntas)\n" +
-      "  sync [<repo>] [--dry-run] [--for <asistentes>]   refresca skills/constitución/templates a la versión del CLI (aditivo; no toca .env.dai ni OpenSpec)\n" +
-      "  upgrade [--check] [--dry-run]   (alias: update) actualiza el CLI global a la última (npm i -g …@latest) y avisa si el repo quedó atrasado (ADR-0012)\n" +
-      "  docs <destino>               documentación conceptual → <destino>\n" +
-      "  doctor                       diagnóstico del entorno\n\n" +
-      "  (config: .env.dai — ver .env.dai.example)\n"
-    );
-    process.exit(cmd && cmd !== "help" ? 1 : 0);
+    // Comando desconocido: la ayuda global por stderr y salida ≠ 0 (la ayuda PEDIDA sale
+    // por stdout y con 0, arriba). Distinguirlos es lo que deja `dai foo --help` usable
+    // en un script sin tener que adivinar de dónde leer.
+    process.stderr.write(`dai: no conozco el comando '${cmd}'.\n\n`);
+    process.stderr.write(globalUsage());
+    process.exit(1);
 }

package/cli/lib/bootstrap.mjs

@@ -166,8 +166,19 @@ export function skillToCursor(md) {
 // tapaba la de ClickUp con team_id. Queda como override manual para trackers raros.
 export function envFor(pm) {
   const head = "# Config de dai — va en .env.dai (NO versionado), no en el .env del equipo.\n# Completá lo que falte. NUNCA commitees tokens.\n";
+  // Flujo de branches: sin esto, `dai pr` tiene que adivinar la base, y en un repo con
+  // ramas de ambiente adivinar significa proponer un merge a producción (issue #46).
+  // Van vacías a propósito: vacío = "no declarada", y dai cae a la default del remoto.
+  const flujo =
+    "\n# ── Flujo de branches (dai pr · dai done) ─────────────────────────────────\n" +
+    "# Las DOS ramas de vida larga del repo. La base de una PR sale del TIPO de branch:\n" +
+    "#   feature/ · fix/     → PR contra DAI_BRANCH_DEV\n" +
+    "#   release/ · hotfix/  → PR contra DAI_BRANCH_PROD, con confirmación explícita\n" +
+    "# Vacías = no declaradas: dai cae a la rama default del remoto y avisa que adivina.\n" +
+    "DAI_BRANCH_DEV=\n" +
+    "DAI_BRANCH_PROD=\n";
   if (pm === "clickup") {
-    return head + "DAI_PM=clickup\nDAI_CLICKUP_TOKEN=\nDAI_CLICKUP_LIST_ID=\n";
+    return head + "DAI_PM=clickup\nDAI_CLICKUP_TOKEN=\nDAI_CLICKUP_LIST_ID=\n" + flujo;
   }
   if (pm === "jira") {
     return head +
@@ -181,9 +192,9 @@ export function envFor(pm) {
       "# 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";
+      "# DAI_JIRA_FIELDS_FILE=.dai/jira-fields.json\n" + flujo;
   }
-  return head + "DAI_PM=md\nDAI_MD_US_DIR=.dai/us\n";
+  return head + "DAI_PM=md\nDAI_MD_US_DIR=.dai/us\n" + flujo;
 }
 
 // ── Helpers aditivos para `dai init` — no destruir la config de un repo vivo ──

package/cli/lib/branch-flow.mjs

@@ -0,0 +1,82 @@
+// dai · el mapa de ramas de vida larga del repo, y de ahí la base de cada PR (issue #46).
+//
+// El default `main` hardcodeado miente en cualquier repo cuyo flujo no sea el de GitHub:
+// con ramas de ambiente (`testing` integra, `main` DESPLIEGA A PRODUCCIÓN), `dai pr`
+// proponía mergear a producción y el preview no lo destacaba de ninguna forma. Había que
+// acordarse de `--base testing` en cada invocación; el día que alguien se olvida, la MR
+// queda apuntando a PRO y nada avisa.
+//
+// La primera versión pedía configurar "la base", y ese era el error de modelado: la base
+// NO es una constante, es una consecuencia del TIPO de branch —
+//
+//   feature/ · fix/ · lo que sea   → rama de integración   (DAI_BRANCH_DEV)
+//   release/ · hotfix/             → rama de producción    (DAI_BRANCH_PROD)
+//
+// Por eso no se configura una base: se declaran las DOS ramas de vida larga del repo, que
+// son dos hechos que dai no puede deducir de ningún lado, y la base sale del mapa.
+// Lo que dai NO hace es adivinar: sin `DAI_BRANCH_PROD` declarada no marca nada como
+// producción — inventar un gate sobre una suposición es peor que no tenerlo.
+
+import { branchType } from "./branch-scope.mjs";
+
+export const DEFAULT_BASE = "main";
+
+// Ramas de vida larga declaradas por el repo. `null` = no declarada (≠ vacía).
+export function branchFlow(env = {}) {
+  const val = (k) => String(env[k] ?? "").trim() || null;
+  return { dev: val("DAI_BRANCH_DEV"), prod: val("DAI_BRANCH_PROD") };
+}
+
+// Los tipos de branch que van contra producción: una release que se corta y un hotfix
+// que sale del tag que está en PRO. El resto integra.
+const HACIA_PROD = new Set(["release", "hotfix"]);
+
+// Resuelve la base de una PR y —tan importante como el valor— POR QUÉ es esa.
+//   --base > el mapa de ramas según el tipo de branch > rama default del remoto > main
+export function resolveBase({ flag, branch = null, env = {}, originHead = null } = {}) {
+  const explicit = typeof flag === "string" ? flag.trim() : "";
+  if (explicit) return { base: explicit, source: "--base", reason: null };
+
+  const flow = branchFlow(env);
+  const tipo = branchType(branch);
+  if (HACIA_PROD.has(tipo) && flow.prod) {
+    return { base: flow.prod, source: "DAI_BRANCH_PROD (.env.dai)", reason: `la branch es ${tipo}/` };
+  }
+  if (flow.dev) {
+    return { base: flow.dev, source: "DAI_BRANCH_DEV (.env.dai)", reason: null };
+  }
+  // Un repo puede declarar solo la de producción (flujo de una sola rama). Ahí la base es
+  // esa, y el gate de producción se dispara — que es exactamente lo que quiso quien la declaró.
+  if (flow.prod) return { base: flow.prod, source: "DAI_BRANCH_PROD (.env.dai)", reason: "es la única rama declarada" };
+
+  const head = String(originHead ?? "").trim();
+  if (head) return { base: head, source: "rama default de origin", reason: null };
+  return { base: DEFAULT_BASE, source: "default de dai", reason: null };
+}
+
+// ¿Esta base es la rama que despliega a producción? Solo si el repo lo declaró.
+export function isProdBranch(base, env = {}) {
+  const b = String(base ?? "").trim();
+  return b !== "" && b === branchFlow(env).prod;
+}
+
+// Las fuentes que YA son una decisión de alguien: no hay nada que avisar.
+const DECIDIDAS = new Set(["--base", "DAI_BRANCH_DEV (.env.dai)", "DAI_BRANCH_PROD (.env.dai)", "lo respondiste vos"]);
+
+// El aviso que va debajo del preview cuando la base salió de un default. Desaparece en
+// cuanto el repo declara su mapa de ramas, que es justo lo que se le pide.
+export function baseHint(source, base) {
+  if (DECIDIDAS.has(source)) return null;
+  return `la base '${base}' salió de ${source} — dai no sabe cuáles son las ramas de vida larga de este repo. Declaralas una vez en el .env.dai:\n` +
+         `    DAI_BRANCH_DEV=<rama-que-integra>   ·   DAI_BRANCH_PROD=<rama-que-despliega-a-PRO>\n` +
+         `    Con eso: feature/ y fix/ van contra DEV; release/ y hotfix/ contra PROD (con confirmación).`;
+}
+
+// Normaliza lo que devuelve `git symbolic-ref refs/remotes/origin/HEAD` → nombre de rama.
+//   "origin/main" → "main" · "refs/remotes/origin/main" → "main" · basura → null
+export function parseOriginHead(out) {
+  const s = String(out ?? "").trim();
+  if (!s) return null;
+  const m = s.match(/(?:^|\/)origin\/(.+)$/);
+  return m ? m[1].trim() || null : null;
+}

package/cli/lib/branch-scope.mjs

@@ -194,7 +194,16 @@ export function prScope({ branch, rows, allRows = rows, ids = [] }) {
   if (req.kind === "exempt") {
     return { mode: "exempt", target: null, candidates: rows, reason: `${req.reason} y su nombre no nombra ninguna US` };
   }
-  if (rows.length === 0) return { mode: "none", target: null, candidates: [], reason: "no hay implements.yaml vivo en el repo" };
+  // El repo no tiene NINGUNA US viva. Exigirle un link a una branch que el propio
+  // branch-naming declara exenta es pedir algo que no existe: `fix/lo-que-sea` (sin ID en
+  // el nombre) terminaba con "corré dai link-us primero" y el consejo de renombrarla a
+  // `chore/`, que para un fix es directamente el consejo equivocado. Le pasa a cualquier
+  // repo de tooling — al de dai, sin ir más lejos, que no se trackea a sí mismo con US.
+  if (rows.length === 0) {
+    return req.required
+      ? { mode: "none", target: null, candidates: [], reason: "no hay implements.yaml vivo en el repo" }
+      : { mode: "exempt", target: null, candidates: [], reason: `${req.reason}, y el repo no declara ninguna US` };
+  }
   if (rows.length === 1) return { mode: "only", target: rows[0], candidates: rows, reason: "es la única US viva del repo" };
   return { mode: "ambiguous", target: null, candidates: rows, reason: `hay ${rows.length} US vivas y la branch '${branch}' no dice cuál` };
 }

package/cli/lib/help.mjs

@@ -0,0 +1,448 @@
+// dai · la ayuda del CLI, y la CONVENCIÓN de cómo se pide.
+//
+// El bug que originó este archivo: `dai <comando> --help` no imprimía ayuda — el flag caía
+// en `opts` y el comando SE EJECUTABA igual. Con comandos que hablan hacia afuera eso no es
+// una molestia: `dai stamp --help` dejaba un comentario en el tracker, `dai pr --help`
+// publicaba una branch y abría una PR. Los agentes lo pisan seguido, porque probar
+// `<cmd> --help` antes de usar un comando es exactamente lo que hay que hacer.
+//
+// La convención, para que valga en TODOS los comandos y no haya que recordar cuál la
+// implementa: pedir ayuda NUNCA ejecuta nada, siempre sale por stdout y siempre con 0.
+//   dai help · dai --help · dai -h
+//   dai help <comando> · dai <comando> --help · dai <comando> -h · dai <comando> help
+
+// Tokens que significan "quiero la ayuda", en cualquier posición razonable.
+// `-h` entra como POSICIONAL (el parser solo entiende `--`), por eso está en la lista.
+export const HELP_TOKENS = new Set(["help", "-h", "-help", "--help", "ayuda", "?"]);
+
+export const isHelpToken = (t) => HELP_TOKENS.has(String(t ?? "").toLowerCase());
+
+// ¿Esta invocación pide ayuda en vez de ejecutar?
+export function wantsHelp({ opts = {}, pos = [] } = {}) {
+  if ("help" in opts || "h" in opts) return true;
+  return pos.some(isHelpToken);
+}
+
+// Alias → comando canónico (para que `dai mr --help` no quede sin ayuda).
+export const HELP_ALIAS = {
+  mr: "pr", update: "upgrade", install: "skills", "skills-install": "skills",
+  "link": "link-us", "us": "link-us",
+};
+
+// El tema del que se pide ayuda: el comando, o el primer positivo que no sea un token
+// de ayuda (`dai help pr`). Devuelve null para la ayuda global.
+export function helpTopic(cmd, pos = []) {
+  const c = String(cmd ?? "").toLowerCase();
+  if (c && !isHelpToken(c)) return HELP_ALIAS[c] || c;
+  const t = pos.map((p) => String(p).toLowerCase()).find((p) => !isHelpToken(p));
+  return t ? (HELP_ALIAS[t] || t) : null;
+}
+
+// ── Ayuda por comando ────────────────────────────────────────────────────────
+// Cada entrada es autocontenida: qué hace, cómo se invoca, sus flags y un ejemplo real.
+export const COMMAND_HELP = {
+  "ac-hash": `dai ac-hash — calcula el ac_hash de una US (ADR-0001)
+
+Uso:
+  dai ac-hash <us.md>
+
+Qué hace:
+  Extrae la sección "Criterios de aceptación", la normaliza y devuelve su SHA-256 truncado
+  a 8 hex. Es el mismo número que estampa \`dai link-us\` y compara \`dai check\`: si el QUÉ
+  cambia, cambia el hash, y los CÓMO que lo implementaban quedan marcados como atrasados.
+
+Ejemplo:
+  dai ac-hash .dai/us/ABC-482.md
+`,
+
+  ls: `dai ls — lista lo que este repo implementa (ADR-0005)
+
+Uso:
+  dai ls [--json] [--root <dir>]
+
+Qué hace:
+  Recorre los implements.yaml del repo y muestra cada US linkeada con su versión, su
+  ac_hash y el change de OpenSpec al que pertenece. Con --json sale la misma info
+  estructurada, para scripts y CI.
+
+Ejemplo:
+  dai ls --json | jq '.[].id'
+`,
+
+  "link-us": `dai link-us — crea la branch + el implements.yaml (el link QUÉ↔CÓMO, ADR-0004)
+
+Uso:
+  dai link-us <KEY> [--us <us.md>] [--title <t>] [--change <c>] [--repo <r>] [--base <rama>]
+  dai link-us <KEY> --resync
+  dai link-us <KEY> --dry-run
+
+Qué hace:
+  Trae la US del tracker (o la lee del .md que le pases), calcula el ac_hash, crea la
+  branch con el nombre canónico (governance/branch-naming.md) y escribe el implements.yaml.
+  El KEY nunca se tipea a mano en la branch: sale del argumento.
+
+Opciones:
+  --us <us.md>     fuente local en vez del tracker (útil sin red/token)
+  --resync         re-estampa el ac_hash contra la US viva, sin crear branch (tras un ⚠ de check)
+  --title <t>      pisa el título (y por lo tanto el slug de la branch)
+  --change <c>     nombre del change de OpenSpec (default: el slug del título)
+  --base <rama>    de qué rama sale la branch nueva (default: donde estás parado)
+  --dry-run        muestra branch + yaml y no toca nada
+
+Notas:
+  Si la US no declara \`spec_version\`, el link queda con \`version: pendiente\` y dai avisa:
+  un \`v1\` inventado se publica en la PR y se estampa en el tracker como si fuera un dato.
+
+Ejemplo:
+  dai link-us ABC-482
+  dai link-us ABC-482 --resync
+`,
+
+  check: `dai check — ¿tu implementación sigue cubriendo el QUÉ? (ADR-0003)
+
+Uso:
+  dai check
+  dai check --ci [--branch <rama>] [--no-network]
+
+Qué hace:
+  Compara el ac_hash estampado en cada implements.yaml contra la US viva del tracker.
+  Al día = el QUÉ no se movió. Atrasado = alguien cambió los criterios y tu CÓMO todavía
+  no los cubre.
+
+Modo --ci (gate de governance/ci-rules.md):
+  Exige el link según el nombre de la branch — chore/, docs/, ci/, release/ y hotfix/
+  están exentas. Salidas:  0 pasa · 1 falta el link · 2 el QUÉ cambió.
+  --branch <rama>   la branch a evaluar (en CI se detecta sola)
+  --no-network      valida solo que el link exista (sin consultar al tracker)
+
+Ejemplo:
+  dai check
+  dai check --ci --branch feature/ABC-482-checkout
+`,
+
+  stamp: `dai stamp — estampa la cobertura en el tracker (ADR-0005, ADR-0018)
+
+Uso:
+  dai stamp [<ID>…] [--all] [--dry-run]
+
+Qué hace:
+  Deja en la US un comentario con qué repo/change/branch/commit la implementa y en qué
+  estado quedó. Sin ID estampa la US de ESTA branch; si hay varias candidatas pregunta,
+  porque un comentario en el tracker no se deshace.
+
+Opciones:
+  --all        estampa todas las US del repo (úsalo a sabiendas)
+  --dry-run    muestra qué estamparía y no escribe nada
+
+Ejemplo:
+  dai stamp --dry-run
+`,
+
+  "update-us": `dai update-us — empuja al tracker un .md que ya escribiste
+
+Uso:
+  dai update-us <ID> [--us <us.md>] [--dry-run] [--yes] [--strict] [--no-resync] [--no-bump]
+
+Qué hace:
+  Valida el formato de la US, muestra el diff contra lo que hay en el tracker, propone
+  subir el spec_version si cambiaron los criterios, publica y re-estampa el ac_hash local.
+
+Opciones:
+  --yes         no pregunta (sin --yes muestra el diff y pide confirmación)
+  --strict      las advertencias de formato también frenan
+  --no-resync   no re-estampa el ac_hash en el implements.yaml
+  --no-bump     no toca el spec_version
+
+Ejemplo:
+  dai update-us ABC-482 --us borrador.md --dry-run
+`,
+
+  "edit-us": `dai edit-us — editar el QUÉ con red de seguridad (para el PO)
+
+Uso:
+  dai edit-us <ID> [--no-editor] [--bump | --no-bump] [--yes]
+
+Qué hace:
+  Trae la US del tracker, la abre en tu $EDITOR, valida el formato al guardar, te muestra
+  qué cambia y recién entonces la escribe. Pregunta si el cambio es material para subir
+  el spec_version — esa decisión es de la persona, no de dai.
+
+Opciones:
+  --no-editor          no abre $EDITOR (para skills/scripts que ya escribieron el .md)
+  --bump / --no-bump   decide el spec_version sin preguntar (sin TTY no se toca y avisa)
+
+Ejemplo:
+  dai edit-us ABC-482
+`,
+
+  publish: `dai publish — crea la US en el tracker y devuelve su key
+
+Uso:
+  dai publish <us.md> [--parent <KEY>] [--issuetype <T>] [--field alias=valor]…
+
+Qué hace:
+  Valida el formato y crea el issue/tarea en el backend configurado (DAI_PM). Devuelve el
+  key para que \`dai link-us\` lo use.
+
+Opciones:
+  --parent <KEY>       la cuelga de su épica
+  --issuetype <T>      tipo de issue (p. ej. Epic; default DAI_JIRA_ISSUETYPE o Story)
+  --field alias=valor  campos propios que exige tu Jira (.dai/jira-fields.json); repetible
+
+Ejemplo:
+  dai publish us.md --parent ABC-100 --field clasificacion=Evolutiva
+`,
+
+  pr: `dai pr — crea (o ACTUALIZA) TU Pull/Merge Request precargada
+
+Uso:
+  dai pr [--base <rama>] [--us <ID>] [--title <t>] [--assignee <u>] [--draft] [--yes]
+  dai pr --description <texto> | --description-file <archivo>
+  dai pr --changes <texto>     | --changes-file <archivo>
+  dai mr …                     alias para GitLab (merge request)
+
+Qué hace:
+  Resuelve la US de esta branch, corre la verificación de trazabilidad, arma el body desde
+  el template del repo, TE MUESTRA el preview y pide confirmación. Si la branch ya tiene
+  una PR/MR abierta, la ACTUALIZA (título + descripción) en vez de fallar a mitad de camino.
+
+La branch base sale del TIPO de branch, no de un default fijo:
+  feature/ · fix/ · el resto  →  DAI_BRANCH_DEV   (la rama que integra)
+  release/ · hotfix/          →  DAI_BRANCH_PROD  (la que despliega a producción)
+  --base gana siempre; sin nada declarado cae a la rama default de origin, avisando.
+  El preview dice de dónde salió la base. Contra DAI_BRANCH_PROD pide confirmación
+  explícita — hay que escribir el nombre de la rama, y con --yes agregar --to-prod.
+
+Opciones:
+  --base <rama>          contra qué rama va la PR
+  --to-prod              confirma que la base es producción (obligatorio junto a --yes)
+  --us <ID>              con qué US titularla, si la branch toca varias
+  --title <t>            pisa el título
+  --description[-file]   QUÉ resuelve la PR y por qué → sección "Descripción"
+  --changes[-file]       detalle de "Cambios realizados" (default: los commits)
+  --assignee <u>         asigna la PR · --draft: la crea en borrador
+  --yes                  no pregunta (igual frena si el body saldría con el molde vacío)
+
+Ejemplo:
+  dai pr --base develop --description-file notas.md
+`,
+
+  done: `dai done — cierra la US: vuelve a la base, actualiza y borra la branch local
+
+Uso:
+  dai done [--base <rama>] [--force]
+
+Qué hace:
+  Verifica que no queden cambios sueltos ni commits sin pushear, vuelve a la base, hace
+  fetch + pull --ff-only y borra la branch local SOLO si ya está mergeada.
+  La base se resuelve igual que en \`dai pr\`: del tipo de branch (DAI_BRANCH_DEV /
+  DAI_BRANCH_PROD), o de la rama default de origin si el repo no las declaró.
+
+Opciones:
+  --force    borra la branch aunque no esté mergeada
+
+Ejemplo:
+  dai done --base develop
+`,
+
+  archive: `dai archive — funde los delta specs y archiva el change (ADR-0011)
+
+Uso:
+  dai archive [<change>] [--skip-specs]
+
+Qué hace:
+  Mueve el change de OpenSpec a archive/ y funde sus delta specs en las specs canónicas.
+  Lo corre QUIEN APRUEBA la PR, no quien la abre: es el gate de aprobación.
+
+Ejemplo:
+  dai archive checkout-sin-duplicado
+`,
+
+  forge: `dai forge — hablarle a una PR/MR AJENA (github/gitlab)
+
+Uso:
+  dai forge pr <ref>                          lee la PR/MR
+  dai forge comment <ref> --body-file <f>     comenta en el hilo
+  dai forge review <ref> --from <review.json> [--dry-run | --yes]
+
+Qué hace:
+  \`review\` postea un review INLINE: un comentario de resumen más uno anclado a cada
+  archivo:línea. Sin --yes no postea nada: muestra el preview y valida que cada hallazgo
+  apunte de verdad al diff (descarta las líneas que el modelo inventó).
+
+Opciones de review:
+  --min-severity low|medium|high · --min-confidence 0..1 · --max-comments N · --base <rama>
+
+Auth:
+  GITHUB_TOKEN / GITLAB_TOKEN en el .env.dai (token scopeado; git sigue usando SSH).
+
+Ejemplo:
+  dai forge review 42 --from review.json --dry-run
+`,
+
+  skills: `dai skills install — instala las skills de dai (alias: dai install)
+
+Uso:
+  dai skills install [--global | --local <repo>] [--force] [--dry-run] [--for <asistentes>]
+  dai skills install --from <git-url|npm:pkg|path>[#ref] [--for <asistentes>]
+
+Qué hace:
+  Copia las skills al asistente (Claude, Copilot, Cursor). Con --from instala skills
+  EXTERNAS por-stack, convertidas para los tres asistentes (ADR-0013).
+
+Opciones:
+  --for <asistentes>   claude|copilot|cursor (combinables con coma) · both|all (default all)
+  --global             al home del asistente · --local <repo>: dentro de un repo
+  --force              pisa lo que haya · --dry-run: muestra y no escribe
+
+Ejemplo:
+  dai skills install --global --for claude,cursor
+`,
+
+  init: `dai init — scaffolder del repo (asistente, gestor, OpenSpec)
+
+Uso:
+  dai init [<repo>] [--for <asistentes>] [--pm md|jira|clickup] [--openspec]
+
+Qué hace:
+  Interroga y deja el repo listo: skills del asistente, constitución, templates,
+  .env.dai.example, gitignore y el gate de CI. Con flags te saltea las preguntas.
+
+Opciones:
+  --for <asistentes>   claude|copilot|cursor (combinables con coma) · both|all (default all)
+  --pm <backend>       backend del tracker · --openspec: además scaffoldea OpenSpec
+
+Ejemplo:
+  dai init --for claude,copilot --pm jira --openspec
+`,
+
+  sync: `dai sync — refresca el scaffolding a la versión del CLI (ADR-0010)
+
+Uso:
+  dai sync [<repo>] [--dry-run] [--for <asistentes>]
+
+Qué hace:
+  Actualiza skills, constitución y templates a los de esta versión de dai. Es ADITIVO:
+  no toca el .env.dai ni tus archivos de OpenSpec.
+
+Ejemplo:
+  dai sync --dry-run
+`,
+
+  upgrade: `dai upgrade — actualiza el CLI global (alias: dai update, ADR-0012)
+
+Uso:
+  dai upgrade [--check] [--dry-run]
+
+Qué hace:
+  Instala la última versión publicada (npm i -g …@latest) y avisa si el scaffolding del
+  repo quedó atrasado respecto del CLI.
+
+Opciones:
+  --check      solo dice si hay una versión nueva
+  --dry-run    muestra el comando y no lo corre
+
+Ejemplo:
+  dai upgrade --check
+`,
+
+  docs: `dai docs — copia la documentación conceptual a un destino
+
+Uso:
+  dai docs <destino>
+
+Ejemplo:
+  dai docs ./docs/metodologia
+`,
+
+  doctor: `dai doctor — diagnóstico del entorno
+
+Uso:
+  dai doctor
+
+Qué hace:
+  Revisa skills instaladas por asistente, constitución, comandos de OpenSpec, el backend
+  de PM configurado, el remoto/forge y el cliente ssh, y avisa si el scaffolding del repo
+  quedó atrasado respecto del CLI.
+`,
+
+  version: `dai version — versión del CLI (alias: --version, -v)
+
+Uso:
+  dai version
+
+Además avisa si el scaffolding de este repo quedó atrasado respecto del CLI (ADR-0010).
+`,
+
+  help: `dai help — ayuda del CLI
+
+Uso:
+  dai help              todos los comandos
+  dai help <comando>    el detalle de uno
+  dai <comando> --help  lo mismo (también -h, o \`dai <comando> help\`)
+
+Pedir ayuda NUNCA ejecuta el comando: sale por stdout y termina con 0.
+`,
+};
+
+// ── Ayuda global ─────────────────────────────────────────────────────────────
+export function globalUsage() {
+  return (
+    "Uso: dai <comando> [args]\n\n" +
+    "Trazabilidad:\n" +
+    "  ac-hash <us.md>              calcula el ac_hash (ADR-0001)\n" +
+    "  ls [--json]                  lista lo que implementa el repo (ADR-0005)\n" +
+    "  publish <us.md>              crea la US en el tracker (Jira/ClickUp/md) y devuelve el key\n" +
+    "      [--parent KEY]           la cuelga de su épica · [--issuetype T] p. ej. Epic\n" +
+    "      [--field alias=valor]    campos propios que exige tu Jira (.dai/jira-fields.json); repetible\n" +
+    "  link-us <KEY> [--us <md>]    crea branch + implements.yaml; sin --us trae la US del tracker (ADR-0004)\n" +
+    "  link-us <KEY> --resync       re-estampa el ac_hash contra la US viva (tras un ⚠️ de check)\n" +
+    "  edit-us <KEY>                trae la US del tracker, la abrís en tu editor, valida el formato,\n" +
+    "                               muestra qué cambia y la guarda (para el PO)\n" +
+    "      [--no-editor]            no abre $EDITOR (para skills/scripts que ya escribieron el .md)\n" +
+    "      [--bump | --no-bump]     decide el spec_version sin preguntar (sin TTY no se toca y avisa)\n" +
+    "  update-us <KEY> [--us <md>]  empuja al tracker un .md que ya escribiste + re-estampa el ac_hash\n" +
+    "      [--dry-run] [--yes]      sin --yes muestra el diff y pide confirmación · [--no-resync]\n" +
+    "      [--strict]               las advertencias de formato también frenan · [--no-bump] no toca spec_version\n" +
+    "  check                        compara vs la US viva → atrasado (ADR-0003)\n" +
+    "  check --ci                   gate de CI: exige el link según branch-naming (chore/ y docs/ exentas)\n" +
+    "      [--branch b]             la branch a evaluar (en CI se detecta sola) · [--no-network]\n" +
+    "                               salidas: 0 pasa · 1 falta el link · 2 el QUÉ cambió\n" +
+    "  stamp [<ID>…] [--all]        estampa la cobertura en el tracker (ADR-0005)\n" +
+    "                               sin ID: la US de esta branch; si hay varias, pregunta\n" +
+    "  done [--base b] [--force]    cierra la US: vuelve a la base, actualiza y borra la branch local\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 o ACTUALIZA TU PR/MR precargada (muestra + confirma)\n" +
+    "      [--us <ID>] [--title t]  la US la resuelve la branch; si hay varias, pregunta (sin TTY, falla)\n" +
+    "      --description <texto>    QUÉ resuelve la PR y por qué → sección 'Descripción' (o --description-file <f>)\n" +
+    "      --changes <texto>        detalle de 'Cambios realizados' (default: los commits) (o --changes-file <f>)\n" +
+    "      [--to-prod]              confirma una PR contra la rama de producción (DAI_BRANCH_PROD)\n" +
+    "                               sin descripción y sin commits, con --yes o sin TTY, dai NO publica: la PR\n" +
+    "                               saldría con el molde del template y no se podría revisar\n" +
+    "  forge comment <ref> --body-file <f> · forge pr <ref>   comentar/leer una PR ajena (github/gitlab)\n" +
+    "  forge review <ref> --from <review.json> [--dry-run|--yes]  review inline: resumen + comentario por línea\n" +
+    "      --min-severity low|medium|high · --min-confidence 0..1 · --max-comments N · --base <branch>\n" +
+    "      Sin --yes no postea nada: muestra el preview y valida que cada hallazgo apunte al diff.\n\n" +
+    "Instalación:\n" +
+    "  skills install [--global | --local <repo>] [--force] [--dry-run] [--for <asistentes>]   instala las skills de dai (alias: `install`)\n" +
+    "  skills install --from <git-url|npm:pkg|path>[#ref] [--for <asistentes>]   instala skills EXTERNAS (por-stack), convertidas para los 3 asistentes (ADR-0013)\n" +
+    "  init [<repo>]                scaffolder interactivo del repo (asistente, gestor, OpenSpec)\n" +
+    "       --for <asistentes>      claude|copilot|cursor (combinables con coma) · o both|all (default all)\n" +
+    "                               ej: --for claude,cursor · --for copilot · --for all\n" +
+    "       --pm md|jira|clickup · --openspec   (con flags salteas las preguntas)\n" +
+    "  sync [<repo>] [--dry-run] [--for <asistentes>]   refresca skills/constitución/templates a la versión del CLI (aditivo; no toca .env.dai ni OpenSpec)\n" +
+    "  upgrade [--check] [--dry-run]   (alias: update) actualiza el CLI global a la última (npm i -g …@latest) y avisa si el repo quedó atrasado (ADR-0012)\n" +
+    "  docs <destino>               documentación conceptual → <destino>\n" +
+    "  doctor                       diagnóstico del entorno\n" +
+    "  help [<comando>]             el detalle de un comando (también: dai <comando> --help)\n\n" +
+    "  (config: .env.dai — ver .env.dai.example)\n"
+  );
+}
+
+// El texto a imprimir para un tema. null/desconocido → la ayuda global.
+export function helpFor(topic) {
+  if (!topic) return { text: globalUsage(), known: true };
+  const key = HELP_ALIAS[topic] || topic;
+  const text = COMMAND_HELP[key];
+  return text ? { text, known: true } : { text: globalUsage(), known: false };
+}

package/cli/lib/pr-remote.mjs

@@ -0,0 +1,80 @@
+// dai · la PR/MR que YA existe para esta branch: cómo buscarla, cómo actualizarla (issue #46).
+//
+// El bug: con una MR ya abierta, `dai pr` pusheaba la branch (el diff quedaba al día) y
+// después `glab mr create` fallaba porque la MR existía. El body NO se actualizaba y lo
+// único que se veía era el comando crudo del forge, sin un error legible. Resultado: una
+// MR con el diff correcto y una descripción que MIENTE sobre lo que contiene — el peor de
+// los dos mundos, porque parece que salió bien.
+//
+// Acá está la parte pura y testeable: armar los comandos del forge y leer lo que devuelven.
+// Los efectos (execFileSync) viven en dai.mjs.
+
+// ── Buscar la PR/MR abierta de una branch ────────────────────────────────────
+export function listPrCmd(tool, branch) {
+  if (tool === "gh") {
+    return ["pr", "list", "--head", branch, "--state", "open", "--limit", "5",
+            "--json", "number,url,title,baseRefName"];
+  }
+  return ["mr", "list", "--source-branch", branch, "--per-page", "5", "--output", "json"];
+}
+
+// Normaliza la respuesta de gh/glab a la MISMA forma: { number, url, title, base }.
+// Devuelve null si no hay ninguna abierta. Tira si el JSON no parsea — quien llama decide
+// si eso es fatal (no lo es: se sigue por el camino de crear, que también sabe fallar bien).
+export function parsePrList(tool, stdout) {
+  const raw = String(stdout ?? "").trim();
+  if (!raw) return null;
+  const arr = JSON.parse(raw);
+  const list = Array.isArray(arr) ? arr : Array.isArray(arr?.items) ? arr.items : [];
+  for (const it of list) {
+    // glab devuelve TODAS las MR de la branch si no se filtra por estado: las cerradas y
+    // mergeadas no cuentan — reabrir una MR mergeada no es lo que pidió nadie.
+    const state = String(it.state ?? "opened").toLowerCase();
+    if (!["open", "opened"].includes(state)) continue;
+    const number = it.number ?? it.iid ?? null;
+    if (number == null) continue;
+    return {
+      number: Number(number),
+      url: it.url ?? it.web_url ?? null,
+      title: it.title ?? null,
+      base: it.baseRefName ?? it.target_branch ?? null,
+    };
+  }
+  return null;
+}
+
+// ── Actualizar el body/título de una PR/MR existente ─────────────────────────
+// gh lee el body de un archivo; glab lo toma como string (igual que en `mr create`, que
+// ya funciona así). Por eso la firma pide los dos y cada uno usa el que le sirve.
+export function updatePrCmd(tool, { number, title, body, bodyFile }) {
+  if (tool === "gh") {
+    return ["pr", "edit", String(number), "--title", title, "--body-file", bodyFile];
+  }
+  return ["mr", "update", String(number), "--title", title, "--description", body, "--yes"];
+}
+
+// ── "ya existe una PR para esta branch" ──────────────────────────────────────
+// El forge lo dice de formas distintas y en inglés. Se reconoce para poder pasar al camino
+// de actualizar en vez de morir con el comando crudo en pantalla.
+const ALREADY = [
+  /already exists/i,
+  /a merge request already exists/i,
+  /existing (?:pull request|merge request)/i,
+  /pull request for branch .* already exists/i,
+  /open merge request already exists/i,
+];
+export function isAlreadyExistsError(msg) {
+  const s = String(msg ?? "");
+  return ALREADY.some((re) => re.test(s));
+}
+
+// Lo que se le muestra al dev cuando dai detecta la PR existente: qué va a pasar con ella.
+export function describeUpdate(pr, { base, tool }) {
+  const lines = [`ya hay una PR/MR abierta para esta branch: #${pr.number}${pr.url ? ` — ${pr.url}` : ""}`];
+  if (pr.base && base && pr.base !== base) {
+    lines.push(`ojo: apunta a '${pr.base}' y vos pediste '${base}'. dai NO cambia la base de una PR abierta: ` +
+               `si querés otra base, cerrala y creá una nueva.`);
+  }
+  lines.push(`dai va a ACTUALIZAR su título y su descripción con ${tool} (el diff ya lo actualiza el push).`);
+  return lines;
+}

package/cli/lib/us-format.mjs

@@ -108,8 +108,19 @@ export function validateUS(md) {
 // (METODOLOGIA §4). Sube cuando el cambio es material, y eso lo sabe el PO: dai
 // mirando el hash no puede distinguir un criterio nuevo de un typo corregido.
 
+// La US se escribe a mano en un tracker, así que el nombre del campo llega como salga:
+// `spec_version`, `spec version`, `spec-version` y —visto en un Jira real— `specversion`
+// pegado. Con el `[_ ]` obligatorio de antes, `| specversion | v4 |` no matcheaba y el
+// link se estampaba en `v1` sin que nada avisara (issue #46). El separador es opcional.
+export const SPEC_VERSION_RE = /spec[\s_-]*version[^\n]*?\b(v\d+)\b/i;
+
+// El valor que se escribe cuando la US NO declara versión. Un placeholder VISIBLE es
+// mejor que un `v1` que parece correcto: el `v1` se publica en la PR y se estampa en el
+// tracker como si fuera un dato, cuando es una suposición de dai.
+export const PENDING_VERSION = "pendiente";
+
 export const parseSpecVersion = (md) => {
-  const m = String(md || "").match(/spec[_ ]version[^\n]*?\b(v\d+)\b/i);
+  const m = String(md || "").match(SPEC_VERSION_RE);
   return m ? m[1] : null;
 };
 
@@ -123,8 +134,8 @@ export const bumpSpecVersion = (v) => {
 // al final, donde nadie lo ve, ni en una tabla que no existe.
 export function setSpecVersion(md, version) {
   const text = String(md || "");
-  if (/spec[_ ]version[^\n]*?\bv\d+\b/i.test(text)) {
-    return text.replace(/(spec[_ ]version[^\n]*?\b)v\d+\b/i, `$1${version}`);
+  if (SPEC_VERSION_RE.test(text)) {
+    return text.replace(/(spec[\s_-]*version[^\n]*?\b)v\d+\b/i, `$1${version}`);
   }
   const lines = text.split(/\r?\n/);
   const i = lines.findIndex((l) => /^#\s+\S/.test(l));

package/cli/lib/us.mjs

@@ -3,12 +3,15 @@
 
 import { acHash } from "./ac-hash.mjs";
 import { extractTitle } from "./link-us.mjs";
+import { parseSpecVersion } from "./us-format.mjs";
 
 // Parseo puro de una US (markdown o texto) → identidad + hash vivo.
 export function parseUS(raw) {
   const title = extractTitle(raw);
-  const m = raw.match(/spec[_ ]version[^\n]*?\b(v\d+)\b/i);
-  return { title, spec_version: m ? m[1] : null, ac_hash: acHash(raw) };
+  // El regex vive en us-format.mjs: es UNO solo para leer, escribir y bumpear la versión.
+  // Duplicado acá, la variante `specversion` (sin separador) se arreglaba en un lado y
+  // seguía rota en el otro — que es exactamente como nació el issue #46.
+  return { title, spec_version: parseSpecVersion(raw), ac_hash: acHash(raw) };
 }
 
 // Compara el hash estampado (implements.yaml) con el hash vivo de la US.

package/governance/branch-naming.md

@@ -20,7 +20,21 @@ Ejemplo: `feature/ABC-482-finalizar-compra-sin-duplicado`
 - El **ID nunca se tipea a mano**: sale del argumento de `/link-us ABC-###`. Elimina
   el error de tipeo que rompe el link ([Art. 8](../docs/MANIFIESTO.md#art-8), Art. 9).
 - El **slug** deriva del título de la US: minúsculas, sin acentos ni ñ, espacios → `-`.
-- La **base** de la rama sigue la convención del repo (`main` o `develop`).
+- La **base** de una PR no se recuerda ni se configura una por una: sale del **tipo de
+  rama**, leyendo las dos ramas de vida larga que el repo declara en su `.env.dai`.
+
+  | Tipo de rama | PR contra | Variable |
+  |---|---|---|
+  | `feature/`, `fix/`, el resto | la rama que integra | `DAI_BRANCH_DEV` |
+  | `release/`, `hotfix/` | la rama que despliega a producción | `DAI_BRANCH_PROD` |
+
+  `dai pr` y `dai done` usan ese mapa; `--base` siempre gana. Si `DAI_BRANCH_DEV` no está
+  declarada, dai usa la rama default del remoto y **avisa que la está adivinando**.
+- Apuntarle a `DAI_BRANCH_PROD` pide una **confirmación explícita**: hay que escribir el
+  nombre de la rama, y con `--yes` hace falta `--to-prod`. En repos con ramas de ambiente
+  (`testing` integra, `main` va a producción) esto es lo que evita que una PR quede
+  proponiendo un despliegue que nadie pidió. Sin la variable declarada, dai no marca
+  ninguna rama como producción: no adivina cuál es.
 - Una rama, una US. Si una US toca varios repos, es una rama por repo, **todas con el
   mismo `ABC-###`** — así el índice las agrupa en una fila (federación).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforce2055/dai",
-  "version": "0.13.3",
+  "version": "0.14.0",
   "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/",