ADR-0005 — Superficie de comandos del CLI y contenido del stamp

• Estado: aceptado
• Fecha: 2026-07-03
• Decide: lead / arquitecto de la metodología

Contexto

Los ADR-0001/0003/0004 definieron el hash, el modelo de detección y el schema del implements.yaml. Falta congelar qué comandos expone dai para la trazabilidad y qué estampa exactamente dai stamp en el tracker (que es el router de Nivel-1, §2.5, y por lo tanto debe llevar links a la implementación).

Decisión

Superficie de comandos de trazabilidad

Comando	Acceso	Qué hace
dai ac-hash <us>	local	calcula el hash de criterios (ADR-0001).
dai ls [--json]	local, offline	escanea **/implements.yaml, lista las US que implementa el repo + su link al tracker. Base de los otros dos.
dai check	lee la US viva	ls + trae la US + compara hashes → al día / ⚠️ atrasado. Exit ≠ 0 si atraso (gate de PR).
dai stamp	escribe al tracker	ls + trae la US + escribe la cobertura (inversa, Art. 10).

check y stamp se construyen sobre ls (un solo lugar descubre y parsea).

Contenido del stamp (el router necesita links)

dai stamp escribe en el ticket, por cada repo/change que lo implementa:

repo:    <nombre>   → <repo web url>
branch:  <branch>   → <branch url>     ← link principal (legible)
commit:  <sha>      → <commit url>     ← ANCLA durable (sobrevive al borrado de branch)
version: <v> (<ac_hash>)  → ✅ al día | ⚠️ atrasado
autor:   <dev>

Los links se derivan de git, sin API del forge ni --pr:

• repo/branch/commit salen de git remote get-url origin + git rev-parse.
• La URL web es específica del forge (GitHub /tree/ /commit/; GitLab /-/tree//-/commit/; Bitbucket /src/ /commits/): dai mapea forge→esquema por el host del remoto.

Branch + commit-ancla: la branch es el link legible, pero se borra al mergear; el commit es permanente. Guardar los dos evita que el router quede en 404.

Consecuencias

• ✅ Trazabilidad completa sin API del forge ni flags manuales: todo se deriva de git.
• ✅ El router (§2.5) siempre tiene un link vivo (el commit) → nunca dead-link.
• ✅ dai ls es offline y read-only → sirve de base barata para todo lo demás.
• ⚠️ Construir la URL web es forge-específico → lógica a testear (SSH/HTTPS, 3 forges).
• ⚠️ dai stamp (write) y dai check (read US viva) dependen del adaptador de PM (getAdapter, ya implementado). Para el backend md, stamp --format md emite el bloque para pegar a mano (mismo fallback que grill-user-story).

Alternativas consideradas

• Link a la PR/MR — descartado: no es derivable localmente sin API del forge, y en modo distribuido genera fricción (--pr). La branch+commit se derivan de git solo.
• Solo la branch — descartado: la branch se borra al mergear → 404. El commit es la ancla durable.
• Solo el commit — viable pero menos legible; la branch le da contexto humano. Guardamos los dos.