@dforce2055/dai 0.1.0

package/cli/lib/pm-jira.mjs

@@ -0,0 +1,123 @@
+// dai · backend Jira del adaptador de PM (REST v3 / Jira Cloud, cara CLI).
+// Auth: Basic (email + api_token) — token scopeado, no contraseña (ADR-0007).
+// Config: DAI_JIRA_BASE_URL, DAI_JIRA_EMAIL, DAI_JIRA_TOKEN.
+//
+// Jira Cloud usa ADF (Atlassian Document Format, JSON) para descripción y comentarios,
+// no markdown ni string. Así que: al LEER convertimos ADF → markdown (para que el
+// hasher encuentre "## Criterios de aceptación"); al ESCRIBIR el stamp, componemos ADF.
+
+import { parseUS } from "./us.mjs";
+
+const trim = (b) => String(b || "").replace(/\/+$/, "");
+
+export function jiraIssueUrl(base, id) {
+  return `${trim(base)}/rest/api/3/issue/${encodeURIComponent(id)}?fields=summary,description`;
+}
+export function jiraCommentUrl(base, id) {
+  return `${trim(base)}/rest/api/3/issue/${encodeURIComponent(id)}/comment`;
+}
+export function jiraAuthHeaders(env) {
+  const cred = Buffer.from(`${env.DAI_JIRA_EMAIL || ""}:${env.DAI_JIRA_TOKEN || ""}`).toString("base64");
+  return { Authorization: `Basic ${cred}`, Accept: "application/json", "Content-Type": "application/json" };
+}
+
+// ── ADF → markdown (para leer la descripción) ────────────────────────────────
+export function adfToMarkdown(node) {
+  if (node == null) return "";
+  if (Array.isArray(node)) return node.map(adfToMarkdown).join("");
+  switch (node.type) {
+    case "doc":         return (node.content || []).map(adfToMarkdown).join("\n");
+    case "heading":     return "#".repeat(node.attrs?.level || 1) + " " + (node.content || []).map(adfToMarkdown).join("") + "\n";
+    case "paragraph":   return (node.content || []).map(adfToMarkdown).join("").trim() + "\n";
+    case "bulletList":
+    case "orderedList": return (node.content || []).map(adfToMarkdown).join("");
+    case "listItem":    return "- " + (node.content || []).map(adfToMarkdown).join("").trim() + "\n";
+    case "text":        return node.text || "";
+    case "hardBreak":   return "\n";
+    default:            return (node.content || []).map(adfToMarkdown).join("");
+  }
+}
+
+// ── markdown → ADF (para CREAR el issue: la descripción va en ADF) ────────────
+// Parser de bloques: headings, párrafos y bullets. Suficiente para el formato de US.
+export function markdownToAdf(md) {
+  const clean = (s) => s.replace(/[*_`]+/g, "").trim();
+  const content = [];
+  let para = [], bullets = null;
+  const flushPara = () => { if (para.length) { const t = clean(para.join(" ")); if (t) content.push({ type: "paragraph", content: [{ type: "text", text: t }] }); para = []; } };
+  const flushBullets = () => { if (bullets) { if (bullets.length) content.push({ type: "bulletList", content: bullets }); bullets = null; } };
+  for (const raw of String(md || "").split(/\r?\n/)) {
+    const line = raw.replace(/\s+$/, "");
+    const h = line.match(/^(#{1,6})\s+(.*)$/);
+    const b = line.match(/^\s*[-*+]\s+(?:\[[ xX]\]\s+)?(.*)$/);
+    if (h) { flushPara(); flushBullets(); const t = clean(h[2]); if (t) content.push({ type: "heading", attrs: { level: h[1].length }, content: [{ type: "text", text: t }] }); }
+    else if (b) { flushPara(); if (!bullets) bullets = []; const t = clean(b[1]); if (t) bullets.push({ type: "listItem", content: [{ type: "paragraph", content: [{ type: "text", text: t }] }] }); }
+    else if (line.trim() === "") { flushPara(); flushBullets(); }
+    else { flushBullets(); para.push(line.trim()); }
+  }
+  flushPara(); flushBullets();
+  if (content.length === 0) content.push({ type: "paragraph", content: [{ type: "text", text: " " }] });
+  return { type: "doc", version: 1, content };
+}
+
+// Arma el texto de la US: summary (campo) + descripción (ADF→md o string).
+export function jiraIssueToText(json) {
+  const f = json.fields || {};
+  const desc = typeof f.description === "string" ? f.description
+    : f.description ? adfToMarkdown(f.description) : "";
+  return `# ${f.summary || json.key || ""}\n\n${desc}`;
+}
+
+// ── cobertura → ADF (para escribir el comentario del stamp) ───────────────────
+const STATUS = { "al-dia": "✅ al día", atrasado: "⚠️ atrasado", "sin-us": "❓ sin US" };
+const txt = (s) => ({ type: "text", text: String(s) });
+const link = (s, href) => ({ type: "text", text: String(s), marks: [{ type: "link", attrs: { href } }] });
+
+export function renderCoverageAdf(id, r) {
+  const content = [
+    { type: "heading", attrs: { level: 4 }, content: [txt(`Cobertura de ${id} — generado por dai stamp`)] },
+    { type: "paragraph", content: [txt(`${r.repo} / ${r.change} @ ${r.version} (${r.ac_hash}) — ${STATUS[r.status] || r.status}`)] },
+  ];
+  const items = [];
+  if (r.branchUrl) items.push({ type: "listItem", content: [{ type: "paragraph", content: [txt("branch: "), link(r.branch, r.branchUrl)] }] });
+  if (r.commitUrl) items.push({ type: "listItem", content: [{ type: "paragraph", content: [txt("commit: "), link((r.commit || "").slice(0, 8), r.commitUrl), txt(" (ancla durable)")] }] });
+  if (items.length) content.push({ type: "bulletList", content: items });
+  return { type: "doc", version: 1, content };
+}
+
+export function jiraAdapter(env) {
+  const base = env.DAI_JIRA_BASE_URL;
+  if (!base) throw new Error("falta DAI_JIRA_BASE_URL en el .env (backend jira).");
+  return {
+    kind: "jira",
+    async fetchUS(id) {
+      const res = await fetch(jiraIssueUrl(base, id), { headers: jiraAuthHeaders(env) });
+      if (res.status === 404) return null;
+      if (!res.ok) throw new Error(`jira ${res.status}: ${await res.text()}`);
+      return { id, ...parseUS(jiraIssueToText(await res.json())) };
+    },
+    async stamp(id, record) {
+      const res = await fetch(jiraCommentUrl(base, id), {
+        method: "POST", headers: jiraAuthHeaders(env),
+        body: JSON.stringify({ body: renderCoverageAdf(id, record) }),
+      });
+      if (!res.ok) throw new Error(`jira ${res.status}: ${await res.text()}`);
+      return `${trim(base)}/browse/${id}`;
+    },
+    async createUS({ title, descriptionMarkdown }) {
+      const project = env.DAI_JIRA_PROJECT;
+      const issuetype = env.DAI_JIRA_ISSUETYPE || "Story";
+      if (!project) throw new Error("falta DAI_JIRA_PROJECT en el .env (la clave del proyecto donde crear el issue).");
+      const res = await fetch(`${trim(base)}/rest/api/3/issue`, {
+        method: "POST", headers: jiraAuthHeaders(env),
+        body: JSON.stringify({ fields: {
+          project: { key: project }, issuetype: { name: issuetype },
+          summary: title, description: markdownToAdf(descriptionMarkdown),
+        } }),
+      });
+      if (!res.ok) throw new Error(`jira ${res.status}: ${await res.text()}`);
+      const j = await res.json();
+      return { id: j.key, url: `${trim(base)}/browse/${j.key}` };
+    },
+  };
+}

package/cli/lib/pr.mjs

@@ -0,0 +1,53 @@
+// dai · componer el cuerpo de una Pull/Merge Request desde el template (ADR-0005).
+// Parte pura y testeable: rellena el template con los datos del link + git + check.
+// Los efectos (git push, gh/glab create) viven en dai.mjs.
+
+const EMOJI = { "al-dia": "✅ al día", atrasado: "⚠️ atrasado", "sin-us": "❓ sin US" };
+
+// Reemplaza el cuerpo de una sección (## Heading … hasta el próximo ## o el final)
+// por content. Tolerante: si no encuentra la sección, devuelve el body igual.
+// Sin flag `m`: `$` = fin de string (no fin de línea), así no corta antes de tiempo.
+export function replaceSection(body, heading, content) {
+  const esc = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`(^|\\n)(##[ \\t]*${esc}[ \\t]*\\n)([\\s\\S]*?)(\\n##\\s|$)`, "i");
+  if (!re.test(body)) return body;
+  return body.replace(re, (m, pre, h, _b, tail) => `${pre}${h}\n${content}\n${tail}`);
+}
+
+// Rellena el template del PR con los datos precargados. Tolerante: reemplaza los
+// placeholders que encuentra y deja el resto para que el humano lo edite.
+export function composePrBody(template, d) {
+  let b = template;
+  b = b.replace(/`ABC-###`/g, `\`${d.id}\``);
+  b = b.replace(/@ `vX`/g, `@ \`${d.version}\``);
+  b = b.replace(/`<hash>`/g, `\`${d.ac_hash}\``);
+  b = b.replace(/verificado con `dai check` ✅/g, `verificado con \`dai check\`: ${EMOJI[d.status] || d.status}`);
+
+  // Descripción: default desde la US (el humano lo pule).
+  if (d.usTitle) b = replaceSection(b, "Descripción", `Implementa la US **${d.usTitle}** (\`${d.id}\`). Ver los criterios de aceptación en el tracker.`);
+  // Cambios realizados: de los commits de la branch (como gh pr create --fill).
+  if (d.commits && d.commits.length) {
+    b = replaceSection(b, "Cambios realizados", d.commits.map((c) => `- [x] ${c}`).join("\n"));
+  }
+  // Bloque de enlaces (lo agrega dai; el humano completa el resto del template).
+  const links = ["", "<!-- Enlaces precargados por `dai pr` -->"];
+  if (d.usUrl) links.push(`- US: ${d.usUrl}`);
+  if (d.branchUrl) links.push(`- branch \`${d.branch}\`: ${d.branchUrl}`);
+  if (d.commitUrl) links.push(`- commit \`${(d.commit || "").slice(0, 8)}\`: ${d.commitUrl}`);
+  return b.replace(/(##\s*Enlaces relacionados\s*\n)(<!--[\s\S]*?-->)?/i,
+    (m, h) => `${h}${links.join("\n")}\n`) === b
+    ? b + "\n" + links.join("\n") + "\n"   // si no había sección Enlaces, apéndela
+    : b.replace(/(##\s*Enlaces relacionados\s*\n)(<!--[\s\S]*?-->)?/i, (m, h) => `${h}${links.join("\n")}\n`);
+}
+
+// Título del PR: el pasado a mano, o "<ID>: <título de la US>", o solo el ID.
+export function prTitle(opts, id, usTitle) {
+  if (opts.title) return opts.title;
+  if (usTitle) return `${id}: ${usTitle}`;
+  return id;
+}
+
+// Herramienta de CLI del forge según el host del remoto.
+export function forgeTool(forge) {
+  return forge === "gitlab" ? "glab" : "gh";
+}

package/cli/lib/us.mjs

@@ -0,0 +1,36 @@
+// dai · primitivos de US y cobertura, compartidos por todos los backends de PM.
+// Vive aparte de pm-adapter.mjs para que jira/clickup lo importen sin ciclos.
+
+import { acHash } from "./ac-hash.mjs";
+import { extractTitle } from "./link-us.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) };
+}
+
+// Compara el hash estampado (implements.yaml) con el hash vivo de la US.
+export function coverageStatus(stampedHash, liveHash) {
+  if (liveHash == null) return "sin-us";
+  return stampedHash === liveHash ? "al-dia" : "atrasado";
+}
+
+const STATUS_LABEL = { "al-dia": "✅ al día", atrasado: "⚠️ atrasado", "sin-us": "❓ sin US" };
+export const statusLabel = (s) => STATUS_LABEL[s] || s;
+
+// Render de la cobertura como markdown (lo que un backend "estampa").
+export function renderCoverage(id, r) {
+  const lines = [
+    `# Cobertura de ${id}  ·  generado por dai stamp`,
+    "",
+    "| repo | change | versión | ac_hash | estado |",
+    "|------|--------|---------|---------|--------|",
+    `| ${r.repo} | ${r.change} | ${r.version} | ${r.ac_hash} | ${statusLabel(r.status)} |`,
+    "",
+  ];
+  if (r.branchUrl) lines.push(`- branch: ${r.branch} → ${r.branchUrl}`);
+  if (r.commitUrl) lines.push(`- commit: ${r.commit} → ${r.commitUrl}  (ancla durable)`);
+  return lines.join("\n") + "\n";
+}

package/docs/EJEMPLO-END-TO-END.md

@@ -0,0 +1,330 @@
+# Ejemplo end-to-end — El "golden path"
+
+> **Para qué sirve.** Es la pieza que la gente copia. Una User Story real viajando
+> de *idea vaga* a *desplegada*, mostrando **el artefacto concreto que produce cada
+> uno de los 10 pasos** de [`SCRUM-CON-IA.md`](SCRUM-CON-IA.md). Si tienes que
+> mostrar la metodología en una sola lectura, es esta.
+>
+> Dominio del ejemplo: **un carrito de compras** (checkout). Los nombres
+> (`ABC-482`, `frontend`) son ilustrativos.
+
+## El mapa: qué artefacto sale de cada paso
+
+| Paso | Skill / evento | Artefacto que produce |
+|---|---|---|
+| 1 Refinamiento | `grill-intent` → `grill-user-story` | `intent.md` + la **US** (`ABC-482`) |
+| 2 Planning | `opsx:propose` | `proposal.md` + `design.md` + `tasks.md` + `specs/` |
+| 3 Rama | `link-us` | branch + `implements.yaml` |
+| 4 TDD | `tdd` | test (RED) → código (GREEN) |
+| 5 Smoke | skill de smoke | escenario end-to-end verde |
+| 6 Code review | review propio del dev → `dai pr` → partner (con `/dai-review`) | PR (código + spec) + aprobación |
+| 7 Merge | `dai stamp` | cobertura estampada en el tracker |
+| 8 Daily | — (humano) | sincronización verbal |
+| 9 Review/Demo | criterios Gherkin | US aceptada por el PO |
+| 10 Retro | — (humano) | 1–2 mejoras |
+
+---
+
+## Paso 1 — Refinamiento: de la idea vaga a la US testeable
+
+### 1a · Cómo empieza (el ticket vago)
+
+El PO crea un ticket en el gestor. Nace con **identidad** (`ABC-482`) y poco más:
+
+```
+ABC-482 · "Arreglar lo del carrito que a veces deja comprar de más"
+```
+
+Impresentable para implementar. Acá entra la IA.
+
+### 1b · Gate 0 — `grill-intent` desafía el problema
+
+La skill no acepta el ticket: interroga el *problema* detrás (contra el
+[`MANIFIESTO.md`](MANIFIESTO.md)).
+
+```
+IA:  ¿Qué duele HOY, concretamente? "Comprar de más" es un síntoma.
+PO:  Un cliente finalizó la compra de un producto que ya no tenía stock, y quedó
+     una orden que no podemos cumplir. También pasa que finalizan con el carrito
+     vacío y se genera una orden fantasma.
+IA:  ¿Quién siente el dolor? "El sistema" no es un usuario.
+PO:  El comprador (recibe un error después de comprar) y depósito, que recibe
+     órdenes que no puede despachar.
+IA:  ¿Y si no lo hacemos? (costo de no actuar)
+PO:  Órdenes que se cancelan a mano, clientes enojados. Pasó bastante el último mes.
+IA:  La solución implícita es "validar el carrito al finalizar". ¿Es el salto correcto,
+     o el problema real es que el stock que muestra el carrito no es confiable?
+PO:  No, validar al finalizar es lo correcto: el stock ya existe, falta chequearlo
+     en el momento de la compra.
+
+Veredicto: a-spec  ✅  (problema real, usuario concreto, costo claro, sin solution-lock)
+```
+
+→ produce `openspec/intents/20260703-checkout-invalido/intent.md` con ese veredicto.
+
+### 1c · `grill-user-story` produce la US
+
+Con el problema validado, la skill interroga hasta que la US es **testeable por
+construcción** ([`formato-us.md`](../templates/formato-us.md)) y la publica en el gestor:
+
+```markdown
+# 🔗 Metadata de trazabilidad
+| Campo        | Valor                        |
+|--------------|------------------------------|
+| ID           | ABC-482                      |
+| spec_version | v1                           |
+| Autor        | J. Pérez (PO)                |
+| Estado       | pulida                       |
+| Repos esperados | frontend                  |
+
+# Finalizar la compra del carrito
+
+## Historia
+Como **comprador**
+quiero **finalizar la compra de mi carrito**
+para **recibir los productos que elijo sin sorpresas**.
+
+## Casos de uso
+- **Happy path** — el comprador finaliza un carrito con productos con stock → se crea la orden.
+- **Alternativo** — intenta finalizar con el carrito vacío → el sistema lo frena.
+- **Excepción** — un producto del carrito no tiene stock → se rechaza indicando cuál.
+
+## 🔗 Criterios de aceptación
+- [ ] **AC-1** —
+  - **Dado** un carrito con productos que tienen stock
+  - **Cuando** el comprador finaliza la compra
+  - **Entonces** se crea la orden y el carrito queda vacío
+- [ ] **AC-2** —
+  - **Dado** un carrito vacío
+  - **Cuando** se intenta finalizar la compra
+  - **Entonces** el sistema lo rechaza y NO crea ninguna orden
+- [ ] **AC-3** —
+  - **Dado** un carrito con un producto sin stock
+  - **Cuando** se intenta finalizar la compra
+  - **Entonces** se rechaza indicando qué producto no tiene stock
+
+## Fuera de scope
+- El pago (pasarela, tarjetas) es otra US.
+
+## Reglas de negocio
+- Una orden creada descuenta el stock de cada producto.
+```
+
+> Nota que la US **no dice** tablas, endpoints ni framework — solo el QUÉ. Y cada
+> AC es un test en potencia ([Art. 3](./MANIFIESTO.md#art-3) del manifiesto).
+
+---
+
+## Paso 2 — Planning: `opsx:propose` deriva el CÓMO
+
+El dev corre `opsx:explore` → `opsx:propose` sobre la US. OpenSpec genera el design
+y las tareas. El dev valida y ajusta:
+
+```markdown
+# design.md (extracto)
+## Enfoque
+Guard de validación en el caso de uso `FinalizarCompra`. El carrito se valida ANTES
+de crear la orden: no vacío, y todos sus productos con stock.
+
+## Reglas de la transición
+  carrito con stock   ──finalizar──► orden creada, carrito vacío   (permitido)
+  carrito vacío       ──finalizar──► ✗ CarritoVacioError
+  producto sin stock  ──finalizar──► ✗ SinStockError(producto)
+```
+
+```markdown
+# tasks.md (extracto)
+- [ ] T1. Test: finalizar carrito con stock → orden creada, carrito vacío (AC-1)
+- [ ] T2. Test: finalizar carrito vacío → CarritoVacioError, sin orden (AC-2)
+- [ ] T3. Test: producto sin stock → SinStockError con el producto (AC-3)
+- [ ] T4. Guard de validación en FinalizarCompra
+- [ ] T5. Smoke end-to-end del flujo
+```
+
+> Las tareas **nacen del cómo**, definidas por quien va a implementar — no bajadas
+> desde arriba (Art. 1).
+
+---
+
+## Paso 3 — Rama: `link-us` ata el código al QUÉ
+
+```bash
+$ dai link-us ABC-482 --us us.md --change finalizar-compra
+✓ branch:  feature/ABC-482-finalizar-la-compra-del-carrito
+✓ archivo: openspec/changes/finalizar-compra/implements.yaml  (ac_hash 7f3a9c2e)
+```
+
+```yaml
+# implements.yaml — el ÚNICO link autorado a mano (schema ADR-0004)
+change: finalizar-compra
+repo:   frontend
+
+implements:
+  - id: ABC-482
+    version: v1
+    ac_hash: 7f3a9c2e          # lo calculó `dai ac-hash` sobre los criterios de la US v1
+
+introduces:
+  - guard-carrito-vacio
+
+autor: D. Force (dev)
+```
+
+> El key `ABC-482` **no se tipeó**: salió del argumento. La rama y el link son
+> correctos por construcción (Art. 8, Art. 9).
+
+---
+
+## Paso 4 — TDD: un test a la vez (RED → GREEN)
+
+Vertical slice del AC-2 (el guard del carrito vacío). **Primero el test (RED):**
+
+```typescript
+test("un carrito vacío no se puede finalizar", async () => {
+  const carrito = await nuevoCarrito({ items: [] });
+
+  const accion = finalizarCompra(carrito.id);
+
+  await expect(accion).rejects.toThrow(CarritoVacioError);
+  expect(await ordenesDe(carrito.id)).toHaveLength(0); // NO se creó ninguna orden
+});
+// ▶ FALLA: finalizarCompra todavía no valida el carrito.
+```
+
+**Después el código mínimo (GREEN):**
+
+```typescript
+export async function finalizarCompra(id: CarritoId) {
+  const carrito = await repo.obtener(id);
+  if (carrito.items.length === 0) throw new CarritoVacioError(id);
+  const sinStock = carrito.items.filter((i) => !hayStock(i));
+  if (sinStock.length > 0) throw new SinStockError(sinStock);
+  const orden = await crearOrden(carrito);
+  return repo.vaciar(carrito, orden);
+}
+// ▶ VERDE. Repetir el ciclo para AC-1 y AC-3.
+```
+
+> El test verifica por la **interfaz pública** (`finalizarCompra`, `ordenesDe`), no
+> espía lo interno. Sobrevive a un refactor (Art. 7 + skill `tdd`).
+
+---
+
+## Paso 5 — Smoke: el flujo entero, verde
+
+```
+$ smoke checkout
+✓ carrito con stock → orden creada, carrito vacío
+✓ carrito vacío → rechazado, sin orden
+✓ producto sin stock → rechazado indicando el producto
+SMOKE OK (3/3)
+```
+
+---
+
+## Paso 6 — Code review: el dev primero, después un partner
+
+**Primero el dev revisa la implementación de la IA** — minucioso y con criterio
+(correctitud, casos borde, seguridad, calidad). El dev es responsable del código, no la IA
+(anti vibe-coding). Ajusta y **commitea** lo que haga falta.
+
+Con el smoke verde y **todo commiteado** (lo que quede suelto no entra en la PR), crea la
+PR con `dai pr` — precargada con la US, el estado del check y los links (los **dos activos**:
+código + spec trazable) — y la asigna a un partner:
+
+```
+$ dai check
+✅ ABC-482 al día (v1)
+$ dai pr --assignee mgomez
+✓ PR #123 creada → …/pull/123   (base: main · US: ABC-482 @ v1 · dai check ✅)
+```
+
+El **partner** revisa la PR. Se apoya en la skill `/dai-review` para un primer pase con
+comentario estándar, y **firma** aprobación o rechazo:
+
+```
+🤖 /dai-review (primer pase, ayuda al partner)
+  · AC-2 cubierto y verificado (no se crea orden con carrito vacío). ✓
+  · Sugerencia: CarritoVacioError y SinStockError deberían extender un DomainError
+    común, como el resto del módulo.
+  · Sin problemas de correctitud.
+
+👤 M. Gómez (partner): de acuerdo con el DomainError. Aprobado tras el ajuste.
+```
+
+> El dev revisa su propio código; un partner distinto revisa la PR y **firma** (Art. 5).
+> La skill `/dai-review` le saca el ruido al partner, pero la aprobación la firma la persona.
+
+---
+
+## Paso 7 — Merge: la trazabilidad se estampa sola
+
+Al mergear, se corre `dai stamp` (el dev, o el CI si está automatizado — ADR-0003).
+Lee el `implements.yaml` y **estampa la cobertura inversa** en el ticket `ABC-482`,
+con links a la implementación:
+
+```
+ABC-482 · implementado por  (lo estampó dai stamp)
+┌──────────┬───────────────────┬─────────┬──────────┬───────────┐
+│ repo     │ change            │ versión │ ac_hash  │ estado    │
+├──────────┼───────────────────┼─────────┼──────────┼───────────┤
+│ frontend │ finalizar-compra  │ v1      │ 7f3a9c2e │ ✅ al día │
+└──────────┴───────────────────┴─────────┴──────────┴───────────┘
+  branch → …/tree/feature/ABC-482-finalizar-la-compra-del-carrito
+  commit → …/commit/abc123   (ancla durable)
+```
+
+> El estado se **deriva**, no se reporta (Art. 10). El link (branch + commit) hace
+> que el ticket sea un router hacia la implementación real (§2.5).
+
+---
+
+## Paso 8 — Daily *(humano, a propósito)*
+
+> *"Ayer cerré ABC-482, la validación del checkout con el guard de carrito. Hoy
+> agarro ABC-490. Sin trabas."* — La IA no genera esto; el equipo se sincroniza (Art. 6).
+
+## Paso 9 — Review / Demo
+
+El PO valida contra los **mismos criterios que ya eran tests**. Finaliza un carrito,
+prueba con uno vacío, prueba con un producto sin stock, ve los rechazos. AC-1, AC-2,
+AC-3 verdes → **US aceptada**. Cero sorpresas: si el QUÉ hubiera cambiado, el
+`@version` lo habría gritado antes.
+
+## Paso 10 — Retro *(humano)*
+
+> *"El Gate 0 nos ahorró rediseñar el stock, que no hacía falta. Mejora para el
+> próximo sprint: sumar el smoke al pipeline y no correrlo a mano."* La matriz de
+> trazabilidad aportó el dato; la decisión la tomó el equipo (Art. 6).
+
+---
+
+## Epílogo — Y cuando el QUÉ cambia (el `@version` gritando solo)
+
+Dos sprints después, el PO agrega un criterio a `ABC-482` (ahora exige **avisar al
+comprador qué productos quedaron sin stock, sin cancelar el resto del carrito**).
+Sube la US a **v2** → cambia el `ac_hash`.
+
+```
+ABC-482 · implementado por
+┌──────────┬───────────────────┬─────────┬──────────┬────────────────────────────┐
+│ repo     │ change            │ versión │ ac_hash  │ estado                     │
+├──────────┼───────────────────┼─────────┼──────────┼────────────────────────────┤
+│ frontend │ finalizar-compra  │ v1      │ 7f3a9c2e │ ⚠️  ATRASADO (la US es v2)  │
+└──────────┴───────────────────┴─────────┴──────────┴────────────────────────────┘
+```
+
+Nadie le avisó al dev: `dai check` lo marcó solo al re-derivar el hash de la US viva
+y compararlo con el estampado (Art. 11). El dev abre una nueva iteración —mismo
+`ABC-482`, ahora contra v2— y el ciclo vuelve a empezar desde el paso 3.
+
+---
+
+## Qué demuestra este recorrido
+
+- **Los 10 pasos son tu Scrum de siempre** — solo que en cada uno hay una skill.
+- **El link nunca se escribió dos veces**: `implements.yaml` una vez, la cobertura
+  se derivó.
+- **Nada llegó a producción sin ser testeable y trazable** (Arts. 3, 9, 10).
+- **Los rituales humanos siguieron siendo humanos** (Art. 6).
+- Y cuando el negocio cambió, **el desajuste se hizo visible solo** (Art. 11).

package/docs/MANIFIESTO.md

@@ -0,0 +1,114 @@
+# Manifiesto — Desarrollo Asistido por IA
+
+> **Qué es esto.** La *constitución* de la metodología: los principios inmutables
+> contra los que se mide toda decisión. Cuando `grill-intent` desafía un problema,
+> lo hace contra estos artículos. Cuando dudas si algo "va con el método", la
+> respuesta está acá. Es corto a propósito — un manifiesto que no se puede citar de
+> memoria no gobierna nada.
+>
+> **Cómo se usa.** Es el input de constitución que las skills asumen (junto con
+> `openspec/project.md` y `CLAUDE.md`). No se negocia por conveniencia de un
+> sprint. Se cambia por decisión explícita del equipo, registrada como ADR.
+
+---
+
+## Los cuatro valores
+
+1. **El QUÉ y el CÓMO son cosas distintas, con dueños distintos.**
+2. **La IA asiste; la persona decide.**
+3. **Nada existe si no se puede testear ni trazar.**
+4. **La ceremonia se agrega cuando duele, no antes.**
+
+Todo lo que sigue son artículos que hacen operativos esos cuatro valores.
+
+---
+
+## I. Sobre el QUÉ y el CÓMO
+
+<a id="art-1"></a>**Art. 1 — Separación de responsabilidades.**
+El *funcional* define **qué** hay que hacer y **por qué**. El *técnico* define
+**cómo**. Nadie invade el terreno del otro: la US no dice endpoints ni tablas; el
+design no re-discute el valor de negocio.
+
+<a id="art-2"></a>**Art. 2 — El QUÉ es tool-agnóstico.**
+El requerimiento vive con una identidad y una forma mínima que **no dependen de la
+herramienta de abajo** (OpenSpec, Swagger, YAML, Markdown). Cambiar la herramienta
+técnica no rompe el link.
+
+<a id="art-3"></a>**Art. 3 — Testeable o no existe.**
+Un criterio de aceptación que no se puede volver un test, no es un criterio. *"El
+usuario tiene una buena experiencia"* se rechaza. *"Un carrito vacío no se puede
+finalizar"* se acepta. Si no es verificable, no entra.
+
+## II. Sobre la IA y el humano (HITL)
+
+<a id="art-4"></a>**Art. 4 — La IA saca a preguntas, no inventa.**
+El QUÉ se produce **por interrogación** (`grill-*`), no por generación. La IA no
+adivina requerimientos: presiona hasta que la persona los explicita. Un QUÉ que la
+IA "completó sola" es una alucinación con formato lindo.
+
+<a id="art-5"></a>**Art. 5 — La persona firma.**
+Toda decisión irreversible o de negocio —aceptar una US, aprobar un PR, descartar
+un problema— la toma y la firma un humano. La IA propone; nunca autoriza.
+
+<a id="art-6"></a>**Art. 6 — Los rituales de coordinación son humanos.**
+El *daily* y la *retro* se hacen a mano, a propósito. Son donde el equipo se
+apropia del proceso y lo entiende. La IA puede darles datos; no los reemplaza.
+
+<a id="art-7"></a>**Art. 7 — No vibe coding.**
+No se improvisa código sobre una idea vaga. Toda implementación arranca de una US
+bien definida, pasa por un design, y se construye con tests. La disciplina no es
+opcional: es lo que separa este método de "pedirle cosas a un chat".
+
+## III. Sobre la trazabilidad
+
+<a id="art-8"></a>**Art. 8 — Identidad estable.**
+Todo QUÉ nace con un ID único, independiente del path y del formato. Es lo único
+que lo hace linkeable. No se inventa un esquema nuevo: es el ticket del gestor (o
+el change en el nivel más chico).
+
+<a id="art-9"></a>**Art. 9 — El link se autora una sola vez.**
+El CÓMO declara `implements: <id>@<version>`. Es el **único** link escrito a mano.
+La dirección inversa (quién implementó qué) **siempre se deriva, nunca se escribe**.
+Escribirlo en los dos lados es firmar la desincronización.
+
+<a id="art-10"></a>**Art. 10 — El estado se deriva, no se reporta.**
+La matriz de trazabilidad —quién implementó qué, contra qué versión, quién quedó
+atrasado— no la mantiene ninguna persona. La calcula la máquina a partir de los
+links. Si alguien la actualiza a mano, algo está mal diseñado.
+
+<a id="art-11"></a>**Art. 11 — El versionado avisa solo.**
+El `@version` (número legible + hash de criterios) hace que un cambio del QUÉ marque
+solo a los CÓMO atrasados. Nadie avisa a nadie: el link versionado lo grita. El
+número comunica; el hash detecta.
+
+<a id="art-12"></a>**Art. 12 — Capacidad entera, detalle on-demand.**
+El link es a nivel de capacidad/US entera, no criterio-por-criterio. Si el QUÉ sabe
+*quién* lo implementó, el detalle fino se resuelve leyendo el repo por ID. El índice
+central es un **router, no un almacén**.
+
+## IV. Sobre la escala
+
+<a id="art-13"></a>**Art. 13 — Un protocolo, varios niveles de ceremonia.**
+No hay una metodología para equipos chicos y otra para grandes. Hay **un** protocolo
+invariante (Arts. 1–12) y un dial de ceremonia que sube o baja según la escala. El
+que aprende el nivel chico ya sabe el grande.
+
+<a id="art-14"></a>**Art. 14 — No adelantar complejidad.**
+Cada capa de plomería (tracker externo, CI que estampa, matriz de ambientes) se
+agrega **cuando duele, no antes**. Empezar con la maquinaria completa "por las
+dudas" es tan malo como no tener método.
+
+<a id="art-15"></a>**Art. 15 — Los roles se colapsan, el link no.**
+Cuando una misma persona es autor del QUÉ y del CÓMO, los gates se aligeran (un
+auto-check honesto en vez de la firma de otro), pero el link `implements` **sigue
+existiendo**. La ceremonia se achica; la trazabilidad no se negocia.
+
+---
+
+## Cómo se enmienda
+
+Estos artículos se cambian solo por **decisión explícita del equipo**, registrada
+como un ADR con fecha y motivo. Ningún sprint, deadline ni "esta vez es distinto"
+alcanza para saltárselos en silencio. Si un artículo estorba seguido, esa es la
+señal de que hay que debatirlo y enmendarlo — no de ignorarlo.