@dforce2055/dai 0.8.2 → 0.10.0

package/cli/lib/pm-jira.mjs

@@ -15,7 +15,7 @@ const trim = (b) => String(b || "").replace(/\/+$/, "");
 // error de config más común: `dai init` deja DAI_JIRA_PROJECT vacío y quien lo completa
 // suele pegar la épica que tiene a mano. Jira responde un 400 que no lo explica.
 export function assertProjectKey(key) {
-  if (!key) throw new Error("falta DAI_JIRA_PROJECT en el .env (la clave del proyecto donde crear el issue).");
+  if (!key) throw new Error("falta DAI_JIRA_PROJECT en el .env.dai (la clave del proyecto donde crear el issue).");
   const k = String(key).trim();
   const m = k.match(/^([A-Za-z][A-Za-z0-9_]*)-\d+$/);
   if (m) {
@@ -136,7 +136,7 @@ export function createHint(status, body = "") {
 
 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).");
+  if (!base) throw new Error("falta DAI_JIRA_BASE_URL en el .env.dai (backend jira).");
   return {
     kind: "jira",
     async fetchUS(id) {

package/cli/lib/review-findings.mjs

@@ -0,0 +1,195 @@
+// dai · hallazgos de un review inline: parseo, validación contra el diff, filtros y render.
+// Puro y sin red (ADR-0002: lo mecánico en el CLI, el criterio en la skill).
+//
+// El contrato con la skill es un `review.json`. La skill lo escribe, el humano lo lee y
+// lo edita, y el CLI lo valida y lo postea. Ese archivo ES la puerta humana: es
+// diff-eable, editable a mano y auditable, y no ata el flujo a ningún asistente.
+
+export const SEVERITIES = ["low", "medium", "high"];
+const SEV = {
+  low: { emoji: "🔵", label: "Low" },
+  medium: { emoji: "🟡", label: "Medium" },
+  high: { emoji: "🔴", label: "High" },
+};
+const rank = (s) => SEVERITIES.indexOf(s);
+
+// ── Parseo del review.json ───────────────────────────────────────────────────
+// Errores accionables: un LLM se equivoca, y "Unexpected token" no le dice dónde.
+
+function fail(msg) {
+  throw new Error(`review.json inválido: ${msg}`);
+}
+
+export function parseFindings(text) {
+  let j;
+  try {
+    j = typeof text === "string" ? JSON.parse(text) : text;
+  } catch (e) {
+    fail(`no es JSON válido (${e.message}).`);
+  }
+  if (!j || typeof j !== "object" || Array.isArray(j)) fail("la raíz tiene que ser un objeto.");
+  if (!Array.isArray(j.findings)) fail("falta el array 'findings' (puede ir vacío, pero tiene que estar).");
+
+  const findings = j.findings.map((f, i) => {
+    const at = `findings[${i}]`;
+    if (!f || typeof f !== "object") fail(`${at}: tiene que ser un objeto.`);
+    if (typeof f.path !== "string" || !f.path.trim()) fail(`${at}: falta 'path' (ruta del archivo, relativa a la raíz del repo).`);
+    if (!Number.isInteger(f.line) || f.line < 1) fail(`${at} (${f.path}): 'line' tiene que ser un entero ≥ 1, vino ${JSON.stringify(f.line)}.`);
+    if (typeof f.body !== "string" || !f.body.trim()) fail(`${at} (${f.path}:${f.line}): falta 'body' (el hallazgo, en prosa).`);
+    const side = f.side === undefined ? "RIGHT" : String(f.side).toUpperCase();
+    if (side !== "RIGHT" && side !== "LEFT") fail(`${at} (${f.path}:${f.line}): 'side' tiene que ser RIGHT o LEFT, vino ${JSON.stringify(f.side)}.`);
+    if (!SEVERITIES.includes(f.severity)) fail(`${at} (${f.path}:${f.line}): 'severity' tiene que ser ${SEVERITIES.join(" | ")}, vino ${JSON.stringify(f.severity)}.`);
+    const confidence = f.confidence === undefined ? 1 : f.confidence;
+    if (typeof confidence !== "number" || confidence < 0 || confidence > 1) {
+      fail(`${at} (${f.path}:${f.line}): 'confidence' tiene que ser un número entre 0 y 1, vino ${JSON.stringify(f.confidence)}.`);
+    }
+    return { path: f.path.trim(), line: f.line, side, severity: f.severity, confidence, body: f.body.trim() };
+  });
+
+  return {
+    us: j.us ?? null,
+    version: j.version ?? null,
+    checkStatus: j.checkStatus ?? null,
+    dod: j.dod ?? null,
+    summary: typeof j.summary === "string" ? j.summary.trim() : "",
+    good: Array.isArray(j.good) ? j.good.filter((g) => typeof g === "string" && g.trim()) : [],
+    findings,
+  };
+}
+
+// ── Posiciones válidas según el diff ─────────────────────────────────────────
+// El anti-alucinación. Un LLM inventa números de línea con una facilidad pasmosa, y el
+// forge responde 422 sin decir cuál falló. Como el diff ya lo tenemos local, se verifica
+// acá antes de salir a la red.
+//
+// Devuelve: Map<path, { right: Set<line>, left: Set<line> }>. Las líneas de contexto
+// cuentan de los dos lados: el forge acepta comentarlas, son parte del hunk.
+
+export function diffPositions(diff) {
+  const files = new Map();
+  let cur = null, newLine = 0, oldLine = 0;
+
+  for (const raw of String(diff ?? "").split(/\r?\n/)) {
+    // Ojo el orden: '+++ ' y '--- ' empiezan con '+' y '-'. Van ANTES que las de contenido.
+    if (raw.startsWith("+++ ")) {
+      const p = raw.slice(4).trim().replace(/\t.*$/, "");
+      if (p === "/dev/null") { cur = null; continue; }        // archivo borrado: no hay lado derecho
+      cur = { right: new Set(), left: new Set() };
+      files.set(stripDiffPrefix(p), cur);
+      continue;
+    }
+    if (raw.startsWith("--- ")) continue;
+    if (raw.startsWith("@@")) {
+      const m = raw.match(/^@@+ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+      if (m) { oldLine = Number(m[1]); newLine = Number(m[2]); }
+      continue;
+    }
+    if (!cur) continue;
+    if (raw.startsWith("+")) cur.right.add(newLine++);
+    else if (raw.startsWith("-")) cur.left.add(oldLine++);
+    else if (raw.startsWith(" ")) { cur.right.add(newLine++); cur.left.add(oldLine++); }
+    // "", "index …", "diff --git …", "similarity …": se ignoran
+  }
+  return files;
+}
+
+// "b/src/x.ts" → "src/x.ts". git usa a//b/ como prefijos del diff.
+function stripDiffPrefix(p) {
+  return p.replace(/^[ab]\//, "");
+}
+
+// ── Validación ───────────────────────────────────────────────────────────────
+// Un hallazgo que no apunta al diff NO se postea. Se reporta, no se descarta en silencio.
+
+export function validateFindings(findings, positions) {
+  const valid = [], rejected = [];
+  for (const f of findings) {
+    const pos = positions.get(f.path);
+    if (!pos) {
+      rejected.push({ finding: f, reason: "el archivo no aparece en el diff" });
+      continue;
+    }
+    const lines = f.side === "LEFT" ? pos.left : pos.right;
+    if (!lines.has(f.line)) {
+      rejected.push({ finding: f, reason: `la línea ${f.line} no es parte del diff (lado ${f.side})` });
+      continue;
+    }
+    valid.push(f);
+  }
+  return { valid, rejected };
+}
+
+// ── Filtros ──────────────────────────────────────────────────────────────────
+// Lo que habilita el modo desatendido con red: por debajo del umbral, el hallazgo no se
+// postea pero se lista en el resumen. Nada se cae en silencio.
+
+export function filterFindings(findings, { minSeverity = "low", minConfidence = 0, maxComments = Infinity } = {}) {
+  if (!SEVERITIES.includes(minSeverity)) throw new Error(`--min-severity: valores ${SEVERITIES.join(" | ")}, vino '${minSeverity}'.`);
+  const kept = [], suppressed = [];
+  // Ordenado por severidad y después por confianza: si hay tope, se cortan los menos graves.
+  const sorted = [...findings].sort((a, b) => rank(b.severity) - rank(a.severity) || b.confidence - a.confidence);
+  for (const f of sorted) {
+    if (rank(f.severity) < rank(minSeverity)) { suppressed.push({ finding: f, reason: `severidad ${f.severity} < ${minSeverity}` }); continue; }
+    if (f.confidence < minConfidence) { suppressed.push({ finding: f, reason: `confianza ${f.confidence} < ${minConfidence}` }); continue; }
+    if (kept.length >= maxComments) { suppressed.push({ finding: f, reason: `tope de --max-comments (${maxComments})` }); continue; }
+    kept.push(f);
+  }
+  return { kept, suppressed };
+}
+
+// ── Render ───────────────────────────────────────────────────────────────────
+
+// El cuerpo de un comentario inline. Lleva marca de dai a propósito: el comentario se
+// postea con el token del humano, así que el forge lo atribuye a él SIN badge de bot. Sin
+// esta línea, el compañero ve un juicio sobre su código firmado por una persona, sin
+// forma de saber que lo escribió una máquina.
+export function renderFindingBody(f) {
+  const { emoji, label } = SEV[f.severity];
+  return `${emoji} **${label}** — ${f.body}\n\n<sub>🤖 <code>dai-review</code> · revisión asistida por IA, revisada y firmada por un humano</sub>`;
+}
+
+const bullets = (arr) => (arr.length ? arr.map((x) => `- ${x}`).join("\n") : "- — ninguno —");
+
+function detailsList(title, items) {
+  if (!items.length) return null;
+  const rows = items.map(({ finding: f, reason }) => `- \`${f.path}:${f.line}\` (${f.severity}) — ${reason}\n  > ${f.body.split("\n")[0]}`);
+  return `<details>\n<summary>${title} (${items.length})</summary>\n\n${rows.join("\n")}\n\n</details>`;
+}
+
+// El cuerpo del review (el "Pull request overview"). Mismo encabezado de metodología que
+// renderReviewComment — los reviews del equipo se siguen leyendo igual.
+export function renderReviewSummary(r, { kept = [], suppressed = [], rejected = [] } = {}) {
+  const head = r.us
+    ? `**US:** \`${r.us}\`${r.version ? ` @ ${r.version}` : ""} · \`dai check\`: ${r.checkStatus || "?"}`
+    : "**US:** _(este PR no declara implementar una US)_";
+
+  const counts = SEVERITIES.slice().reverse()
+    .map((s) => ({ s, n: kept.filter((f) => f.severity === s).length }))
+    .filter(({ n }) => n > 0)
+    .map(({ s, n }) => `${n} ${SEV[s].emoji} ${SEV[s].label}`);
+
+  const hallazgos = kept.length
+    ? `Dejé **${kept.length}** ${kept.length === 1 ? "comentario" : "comentarios"} en línea: ${counts.join(" · ")}.`
+    : "Sin comentarios en línea: no encontré nada concreto que marcar.";
+
+  return [
+    "## 🤖 dai-review",
+    "",
+    head,
+    r.dod ? `**Definition of Done:** ${r.dod}` : null,
+    "",
+    r.summary || null,
+    r.summary ? "" : null,
+    "### Hallazgos",
+    hallazgos,
+    "",
+    "### ✅ Lo que está bien",
+    bullets(r.good),
+    "",
+    detailsList("Suprimidos por el filtro", suppressed),
+    detailsList("Descartados: no apuntan al diff", rejected),
+    "",
+    "---",
+    "_Revisión asistida por dai. La aprobación la firma un humano (Art. 5 del manifiesto)._",
+  ].filter((l) => l !== null).join("\n").replace(/\n{3,}/g, "\n\n") + "\n";
+}

package/cli/lib/skills-source.mjs

@@ -15,6 +15,14 @@ export function parseSource(src) {
   const hash = raw.lastIndexOf("#");
   if (hash > 0) { ref = raw.slice(hash + 1) || null; loc = raw.slice(0, hash); }
 
+  // Paquete npm: `npm:@scope/pkg[@version]`. dai hace `npm pack` a un temp, respetando el
+  // `.npmrc` del repo (así resuelve registries privados con scope). La versión va en el
+  // propio spec (`@1.2.3`), no como ref con '#'.
+  if (loc.startsWith("npm:")) {
+    const spec = loc.slice(4).trim();
+    if (!spec) throw new Error("fuente npm vacía (usá npm:@scope/paquete)");
+    return { type: "npm", location: spec, ref: null };
+  }
   // Path local explícito (./ ../ / ~/).
   if (/^(\.\.?\/|\/|~\/)/.test(loc)) return { type: "path", location: loc, ref };
   // git por sintaxis de URL (https, ssh, scp git@host:…).

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

@@ -12,10 +12,10 @@
 
 | Paso | Skill / evento | Artefacto que produce |
 |---|---|---|
-| 1 Refinamiento | `grill-intent` → `grill-user-story` | `intent.md` + la **US** (`ABC-482`) |
+| 1 Refinamiento | `grill-user-story` → `grill-intent` (Gate 0) | la **US** (`ABC-482`) + `intent.md` |
 | 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) |
+| 4 Implementación | `opsx:apply` (con TDD) | test (RED) → código (GREEN), por el agente |
 | 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 |
@@ -37,34 +37,9 @@ 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
+### 1b · `grill-user-story` produce la US
 
-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
+Acá entra la IA: `grill-user-story` interroga al PO hasta que la US es **testeable por
 construcción** ([`formato-us.md`](../templates/formato-us.md)) y la publica en el gestor:
 
 ```markdown
@@ -113,6 +88,33 @@ para **recibir los productos que elijo sin sorpresas**.
 > 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).
 
+### 1c · Gate 0 — `grill-intent` desafía el problema
+
+Con la US ya formada, **antes** de invertir en el spec, el Gate 0 cuestiona 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. Si
+hubiera dado *reframe* o *don't build*, la US volvería al PO **antes** de gastar un solo
+artefacto de spec — ese es el punto del Gate 0.
+
 ---
 
 ## Paso 2 — Planning: `opsx:propose` deriva el CÓMO
@@ -175,9 +177,10 @@ autor: D. Force (dev)
 
 ---
 
-## Paso 4 — TDD: un test a la vez (RED → GREEN)
+## Paso 4 — Implementación: el agente construye con TDD (`/opsx:apply`)
 
-Vertical slice del AC-2 (el guard del carrito vacío). **Primero el test (RED):**
+`/opsx:apply` implementa las tareas del change, un test a la vez. 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 () => {
@@ -205,8 +208,9 @@ export async function finalizarCompra(id: CarritoId) {
 // ▶ 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`).
+> El test (que escribió el agente) verifica por la **interfaz pública**
+> (`finalizarCompra`, `ordenesDe`), no espía lo interno. Sobrevive a un refactor
+> (Art. 7 + skill `tdd`). El dev revisa cada slice: es responsable del código.
 
 ---
 
@@ -239,21 +243,26 @@ $ 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:
+El **partner** revisa la PR. Se apoya en la skill `/dai-review` para un primer pase: deja
+un **review inline** (resumen + un comentario anclado por línea, low/medium/high). La skill
+le muestra el preview y **espera su OK antes de postear**; después el partner **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.
+🤖 /dai-review — resumen
+  US: ABC-482 @ v1 · dai check: ✅ al día · DoD: 5/5
+  1 comentario en línea: 1 🔵 Low.
+
+🔵 Low — src/checkout/errors.ts:12
+  CarritoVacioError y SinStockError podrían extender un DomainError común,
+  como el resto del módulo.
 
-👤 M. Gómez (partner): de acuerdo con el DomainError. Aprobado tras el ajuste.
+👤 M. Gómez (partner): reviso el preview, lo posteo, y apruebo 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.
+> El review sale con el nombre y el token del partner (nunca `APPROVE` automático): la
+> skill asiste, la persona firma.
 
 ---
 
@@ -282,7 +291,7 @@ ABC-482 · implementado por  (lo estampó dai stamp)
 ## 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).
+> tomo ABC-490. Sin trabas."* — La IA no genera esto; el equipo se sincroniza (Art. 6).
 
 ## Paso 9 — Review / Demo
 

package/docs/MANIFIESTO.md

@@ -3,7 +3,7 @@
 > **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
+> respuesta está aquí. 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
@@ -56,7 +56,7 @@ 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
+No se improvisa código sobre una idea vaga. Toda implementación parte 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".
 

package/docs/METODOLOGIA.md

@@ -2,7 +2,7 @@
 
 > **Fuente de verdad única.** Este documento es el maestro. Los dos HTML
 > (`desarrollo-asistido-por-ia.html` federado y `-equipos-compactos.html`) son
-> **vistas de presentación** derivadas de acá — si algo contradice a este `.md`,
+> **vistas de presentación** derivadas de aquí — si algo contradice a este `.md`,
 > gana este `.md`. Versionado por git para que no driftee.
 
 Una sola metodología para dos escalas opuestas:
@@ -57,9 +57,9 @@ identidad el día que se crea el ticket/change.
 ### 2.2 Formato linkeable garantizado
 
 El QUÉ se produce con una forma mínima **testeable**: `id · spec_version · autor ·
-criterios de aceptación en Gherkin`. Es exactamente lo que aseguran las skills
-`grill-intent` → `grill-user-story` (ver `formato-us.md`). Sin esa forma, no hay
-a qué linkear.
+criterios de aceptación en Gherkin`. Es exactamente lo que asegura la skill
+`grill-user-story` (y después el Gate 0 de `grill-intent` desafía el problema; ver
+`formato-us.md`). Sin esa forma, no hay a qué linkear.
 
 ### 2.3 El link se autora una sola vez, del lado del CÓMO
 
@@ -122,8 +122,10 @@ federación.**
 
 El CÓMO se construye con **test primero**, en *vertical slices* (un test → una
 implementación → repetir), verificando por la **interfaz pública**, no espiando lo
-interno. Un buen test lee como una spec y sobrevive a un refactor. Ver
-`skills/tdd/`.
+interno. Un buen test lee como una spec y sobrevive a un refactor. **Quien lo ejecuta
+es el agente**, dentro de `/opsx:apply` (la disciplina la encapsula la skill `tdd`); el
+dev decide qué comportamientos importa testear y es responsable de revisar el resultado
+([Art. 7](MANIFIESTO.md#art-7)). Ver `skills/tdd/`.
 
 ---
 
@@ -134,7 +136,7 @@ duele, no antes.**
 
 | | **N1 · Solo / 1 repo** | **N2 · Equipo compacto** | **N3 · Federado** |
 |---|---|---|---|
-| Caso típico | equipo chico arrancando, un dev | equipo chico | organización grande |
+| Caso típico | equipo chico empezando, un dev | equipo chico | organización grande |
 | El QUÉ vive en | `proposal.md` de OpenSpec | ClickUp (US) → el change la referencia | Jira (`ABC-###`, hub) |
 | El link vive en | la carpeta del change (co-localizado) | `implements.yaml` en el repo | `implements.yaml` versionado |
 | Inversa la genera | un comando local | comando / CI liviano | CI estampa cobertura + CD reporta ambiente |
@@ -178,13 +180,13 @@ El artefacto no desaparece; se aligera la ceremonia alrededor.
 
 ```
    ①  Nace la idea            → ticket vago en el PM (o intención suelta en N1)
-   ②  Gate 0: ¿problema OK?   → /grill-intent  → veredicto: a-spec / reframe / descartar
-   ③  Se pule el QUÉ          → /grill-user-story → US testeable (formato-us.md),
+   ②  Se pule el QUÉ          → /grill-user-story → US testeable (formato-us.md),
                                  publicada en Jira/ClickUp (o .md si no hay MCP)
+   ③  Gate 0: ¿problema OK?   → /grill-intent  → veredicto: a-spec / reframe / descartar
    ④  Se abre el CÓMO         → /link-us ABC-###  → branch + implements.yaml ligados al ID
    ⑤  Se arma el change       → opsx:explore → opsx:propose (proposal/design/tasks + specs)
-   ⑥  Se implementa           → TDD (red → green → refactor), vertical slices
-   ⑦  Se promueve             → opsx:apply → opsx:archive; el CI estampa cobertura en el PM
+   ⑥  Se implementa           → opsx:apply → el agente aplica las tareas con TDD (red→green→refactor)
+   ⑦  Se promueve             → opsx:archive; el CI estampa cobertura en el PM
    ⑧  Se despliega            → el CD reporta a qué ambiente (dev/test/pre/prod) fue la versión
 ```
 
@@ -203,11 +205,14 @@ El artefacto no desaparece; se aligera la ceremonia alrededor.
 
 | Skill | Lado | Qué hace |
 |---|---|---|
-| `grill-intent` | QUÉ | Gate 0: desafía el *problema* antes de escribir spec. Veredicto: a-spec / reframe / descartar. |
+| `doc-to-backlog` | QUÉ | Un documento (PDF/Word) → backlog candidato de épicas + US para priorizar. |
+| `grill-epic` | QUÉ | Algo grande → una épica partida en varias US. |
 | `grill-user-story` | QUÉ | Interroga hasta producir una US testeable (INVEST + Gherkin). Publica en Jira/ClickUp o deja `.md`. |
+| `grill-intent` | QUÉ | Gate 0: con la US ya formada, desafía el *problema* antes de escribir spec. Veredicto: a-spec / reframe / descartar. |
 | `link-us` | CÓMO | Crea branch + `implements.yaml` desde el ID del PM. El link, correcto por construcción. |
-| `tdd` | CÓMO | Red-green-refactor en vertical slices, tests por interfaz pública. |
-| `opsx:*` | CÓMO | OpenSpec: explore → propose → apply → archive. Lo provee OpenSpec. |
+| `opsx:*` | CÓMO | OpenSpec: explore → propose → apply (el agente implementa con TDD) → archive. Lo provee OpenSpec. |
+| `tdd` | CÓMO | La disciplina red-green-refactor (vertical slices, tests por interfaz pública) que aplica `opsx:apply`. |
+| `dai-review` | CÓMO | Review inline de una PR/MR ajena: resumen + un comentario por línea, con gate humano de OK antes de postear. |
 
 El **adaptador de PM** es un seam único: las skills del QUÉ publican en Jira **o**
 ClickUp **o** dejan un `.md` según qué MCP/token haya. Es la **misma** skill con
@@ -228,7 +233,7 @@ de N3 queda **una** decisión sin resolver; el resto se cerró al construir la h
 
 **Ya resueltas** (al construir dai):
 - **Adaptador de PM configurable** → `getAdapter` (backends `md`/`jira`/`clickup`, token del
-  `.env`); modelo de auth en [ADR-0007](adr/0007-modelo-de-autenticacion.md).
+  `.env.dai` no versionado — [ADR-0017](adr/0017-env-dai.md)); modelo de auth en [ADR-0007](adr/0007-modelo-de-autenticacion.md).
 - **Formato de `implements.yaml`** → congelado en [ADR-0004](adr/0004-ubicacion-y-schema-implements.md)
   (schema + ubicación + descubrimiento por glob).
 - **Escritura multi-repo en el tracker** → `dai stamp` deja un **comentario por repo** (no se

package/docs/PROBAR.md

@@ -1,8 +1,8 @@
 # Probar dai
 
-No hace falta publicar en npm para probarlo. Se prueba local. Recomendado: hacer la
-**Fase 0** (backend `md`, sin credenciales) para validar el flujo, y después la
-**Fase 1** (ClickUp real).
+La forma más rápida de conocer dai: instala el CLI y corre el ciclo completo en tu
+máquina. Empieza **sin credenciales** (backend `md`) para ver el flujo entero en un par de
+minutos, y después pruébalo **contra tu tracker real** (ClickUp o Jira).
 
 > Esto es la guía para **usar** dai por primera vez. Para verlo funcionando sobre una
 > US real (narrado), mira [`EJEMPLO-END-TO-END.md`](EJEMPLO-END-TO-END.md).
@@ -10,19 +10,17 @@ No hace falta publicar en npm para probarlo. Se prueba local. Recomendado: hacer
 ## Instalar el CLI
 
 ```bash
-npm i -g @dforce2055/dai        # desde npm
-# — o, si clonaste el repo —
-git clone https://github.com/dforce2055/dai && cd dai && npm link
-
+npm i -g @dforce2055/dai
 dai --version
 ```
 
-## Fase 0 — sin credenciales (backend `md`)
+## Paso 1 — sin credenciales (backend `md`)
 
-Valida el loop completo `link-us → check → stamp` sin depender de red ni tokens.
+Recorre el loop completo `link-us → check → stamp` sin red ni tokens: todo local. Perfecto
+para ver cómo funciona antes de conectar nada.
 
 ```bash
-# 1. Repo de prueba + bootstrap (dai init deja el .env; elige "md" cuando pregunte)
+# 1. Repo de prueba + bootstrap (dai init deja el .env.dai; elige "md" cuando pregunte)
 mkdir /tmp/dai-test && cd /tmp/dai-test
 git init && git commit --allow-empty -m init
 git remote add origin git@github.com:TU-USUARIO/dai-test.git   # para los links de branch/commit
@@ -48,9 +46,9 @@ dai check                        # ⚠️ ATRASADO (exit 1)  → sugiere: dai li
 dai stamp                        # con md, deja .dai/us/<slug>.coverage.md
 ```
 
-Si esto anda, el flujo está bien. Pasa al tracker real.
+Con esto ya viste el ciclo entero. Ahora conéctalo a tu tracker real.
 
-## Fase 1 — ClickUp real
+## Paso 2 — contra tu tracker real (ClickUp)
 
 **Preparar ClickUp:**
 
@@ -62,7 +60,7 @@ Si esto anda, el flujo está bien. Pasa al tracker real.
 **Config y flujo:**
 
 ```bash
-cat > .env <<'EOF'
+cat > .env.dai <<'EOF'
 DAI_PM=clickup
 DAI_CLICKUP_TOKEN=pk_XXXXXXXX
 EOF
@@ -79,7 +77,8 @@ dai check                        # ⚠️ ATRASADO (lo detectó solo)
 dai stamp                        # deja un COMENTARIO en la tarea con la cobertura
 ```
 
-> El `.env` está gitignored: el token no se commitea (ADR-0007).
+> El `.env.dai` **no se versiona**: el token no se commitea, y el `.env` del equipo no se
+> toca ([ADR-0017](adr/0017-env-dai.md); modelo de auth en [ADR-0007](adr/0007-modelo-de-autenticacion.md)).
 
 ## Troubleshooting
 

package/docs/SCRUM-CON-IA.md

@@ -49,9 +49,9 @@
 |---|---|
 | **Clásico** | El PO parte épicas en Historias de Usuario y les pone criterios de aceptación. |
 | **Dolor** | US vagas, no testeables ("el usuario quiere un botón"). El malentendido se descubre tarde, ya implementado. |
-| **Con IA** | `grill-intent` (Gate 0: ¿es el problema correcto? veredicto a-spec / reframe / descartar) y luego `grill-user-story` **interrogan** al PO hasta que la US es testeable por construcción (INVEST + Gherkin). La IA no *escribe* la US: la *saca a preguntas*. La US nace con ID estable y criterios hasheables. |
+| **Con IA** | `grill-user-story` **interroga** al PO hasta que la US es testeable por construcción (INVEST + Gherkin); y después el Gate 0 de `grill-intent` desafía el *problema* detrás (veredicto: a-spec / reframe / descartar). La IA no *escribe* la US: la *saca a preguntas*. La US nace con ID estable y criterios hasheables. |
 | **Humano (HITL)** | El PO responde y decide. La IA no inventa requerimientos: los pule. |
-| **Herramienta** | `grill-intent`, `grill-user-story`, `formato-us.md` |
+| **Herramienta** | `grill-user-story`, `grill-intent`, `formato-us.md` |
 | **Detalle →** | [`detalle/01-refinamiento.md`](detalle/01-refinamiento.md) |
 
 #### 2. Sprint Planning: comprometer US y derivar tareas
@@ -76,19 +76,19 @@
 | **Clásico** | El dev crea una rama para trabajar la US. |
 | **Dolor** | Nombres inconsistentes, ramas que no se sabe a qué US pertenecen → trazabilidad rota desde el commit uno. |
 | **Con IA** | `link-us ABC-###` crea la rama **desde el ID de la US, sin tipearlo a mano**, y genera el `implements.yaml`. La rama *es* el link: correcto por construcción. |
-| **Humano (HITL)** | El dev elige qué US agarra. |
+| **Humano (HITL)** | El dev elige qué US toma. |
 | **Herramienta** | `link-us` |
 | **Detalle →** | [`detalle/03-ramas.md`](detalle/03-ramas.md) |
 
-#### 4. Implementación con TDD
+#### 4. Implementación (`/opsx:apply`, con TDD)
 
 | | |
 |---|---|
 | **Clásico** | El dev codea. Idealmente con tests. |
 | **Dolor** | Se codea primero y se testea "si queda tiempo" (nunca queda). Vibe coding. |
-| **Con IA** | La skill `tdd` fuerza test→código en *vertical slices* (un test → una implementación → repetir). La IA escribe el test como spec ejecutable **antes** del código, verificando por la interfaz pública. Anti vibe-coding real. |
-| **Humano (HITL)** | El dev decide qué comportamientos importa testear y revisa cada slice. |
-| **Herramienta** | `tdd` |
+| **Con IA** | El **agente implementa** con `/opsx:apply`: aplica las tareas de `opsx:propose` en *vertical slices* (un test → el código mínimo → repetir), escribiendo el test como spec ejecutable **antes** del código y verificando por la interfaz pública (la disciplina TDD la encapsula la skill `tdd`). Anti vibe-coding real. |
+| **Humano (HITL)** | El dev decide qué comportamientos importa testear, valida cada slice y **es responsable del código** (no la IA) — lo revisa en el paso 6. |
+| **Herramienta** | `opsx:apply` (con la disciplina de `tdd`) |
 | **Detalle →** | [`detalle/04-tdd.md`](detalle/04-tdd.md) |
 
 #### 5. Smoke test de la US
@@ -108,9 +108,9 @@
 |---|---|
 | **Clásico** | Un compañero revisa el PR/MR antes de mergear. |
 | **Dolor** | Depende de que el partner tenga tiempo y ganas; reviews superficiales que dejan pasar lo importante. |
-| **Con IA** | La IA hace el **primer pase** (correctitud + estándares del repo) antes del humano. El partner revisa lo que importa, no el ruido. |
+| **Con IA** | La IA hace el **primer pase**: un **review inline** (corre `dai check` + valida el DoD, y deja un resumen + **un comentario por línea**, low/medium/high). Muestra el preview y **espera el OK del partner antes de postear**; el partner revisa lo que importa, no el ruido. |
 | **Humano (HITL)** | El partner aprueba o rechaza. La IA sugiere; la persona decide y firma. |
-| **Herramienta** | `dai-review` |
+| **Herramienta** | `dai-review` (`dai forge review`) |
 | **Detalle →** | [`detalle/06-code-review.md`](detalle/06-code-review.md) |
 
 #### 7. Merge + trazabilidad automática
@@ -170,7 +170,7 @@
 | 1 Refinamiento | ●●● | La US testeable es la base de todo. |
 | 2 Planning | ●● | El design y las tareas se derivan de la US. |
 | 3 Rama | ●●● | El link correcto por construcción. |
-| 4 TDD | ●●● | El corazón del anti vibe-coding. |
+| 4 Implementación | ●●● | El agente construye con TDD; el corazón del anti vibe-coding. |
 | 5 Smoke | ●● | Cierre verificable de la US. |
 | 6 Code review | ●● | Primer pase automático, humano decide. |
 | 7 Merge + trazabilidad | ●●● | La matriz se deriva sola. |

package/docs/adr/0003-deteccion-y-estampado-son-comandos.md

@@ -49,7 +49,7 @@ Pasar de distribuido a automático es mover la invocación, no reescribir nada.
 
 ## Consecuencias
 
-- ✅ **No hace falta ningún CI para empezar.** La metodología arranca con un dev
+- ✅ **No hace falta ningún CI para empezar.** La metodología empieza con un dev
   tipeando `dai check` / `dai stamp`. El [Art. 14](../MANIFIESTO.md#art-14) queda respetado.
 - ✅ **Rampa de adopción continua:** manual → git-hook → CI, siempre el mismo comando.
 - ✅ **Honra el [Art. 10](../MANIFIESTO.md#art-10):** el humano *dispara* la derivación; no *escribe a mano* el

package/docs/adr/0006-distribucion-y-licencia.md

@@ -20,7 +20,7 @@ más fuerte de eso es el **copyleft**: quien distribuya un `dai` modificado debe
 publicar sus cambios bajo la misma licencia. La GPL convierte "las mejoras vuelven"
 en cláusula, no en deseo.
 
-El downside típico de la GPL **no aplica** acá: `dai` es un **CLI que se ejecuta**,
+El downside típico de la GPL **no aplica** aquí: `dai` es un **CLI que se ejecuta**,
 no una librería que se embebe. Usar `dai` sobre tu código —aunque sea propietario y
 comercial— **no genera ninguna obligación**; el copyleft solo se activa si alguien
 **forkea y redistribuye** una versión modificada. Y *libre ≠ gratis*: se puede