@dforce2055/dai 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -3,6 +3,172 @@
 Formato basado en [Keep a Changelog](https://keepachangelog.com/). Versionado semver
 (ver `VERSION`).
 
+## [0.12.0] — 2026-08-13
+
+**La PR deja de robarle la US a otro. `dai pr` resolvía el link recorriendo todo el repo y
+quedándose con el último `implements.yaml`; ahora lo resuelve la rama, que es la que sabe la
+respuesta — y cuando no puede saberlo, pregunta en vez de elegir en silencio. Más el tutorial
+de setup del dev, la contraparte del que ya tenía el funcional.**
+
+### Arreglado
+- **`dai pr` armaba la PR con la US equivocada** (issues [#31](https://github.com/dforce2055/dai/issues/31),
+  [#32](https://github.com/dforce2055/dai/issues/32), [#33](https://github.com/dforce2055/dai/issues/33)).
+  Recorría **todos** los `implements.yaml` del repo —archivados incluidos, porque era el
+  único comando que no pasaba `{ includeArchived: false }`— y el `break` cortaba solo el
+  bucle interno, así que ganaba el **último** en orden de lectura. La rama, que la nombra el
+  propio `dai link-us`, no entraba en la decisión.
+  El síntoma es silencioso y por eso duele: la PR sale con el título, el link y el
+  `dai check ✅` de **otra** US. En repos reales convivieron dos PRs con el mismo título y
+  contenidos que no tenían nada que ver, y una PR de archivado apareció rotulada con la
+  historia de un compañero. Es exactamente el modo de falla que la constitución quiere
+  evitar — el link QUÉ↔CÓMO queda mal y nadie se entera, porque **nadie lee el
+  `implements.yaml` en la lista de PRs: leen el título**.
+  Ahora decide `prScope` (`cli/lib/branch-scope.mjs`), hermana de `stampScope`: la rama
+  nombra una US viva → esa; una sola US viva → esa; varias candidatas → **pregunta** con TTY
+  y **falla** sin TTY, listándolas.
+- **Una rama exenta ya no hereda la US del repo.** Un `chore/`/`docs/`/`release/` que no
+  nombra ninguna US genera la PR **sin** US —título del último commit y la sección
+  *Implementa* diciendo que no hay historia— en lugar de colgarle la de otro o dejar el
+  placeholder `ABC-###` del template.
+- **`dai done` anunciaba `US cerrada:` con todas las US del repo**, archivadas incluidas.
+  Cerrar una rama informaba el cierre de medio sprint. Mismo defecto de clase, en un mensaje.
+- **Ctrl+D en las preguntas de `dai pr`** cancela en vez de cortar con `Aborted with Ctrl+D`.
+  Todas ellas preceden a una acción hacia afuera (push + PR): ahí abortar es lo seguro.
+
+### Agregado
+- **`dai pr --us <ID>`** — el escape hatch explícito, y la única salida cuando hay ambigüedad
+  y no hay TTY (un pipeline). Acepta también un change ya archivado.
+- **El preview dice de dónde salió la US**: `US: ABC-482 — la branch '…' nombra ABC-482`.
+  Cuando el título está mal, es lo único que lo delata.
+- **[Tutorial de setup para desarrolladores (Windows)](docs/tutoriales/setup-dev.md)** — el
+  otro lado del que ya existía para el funcional: Node, dai, git + SSH + `glab`, las skills
+  en Copilot, OpenSpec, el `.env.dai` contra Jira, y el ciclo completo sobre una US real
+  (`link-us` → `check` → `mr` → `stamp` → `done`). El troubleshooting sale de lo que pasó de
+  verdad en Windows corporativo: el push HTTPS que necesita completar el credential manager,
+  el proxy con su propio certificado, el gate de CI.
+
+### Versionado
+
+**Minor → 0.12.0.** `dai pr` **cambia de comportamiento**: donde antes elegía una US en
+silencio, ahora pregunta (o falla), y una rama exenta genera la PR sin US. En el papel es
+incompatible; en la práctica el comportamiento viejo era el bug de los issues #31/#32/#33.
+Suma la flag `--us`, aditiva. El contrato del modelo (`ac_hash`, schema de `implements.yaml`)
+queda intacto.
+
+### Interno
+- **319 tests** (+12 desde 0.11.0): `prScope` ×10 —la rama manda sobre el orden de
+  directorio, los archivados no compiten, una `chore/` no hereda, la ambigüedad no se
+  resuelve sola— y el cuerpo/título de una PR sin US ×2.
+- `requiresLink()` devuelve además `kind` (`always` / `exempt` / `untyped`): es lo que separa
+  "exenta por tipo" de "la rama no dice nada", y lo que `dai pr` necesitaba para no heredar
+  la US de otro sin romper el gate de CI.
+
+## [0.11.0] — 2026-07-22
+
+**Ronda de fixes reportados usándola, más el eslabón que faltaba: editar el QUÉ. `dai stamp`
+deja de estampar de más, el gate de governance pasa de regla escrita a comando ejecutable,
+`dai edit-us` trae la US del tracker y valida el formato antes de devolverla, y los mensajes
+de error dejan de mandar el diagnóstico para el lado equivocado.**
+
+### Agregado
+- **`dai check --ci`** — el gate de [`governance/ci-rules.md`](governance/ci-rules.md),
+  ejecutable ([ADR-0018](docs/adr/0018-alcance-de-stamp-y-gate-de-ci.md), issue #26). El
+  documento prometía "sin `implements.yaml` el CI bloquea" y no existía el comando que lo
+  hiciera: era una regla escrita que nadie aplicaba. Ahora lee el nombre de la rama y
+  aplica `branch-naming.md` — `feature/` siempre exige US, `chore/`/`docs/`/`ci/`/`release/`
+  y compañía quedan **exentas**, `fix/` exige solo si el nombre trae un ID. Salidas:
+  `0` pasa · `1` falta el link · `2` el QUÉ cambió. Detecta sola la rama en CI
+  (`GITHUB_HEAD_REF` y equivalentes: en una PR, `HEAD` es un merge commit detached).
+  Con `--no-network` valida el link sin pegarle al tracker.
+- **`templates/ci-dai-gate.yml`** — workflow listo para copiar a `.github/workflows/`.
+  Fuera de GitHub Actions el contrato es el mismo: un comando y su código de salida.
+- **`dai edit-us <ID>` y `dai update-us <ID>`** — editar el QUÉ deja de ser copiar y pegar
+  (issue #23, [ADR-0018](docs/adr/0018-alcance-de-stamp-y-gate-de-ci.md)). Dos puertas a un
+  solo camino: `edit-us` **baja la US del tracker**, te la abre en tu `$EDITOR` y la sube
+  (para el PO); `update-us` empuja un `.md` que ya escribiste (para el dev que refinó la US
+  implementándola). Las dos dan el mismo preview y la misma confirmación, porque comparten
+  el mismo tramo de escritura.
+  - **Valida el formato antes de guardar** contra el molde canónico
+    (`templates/formato-us.md`): frenan las tres cosas sin las cuales no hay `ac_hash`
+    —sin título, sin sección de criterios, sección vacía— y **avisan** las demás (un
+    criterio que no es Gherkin completo, uno que se mete en el CÓMO, un título
+    kilométrico). `--strict` sube los avisos a errores.
+  - **Un formato inválido no tira lo escrito**: te devuelve al editor con los errores a la
+    vista, las veces que haga falta.
+  - **Propone subir el `spec_version`** cuando el `ac_hash` se movió, y espera un sí o un
+    no: `s` = cambio material (los repos con la versión vieja se marcan **atrasados**),
+    `n` = cambio editorial (no se marca nadie). dai sabe *que* cambió, no *si importa* —
+    eso lo sabe el PO. `--bump` / `--no-bump` para el modo no interactivo.
+  - **Re-estampa el `ac_hash`** del `implements.yaml`, que si no `dai check` te marcaría
+    atrasado por tu propia edición. `--dry-run` muestra todo el preview sin escribir.
+
+### Arreglado
+- **`dai stamp` estampaba TODAS las US del repo, archivadas incluidas** (issue #22). Cerrar
+  una historia dejaba un comentario de cobertura en los tickets de las otras tres del
+  sprint — y un comentario en un tracker no se deshace. Ahora el alcance sale de la rama
+  ([ADR-0018](docs/adr/0018-alcance-de-stamp-y-gate-de-ci.md)): si la rama nombra la US,
+  esa; si hay una sola viva, esa; si hay varias y no puede saber cuál, **pregunta** en vez
+  de estampar de más (y sin TTY falla pidiendo el ID, en vez de decidir por vos). Los
+  changes archivados salen del default. `dai stamp <ID>` es explícito y `dai stamp --all`
+  recupera el comportamiento anterior.
+- **El error del forge decía `¿token? ¿ref correcta?` para todo** (issue #24). Sin token,
+  token vencido, token sin scope y PR inexistente caían en la misma frase, y eso costó una
+  sesión entera de diagnóstico equivocado. Ahora se nombran por separado: **no hay
+  `GITHUB_TOKEN`/`GITLAB_TOKEN`** (se detecta antes de salir a la red, y no se afirma que
+  esté vencido algo que no existe) · **401** el token existe pero no sirve, con el `curl`
+  para verificarlo · **403** válido pero sin permiso, o rate limit · **404** nombra las
+  **dos** causas, porque en un repo privado GitHub devuelve 404 y no 403 a propósito. El
+  diagnóstico ahora cubre `forge pr`, `forge comment` y `forge review`, que antes se
+  tragaban el error real.
+- **`.dai/reviews/` en el `.gitignore` de los repos ya inicializados** (issue #25). La
+  regla estaba desde 0.10.0, pero solo la aplicaban `dai init`/`dai sync`, y el
+  `review.json` lo escribe la skill: un repo scaffoldeado con una dai vieja se comía
+  borradores a medio editar en un commit. Ahora `dai forge review` lo agrega al consumir
+  un borrador que está bajo `.dai/reviews/`. Además la reconciliación compara **normalizado**
+  (`.dai/reviews`, `/.dai/reviews/` y `.dai/reviews/` son la misma regla), así no duplica
+  la línea a quien ya la había puesto a mano.
+- Un `Ctrl+D` en un prompt de confirmación se trata como **cancelar** en vez de crashear
+  con `Aborted with Ctrl+D`.
+
+### Interno
+- **`cli/test/package-hygiene.test.mjs`** — chequea lo que hasta ahora era un `git grep` a
+  mano antes de pushear: que ningún fuente versionado tenga bytes NUL (uno se coló y git
+  pasó a tratar el archivo como binario, con el diff dejando de ser revisable), que todo
+  sea UTF-8 válido, que no viajen identificadores de repos de terceros —la convención de
+  los ejemplos es ACME— y que `files[]` no publique el sitio.
+
+### Versionado
+
+**Minor → 0.11.0.** `dai stamp` sin argumentos **cambia de comportamiento**: antes estampaba
+todas las US del repo, ahora una. En el papel es incompatible; en la práctica el
+comportamiento viejo era el bug que reporta el issue #22, y quien lo quiera tiene `--all`.
+El contrato del modelo (`ac_hash`, schema de `implements.yaml`) queda intacto, y todo lo
+demás es aditivo.
+
+### Cambiado
+- `governance/ci-rules.md` describe lo que la máquina realmente hace: el comando que
+  ejecuta cada regla, la tabla de ramas exentas, y por qué el gate no bloquea sin
+  credenciales del tracker.
+- **Los adaptadores de PM devuelven `raw`** (el markdown completo de la US) además del
+  parseo. Es lo que `edit-us` abre; antes solo salían título + hash, que alcanza para
+  detectar drift pero no para editar.
+- **`/grill-user-story` distingue crear de refinar.** Si la US es nueva la crea como
+  siempre (MCP o `dai publish`); si **ya tiene key**, ahora la actualiza con
+  `dai edit-us <ID> --us <md> --no-editor` en vez de pisar el ticket por MCP. Así el
+  camino de la skill pasa por los mismos controles que el manual: validación de formato
+  antes de escribir, preview, y la pregunta del `spec_version` — que la skill tiene
+  instrucción explícita de trasladarle al PO, no de responder con `--yes`.
+- **Las skills dicen bien dónde está la config: `.env.dai` *o* `.env`.** Varias mandaban a
+  leer solo uno de los dos, y quien tenía todo en el `.env` del equipo veía a la skill
+  concluir que no había tracker configurado. dai **carga los dos** —`.env.dai` gana si una
+  clave está en ambos, y un repo que nunca creó `.env.dai` sigue funcionando igual
+  (ADR-0017)—; ahora las skills lo dicen así. Sin cambios de comportamiento en el CLI:
+  el loader ya hacía esto.
+- Documentación al día con los comandos nuevos: la [guía del PO](docs/guias/po.md) estrena
+  una sección "Cuando el QUÉ cambia", más `docs/guias/dev.md`, `docs/PROBAR.md`,
+  `docs/EJEMPLO-END-TO-END.md`, `docs/SCRUM-CON-IA.md`, `docs/METODOLOGIA.md`,
+  `docs/glosario.md`, `docs/detalle/01-refinamiento.md` y `docs/detalle/07-merge-trazabilidad.md`.
+
 ## [0.10.0] — 2026-07-18
 
 **La config de dai deja de vivir en el `.env` del equipo y pasa a un `.env.dai` propio (no
@@ -445,6 +611,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.12.0]: https://github.com/dforce2055/dai/releases/tag/v0.12.0
+[0.11.0]: https://github.com/dforce2055/dai/releases/tag/v0.11.0
 [0.10.0]: https://github.com/dforce2055/dai/releases/tag/v0.10.0
 [0.9.0]: https://github.com/dforce2055/dai/releases/tag/v0.9.0
 [0.8.2]: https://github.com/dforce2055/dai/releases/tag/v0.8.2

package/README.md

@@ -112,6 +112,14 @@ dai pr --assignee <compañero>   # crea la PR precargada y se la asigna a un com
 dai stamp                       # al mergear: estampa la cobertura en el tracker
 ```
 
+> ¿Cambió el QUÉ? `dai edit-us <ID>` baja la US del tracker, te la abre en tu editor, valida
+> el formato y te pregunta si el cambio es material (sube `spec_version`) o editorial. Si
+> ya tenés el `.md` escrito —lo refinaste implementando— `dai update-us <ID>` lo empuja y
+> re-estampa tu `ac_hash`, que si no `dai check` te marca atrasado por tu propia edición.
+> Y si quieres que el link deje de depender de la memoria del equipo, `dai check --ci` es
+> el gate ejecutable de [`governance/ci-rules.md`](governance/ci-rules.md): copia
+> [`templates/ci-dai-gate.yml`](templates/ci-dai-gate.yml) a `.github/workflows/`.
+
 > **Para que `dai pr` cree la PR/MR** necesitas el CLI del forge instalado y autenticado, una
 > sola vez por máquina:
 > - **GitHub** → [`gh`](https://cli.github.com) · `gh auth login`
@@ -159,13 +167,15 @@ flowchart TD
 | 4 | **Linkear la US** | `dai link-us <ID>` → branch + `openspec/changes/<id>/implements.yaml` | dev |
 | 5 | **Verificar / listar** | `dai check` (¿al día?) · `dai ls` (qué implementa el repo) | dev |
 | 6 | **Resincronizar** *(si el PO editó la US)* | `dai link-us <ID> --resync` | dev |
+| 6b | **Editar la US** | `dai edit-us <ID>` la baja del tracker, la abrís en tu editor, valida el formato y la devuelve · `dai update-us <ID>` empuja un `.md` que ya escribiste. Las dos preguntan si subir el `spec_version` | PO / dev |
 | 7 | **Diseñar el CÓMO** | en el asistente: `/opsx:explore` → `/opsx:propose` → design + tasks | dev + IA |
 | 8 | **Implementar** | `/opsx:apply` → implementa la US con TDD y genera los commits | dev + IA |
 | 9 | **Code review propio** | revisas tu implementación (correctitud + calidad) antes de la PR | dev |
 | 10 | **Smoke test** | pides al agente un smoke local del flujo | dev + IA |
 | 11 | **Crear la PR** | `dai pr` → pregunta la branch base, arma el texto, lo muestra, confirma, pushea y crea la PR/MR | dev |
 | 12 | **Review de un partner** | skill `/dai-review <PR>` deja un **review inline** (resumen + un comentario por línea, low/medium/high); te muestra el preview y **espera tu OK** antes de postear; un humano aprueba | partner |
-| 13 | **Merge + estampar** | al mergear: `dai stamp` → cobertura inversa en el tracker | dev / CI |
+| 13 | **Merge + estampar** | al mergear: `dai stamp` → cobertura inversa en el tracker (deduce la US de la rama; en CI pasa el ID) | dev / CI |
+| 13b | **Gate de trazabilidad** *(opcional)* | `dai check --ci` en el CI → bloquea una rama de producto sin link; `chore/`/`docs/` quedan exentas ([template](templates/ci-dai-gate.yml)) | CI |
 | 14 | **Cerrar la US** | `dai done` → vuelve a la base, actualiza y borra la branch local (si está mergeada) | dev |
 
 > **Paso 3b (publicar):** el MCP crea el issue interactivamente; `dai publish` necesita el
@@ -191,7 +201,7 @@ flowchart TD
 | `dai link-us <ID> --resync` | re-estampa el `ac_hash` contra la US viva (tras un ⚠️ de check) |
 | `dai check` | compara tu código vs la US viva → ✅ al día / ⚠️ atrasado (exit code = gate de PR) |
 | `dai ls [--json]` | lista las US que implementa el repo + su link al tracker |
-| `dai pr [--assignee u] [--base b] [--draft] [--yes]` · alias **`dai mr`** | crea TU PR/MR precargada: pregunta la branch base (default `main`), muestra el texto y confirma antes de publicar. Detecta el forge (GitHub→PR con `gh` · GitLab→MR con `glab`); `mr` es el mismo comando, más natural en GitLab |
+| `dai pr [--assignee u] [--base b] [--draft] [--yes] [--us ID] [--title t]` · alias **`dai mr`** | crea TU PR/MR precargada: pregunta la branch base (default `main`), muestra el texto y confirma antes de publicar. Detecta el forge (GitHub→PR con `gh` · GitLab→MR con `glab`); `mr` es el mismo comando, más natural en GitLab. **La US la resuelve la branch** (la nombra `dai link-us`): si hay varias vivas y ninguna coincide, **pregunta** en vez de elegir por vos (sin TTY falla pidiendo `--us <ID>`), y una branch `chore/`/`docs/` sale **sin US** en lugar de heredar la de otro |
 | `dai stamp` | estampa la cobertura inversa en el tracker (branch + commit-ancla) |
 | `dai done [--base main] [--force]` | cierra la US: vuelve a la base, `fetch --prune` + `pull`, y borra la branch local **si está mergeada** (chequeo estricto; `--force` la borra igual). Redes: no estar en la base, sin cambios sueltos, sin commits sin pushear |
 | `dai archive [<change>] [--skip-specs]` | **funde los delta specs del change en las specs canónicas** (`openspec/specs/`) y lo archiva. Lo corre el **aprobador** de la PR (gate de aprobación, [ADR-0011](docs/adr/0011-archive-gate-de-aprobacion.md)); detecta el change activo o le pasás el nombre. Envuelve `openspec archive` |

package/VERSION

@@ -1 +1 @@
-0.10.0
+0.12.0