@dforce2055/dai 0.13.2 → 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,116 @@
 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
+spec estaba "verificado con dai check: ✅ al día", y a continuación una explicación general
+del método. Tirando de ese hilo aparecieron dos bugs distintos, y los dos eran dai afirmando
+cosas que no le constaban.**
+
+### Arreglado
+- **El relleno del estado reescribía la prosa del template.** `dai pr` hacía un replace
+  **global** de `verificado con `dai check` ✅`, y esa frase estaba dos veces en el molde: en
+  el dato (`## 🔗 Implementa`) y en la prosa que explica el método. Así que a una oración
+  general —igual en todas las PRs— dai le insertaba el estado de *esta* PR, y quedaba
+  publicado: *"verificado con `dai check`: ✅ al día. Sin esto, el código no sabe a qué QUÉ
+  responde…"*. Ni doctrina ni dato. Ahora el relleno se acota a la sección; sin la sección
+  (un template ajeno con otra forma) cae al body entero, porque rellenar de más es
+  recuperable y publicar `ABC-###` no.
+- **`dai pr` decía "❓ sin US" cuando el tracker no contestaba** — dos líneas debajo del id de
+  la US que sí existe. `coverageStatus` colapsaba en un mismo `sin-us` dos cosas que no
+  significan lo mismo: *el tracker contestó y la US no está* y *no hubo respuesta* (sin red,
+  sin token, 5xx, certificado corporativo). Los adaptadores ya distinguían los dos casos
+  (`404 → null`, cualquier otro error → `throw`), y el gate de CI también con su try/catch
+  propio; lo que rompía la distinción era un `.catch(() => null)` en `dai pr`. Hay un estado
+  nuevo, **`sin-respuesta`** (`⚠️ no verificado`), y la PR dice *"no verificado (el tracker no
+  respondió)"*, que es lo único cierto ([#43](https://github.com/dforce2055/dai/issues/43)).
+- **`dai: fetch failed` era todo lo que se llegaba a leer.** Es el mensaje pelado de undici
+  cuando no hay red, el host no resuelve o el certificado no valida: no dice qué se estaba
+  consultando, ni contra qué, ni qué mirar — indistinguible de un bug de dai, el mismo modo de
+  falla que el push por SSH de la 0.13.1. Ahora el error nombra la US, el backend y el host, y
+  distingue red / credencial / error del tracker, con el próximo paso en cada caso.
+- **`dai check` ya no se detenía en la primera US** que no pudiera consultar: lo reporta, sigue
+  con las demás y sale ≠ 0. **`dai stamp`** explicita que no estampa un estado que no pudo
+  verificar — escribir en el tracker de todo el equipo no se deshace.
+
+### Cambiado
+- **El molde de PR adelgaza: la doctrina pasa a comentario HTML.** El encabezado tenía cuatro
+  bloques y un solo dato — la doctrina de los dos activos, una línea que repetía la de arriba
+  (*"este PR está atado a la US vía implements.yaml"*) y la instrucción de borrar la sección si
+  no hay US, que `dai pr` resuelve solo desde la 0.13.2. Nada de eso decía algo sobre *esa* PR,
+  y repetirlo a la vista en cada una entrena a saltear el principio del cuerpo, que es
+  justamente donde va la descripción. Sigue estando para quien edite el molde, invisible al
+  renderizar; y la doctrina vive donde se lee una vez y no quinientas: `docs/glosario.md`,
+  `docs/guias/dev.md`, `governance/ci-rules.md`. Los repos ya inicializados lo reciben con
+  `dai sync`.
+
+### Interno
+- **367 tests** (+9): los dos caminos de la consulta (la US que no está y la que no se pudo
+  consultar), el mensaje de error por tipo de falla, y que el relleno del estado no toque la
+  prosa que lo rodea.
+
 ## [0.13.2] — 2026-09-02
 
 **Una PR se publicaba con la descripción vacía y la lista de cambios diciendo "Cambio 1,
@@ -808,6 +918,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.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
 [0.13.0]: https://github.com/dforce2055/dai/releases/tag/v0.13.0

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.2
+0.14.0

package/cli/dai.mjs

@@ -22,12 +22,14 @@ import { acHash } from "./lib/ac-hash.mjs";
 import { discoverImplements, isPlaceholderId } from "./lib/implements.mjs";
 import { isValidKey, slugify, branchName, extractTitle, renderImplementsYaml } from "./lib/link-us.mjs";
 import { loadDaiEnv } from "./lib/env.mjs";
-import { getAdapter, coverageStatus, statusLabel } from "./lib/pm-adapter.mjs";
+import { getAdapter, coverageStatus, statusLabel, fetchLiveUS } from "./lib/pm-adapter.mjs";
 import { branchUrl, commitUrl, parseRemote, detectForge } from "./lib/forge-url.mjs";
 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() {
@@ -332,13 +365,21 @@ async function cmdCheck() {
   for (const f of found) for (const im of f.implements || []) {
     if (isPlaceholderId(im.id)) continue;   // plantilla sin completar, no es una US real
     n++;
-    const live = await adapter.fetchUS(im.id);
-    const status = coverageStatus(im.ac_hash, live?.ac_hash);
-    if (status === "al-dia") process.stdout.write(`✅ ${im.id} al día (${im.version})\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`);
+      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);
       worst = Math.max(worst, 1);
+    } else if (status === "sin-respuesta") {
+      // No es "no hay US": es "no pude preguntar". Antes moría acá con `fetch failed` y sin
+      // chequear las demás; ahora lo dice, sigue, y sale ≠ 0 porque no pudo verificar nada.
+      process.stdout.write(`⚠️  ${reason}\n`);
+      worst = Math.max(worst, 2);
     } else {
       process.stdout.write(`❓ ${im.id}: no encontré la US (backend ${adapter.kind}). ¿Falta el .md o el token?\n`);
       worst = Math.max(worst, 2);
@@ -395,7 +436,11 @@ async function cmdStamp(ids = [], opts = {}) {
   }
 
   for (const r of targets) {
-    const live = await adapter.fetchUS(r.id);
+    // Estampar es ESCRIBIR en el tracker de todo el equipo, y no se deshace: si no se pudo
+    // verificar el estado, no se estampa. (Hoy ya frenaba, por la excepción sin atrapar; acá
+    // queda explícito, con el motivo, y cubierto por un test.)
+    const { us: live, unreachable, reason } = await fetchLiveUS(adapter, r.id);
+    if (unreachable) fail(`${reason}\n  No estampo un estado que no pude verificar.`, 2);
     const status = coverageStatus(r.ac_hash, live?.ac_hash);
     const record = {
       repo: r.repo, change: r.change, version: r.version, ac_hash: r.ac_hash, status,
@@ -824,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);
 
@@ -848,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.`); }
@@ -870,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) {
@@ -897,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).
@@ -960,8 +1036,14 @@ async function cmdPr(opts) {
 
   // 2. Estado de trazabilidad (dai check) contra la US viva.
   const adapter = getAdapter(process.env);
-  const live = id ? await Promise.resolve(adapter.fetchUS(id)).catch(() => null) : null;
-  const status = id ? coverageStatus(ac_hash, live?.ac_hash) : null;
+  // El `.catch(() => null)` que había acá convertía "el tracker no contestó" en "no hay US",
+  // y esa afirmación se PUBLICABA en el cuerpo de la PR, al lado del id de la US que sí está.
+  const { us: live, unreachable, reason } = await fetchLiveUS(adapter, id);
+  if (unreachable) {
+    warn(reason);
+    warn("la PR va a decir que no se pudo verificar contra el tracker — no que no hay US.");
+  }
+  const status = id ? coverageStatus(ac_hash, live?.ac_hash, { unreachable }) : null;
   if (status === "atrasado") {
     warn(`la US ${id} está ATRASADA respecto de tu implementación (${ac_hash} ≠ ${live?.ac_hash}).`);
     warn(`resincroniza antes de abrir la PR:  dai link-us ${id} --resync`);
@@ -997,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:
@@ -1029,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);
@@ -1066,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"] : [])]
@@ -1079,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";
@@ -1854,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(); }
 }
@@ -1866,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;
@@ -1895,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);
 }