@dforce2055/dai 0.1.0

package/cli/lib/ac-hash.mjs

@@ -0,0 +1,74 @@
+// dai · cálculo del ac_hash — contrato en docs/adr/0001-contrato-ac-hash.md
+//
+// El ac_hash es lo que hace que un cambio del QUÉ marque solo a los CÓMO
+// atrasados (Art. 11). DEBE calcularse idéntico acá y en el CI.
+//
+// Algoritmo (ADR-0001):
+//   1. Extraer el bloque "Criterios de aceptación" de la US.
+//   2. Normalizar: quitar marcado editorial (checkboxes, viñetas, énfasis,
+//      numeración AC-N, headings) y colapsar todo el whitespace.
+//   3. SHA-256 del texto normalizado, truncado a 8 hex.
+//
+// El ORDEN de los criterios es significativo: reordenar cambia el hash
+// (por eso el formato de US pide orden estable). No se ordena acá.
+
+import { createHash } from "node:crypto";
+
+// Encuentra el heading de criterios de aceptación y devuelve el texto hasta
+// el próximo heading de igual o menor nivel. Tolera el emoji 🔗 y variantes.
+export function extractAcBlock(markdown) {
+  const lines = markdown.split(/\r?\n/);
+  const headingRe = /^(#{1,6})\s+(.*)$/;
+  const isAcHeading = (t) =>
+    /criterios\s+de\s+aceptaci[oó]n/i.test(t.replace(/[🔗*_`#]/g, "").trim());
+
+  let start = -1;
+  let level = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(headingRe);
+    if (m && isAcHeading(m[2])) {
+      start = i + 1;
+      level = m[1].length;
+      break;
+    }
+  }
+  if (start === -1) return null; // sin bloque de criterios
+
+  let end = lines.length;
+  for (let i = start; i < lines.length; i++) {
+    const m = lines[i].match(headingRe);
+    if (m && m[1].length <= level) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n");
+}
+
+// Normaliza el bloque a texto canónico según el contrato.
+export function normalizeAcBlock(block) {
+  return block
+    .split(/\r?\n/)
+    .map((line) =>
+      line
+        .replace(/^\s*>\s?/, "")            // blockquotes
+        .replace(/^\s*[-*+]\s+\[[ xX]\]\s*/, "") // checkbox list items
+        .replace(/^\s*[-*+]\s+/, "")        // viñetas
+        .replace(/^\s*\d+[.)]\s+/, "")      // numeración de lista
+        .replace(/[*_`]+/g, "")             // énfasis / código inline (antes de AC-N)
+        .replace(/\bAC[-\s]?\d+\b\s*[—:\-]?\s*/gi, "") // etiquetas AC-N + separador
+        .replace(/^#{1,6}\s+/, "")          // headings sueltos
+    )
+    .join(" ")
+    .replace(/\s+/g, " ")                   // colapsar todo el whitespace
+    .trim();
+}
+
+// Devuelve el ac_hash (8 hex) de una US en markdown, o null si no hay criterios.
+export function acHash(markdown) {
+  const block = extractAcBlock(markdown);
+  if (block == null) return null;
+  const normalized = normalizeAcBlock(block);
+  if (normalized === "") return null;
+  return createHash("sha256").update(normalized, "utf8").digest("hex").slice(0, 8);
+}

package/cli/lib/args.mjs

@@ -0,0 +1,23 @@
+// dai · parser de argumentos del CLI (cero dependencias).
+// Distingue flags BOOLEANOS (`--force`, `--global`, `--dry-run`) de flags con
+// VALOR (`--us x`, `--local repo`): un flag toma valor solo si lo que sigue no es
+// otro flag. Así `--global --dry-run` NO consume mal el segundo.
+
+export const camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+
+export function parseFlags(argv) {
+  const opts = {};
+  const pos = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = camel(a.slice(2));
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("--")) { opts[key] = next; i++; }
+      else opts[key] = true;                 // flag booleano
+    } else {
+      pos.push(a);
+    }
+  }
+  return { opts, pos };
+}

package/cli/lib/bootstrap.mjs

@@ -0,0 +1,74 @@
+// dai · bootstrap de un repo: genera los adaptadores de asistente (ADR-0002, capa 3).
+// Una sola fuente (los SKILL.md) alimenta a Claude y a Copilot. Los archivos de
+// Copilot se GENERAN, no se mantienen a mano (si no, driftean).
+
+const REPO_URL = "https://github.com/dforce2055/dai";
+
+// Parsea el frontmatter YAML de un SKILL.md → { name, description, body }.
+export function parseFrontmatter(md) {
+  const m = md.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!m) return { name: null, description: null, body: md.trim() };
+  const fm = m[1];
+  const name = (fm.match(/^name:\s*(.+)$/m) || [])[1]?.trim() || null;
+  const description = (fm.match(/^description:\s*(.+)$/m) || [])[1]?.trim() || null;
+  return { name, description, body: m[2].trim() };
+}
+
+// Transforma un SKILL.md (Claude) en un prompt file de Copilot (.prompt.md).
+// Cambia el frontmatter; el cuerpo (la lógica) es el mismo.
+export function skillToPrompt(md) {
+  const { description, body } = parseFrontmatter(md);
+  const fm = [
+    "---",
+    "mode: agent",
+    description ? `description: ${JSON.stringify(description)}` : null,
+    "---",
+  ].filter((x) => x !== null).join("\n");
+  return `${fm}\n\n${body}\n`;
+}
+
+// Contenido del .env según el backend de PM elegido (tokens vacíos, a completar).
+export function envFor(pm) {
+  const head = "# Config de dai — completá lo que falte. NUNCA commitees tokens (.env está gitignored).\n";
+  if (pm === "clickup") {
+    return head + "DAI_PM=clickup\nDAI_CLICKUP_TOKEN=\nDAI_CLICKUP_LIST_ID=\nDAI_TRACKER_URL_TEMPLATE=https://app.clickup.com/t/{id}\n";
+  }
+  if (pm === "jira") {
+    return head + "DAI_PM=jira\nDAI_JIRA_BASE_URL=\nDAI_JIRA_EMAIL=\nDAI_JIRA_TOKEN=\nDAI_JIRA_PROJECT=\nDAI_JIRA_ISSUETYPE=Story\nDAI_TRACKER_URL_TEMPLATE=\n";
+  }
+  return head + "DAI_PM=md\nDAI_MD_US_DIR=.dai/us\n";
+}
+
+// La constitución del repo: se inyecta como CLAUDE.md (Claude) o
+// copilot-instructions.md (Copilot). Mismo núcleo, distinto encabezado.
+export function constitution(kind) {
+  const head = kind === "copilot"
+    ? "# Instrucciones de Copilot para este repo\n\nEste repo sigue la metodología **dai**. Aplicá estas reglas en todo lo que generes.\n\n> **Superficie:** los prompts de dai (`.github/prompts/`) se invocan solo en VS Code /\n> JetBrains, o como custom agents en el Copilot CLI — no en la app standalone ni en\n> github.com. El CLI `dai` corre en cualquier terminal."
+    : "# Constitución del proyecto (dai)\n\nEste repo sigue la metodología **dai**. Estas reglas gobiernan todo el trabajo.";
+  return `${head}
+
+## Valores
+
+1. El QUÉ y el CÓMO son cosas distintas, con dueños distintos.
+2. La IA asiste; la persona decide y firma.
+3. Nada existe si no se puede testear ni trazar.
+4. La ceremonia se agrega cuando duele, no antes.
+
+## Reglas
+
+- **No vibe coding:** toda implementación arranca de una US con criterios testeables.
+- **TDD:** test primero, por la interfaz pública; sobrevive a un refactor.
+- **El link se autora una vez** (\`implements.yaml\`); la cobertura se **deriva** (nunca a mano).
+- **Secretos:** en \`.env\` (nunca commiteados). git por **SSH**, APIs por **token scopeado**.
+- Separá el QUÉ (funcional) del CÓMO (técnico); no mezcles.
+
+## Herramientas
+
+- **Skills (el QUÉ):** \`doc-to-backlog\` (un doc → backlog) · \`grill-intent\` (Gate 0) · \`grill-epic\` (épicas) · \`grill-user-story\` (la US)
+- **Skills (el CÓMO):** \`link-us\`, \`tdd\`, \`dai-review\`
+- **CLI:** \`dai link-us <ID>\` · \`dai check\` · \`dai stamp\` · \`dai pr\` · \`dai ls\`
+- **Formatos:** \`.dai/templates/\` · **Governance:** \`.dai/governance/\`
+
+Detalle completo de la metodología: ${REPO_URL}
+`;
+}

package/cli/lib/env.mjs

@@ -0,0 +1,23 @@
+// dai · loader mínimo de .env (cero dependencias).
+// Carga variables desde un archivo .env SIN pisar las que ya estén en el entorno
+// (para que un valor exportado en la shell/CI gane sobre el archivo).
+
+import { readFileSync } from "node:fs";
+
+export function loadEnv(path = ".env", env = process.env) {
+  let text;
+  try { text = readFileSync(path, "utf8"); } catch { return env; } // sin .env: no pasa nada
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const m = line.match(/^(?:export\s+)?([\w.-]+)\s*=\s*(.*)$/);
+    if (!m) continue;
+    let [, key, val] = m;
+    val = val.trim();
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    if (!(key in env)) env[key] = val;
+  }
+  return env;
+}

package/cli/lib/forge-api.mjs

@@ -0,0 +1,96 @@
+// dai · API del forge para review de PR/MR (GitHub + GitLab).
+// Cara CLI del "forge adapter": lee la PR y postea el comentario vía REST + token.
+// La cara skill (MCP del forge) produce el MISMO comentario estándar.
+// Auth: token SCOPEADO (GITHUB_TOKEN / GITLAB_TOKEN), nunca contraseñas. git usa SSH.
+
+import { parseRemote, detectForge } from "./forge-url.mjs";
+
+// Resuelve una referencia de PR/MR: URL completa, o solo un número + el remoto git.
+//   → { forge, host, projectPath, owner, repo, number }
+export function parsePrRef(input, remote) {
+  const s = String(input ?? "").trim();
+  const url = s.match(/^https?:\/\/([^/]+)\/(.+?)\/(?:-\/)?(?:pull|merge_requests)\/(\d+)/i);
+  if (url) return build(url[1], url[2].replace(/\/+$/, ""), Number(url[3]));
+  if (/^\d+$/.test(s)) {
+    const r = parseRemote(remote);
+    return r ? build(r.host, r.path, Number(s)) : null;
+  }
+  return null;
+}
+
+function build(host, projectPath, number) {
+  const forge = detectForge(host);
+  const parts = projectPath.split("/");
+  return { forge, host, projectPath, owner: parts[0], repo: parts.slice(1).join("/"), number };
+}
+
+export function apiBase(ref) {
+  if (ref.forge === "github") return ref.host === "github.com" ? "https://api.github.com" : `https://${ref.host}/api/v3`;
+  if (ref.forge === "gitlab") return `https://${ref.host}/api/v4`;
+  throw new Error(`forge no soportado para review: ${ref.forge} (solo github/gitlab)`);
+}
+
+export function prApiUrl(ref) {
+  if (ref.forge === "github") return `${apiBase(ref)}/repos/${ref.owner}/${ref.repo}/pulls/${ref.number}`;
+  return `${apiBase(ref)}/projects/${encodeURIComponent(ref.projectPath)}/merge_requests/${ref.number}`;
+}
+
+export function commentApiUrl(ref) {
+  if (ref.forge === "github") return `${apiBase(ref)}/repos/${ref.owner}/${ref.repo}/issues/${ref.number}/comments`;
+  return `${apiBase(ref)}/projects/${encodeURIComponent(ref.projectPath)}/merge_requests/${ref.number}/notes`;
+}
+
+export function authHeaders(ref, env = process.env) {
+  if (ref.forge === "github") {
+    return { Authorization: `Bearer ${env.GITHUB_TOKEN || ""}`, Accept: "application/vnd.github+json", "User-Agent": "dai" };
+  }
+  return { "PRIVATE-TOKEN": env.GITLAB_TOKEN || "" };
+}
+
+// Comentario estándar de dai-review (mismo formato lo emita el CLI o la skill).
+export function renderReviewComment(r) {
+  const { us, version, checkStatus, dod, errors = [], improvements = [], good = [] } = r;
+  const bul = (arr) => (arr.length ? arr.map((x) => `- ${x}`).join("\n") : "- — ninguno —");
+  const head = us
+    ? `**US:** \`${us}\`${version ? ` @ ${version}` : ""} · \`dai check\`: ${checkStatus || "?"}`
+    : "**US:** _(este PR no declara implementar una US)_";
+  return [
+    "## 🤖 dai-review",
+    "",
+    head,
+    dod ? `**Definition of Done:** ${dod}` : null,
+    "",
+    "### 🔴 Errores (correctitud)",
+    bul(errors),
+    "",
+    "### 🟡 Mejoras (calidad, reuso, simplicidad)",
+    bul(improvements),
+    "",
+    "### ✅ Lo que está bien",
+    bul(good),
+    "",
+    "---",
+    "_Revisión asistida por dai. La aprobación la firma un humano (Art. 5 del manifiesto)._",
+  ].filter((l) => l !== null).join("\n") + "\n";
+}
+
+// ── Efectos de red (testeados con fetch mockeado en cli/test) ────────────────
+export async function getPR(ref, env = process.env) {
+  const res = await fetch(prApiUrl(ref), { headers: authHeaders(ref, env) });
+  if (!res.ok) throw new Error(`forge ${res.status}: ${await res.text()}`);
+  const j = await res.json();
+  return ref.forge === "github"
+    ? { title: j.title, state: j.state, body: j.body, branch: j.head?.ref, url: j.html_url }
+    : { title: j.title, state: j.state, body: j.description, branch: j.source_branch, url: j.web_url };
+}
+
+export async function postComment(ref, body, env = process.env) {
+  const res = await fetch(commentApiUrl(ref), {
+    method: "POST",
+    headers: { ...authHeaders(ref, env), "Content-Type": "application/json" },
+    body: JSON.stringify({ body }),
+  });
+  if (!res.ok) throw new Error(`forge ${res.status}: ${await res.text()}`);
+  const j = await res.json();
+  return { url: j.html_url || j.web_url || null };
+}

package/cli/lib/forge-url.mjs

@@ -0,0 +1,61 @@
+// dai · construcción de URLs web desde el remoto de git (ADR-0005).
+// Deriva repo/branch/commit web URLs sin API del forge. La forma de la URL es
+// específica del forge (GitHub / GitLab / Bitbucket), detectada por el host.
+
+// Normaliza un remoto (SSH o HTTPS) a { host, path }.
+//   git@github.com:org/repo.git        → { host: github.com, path: org/repo }
+//   https://github.com/org/repo.git    → { host: github.com, path: org/repo }
+//   ssh://git@host:22/org/repo.git     → { host, path: org/repo }
+export function parseRemote(remote) {
+  if (!remote) return null;
+  let r = remote.trim();
+
+  // scp-like: git@host:org/repo(.git)
+  const scp = r.match(/^[\w.-]+@([^:]+):(.+)$/);
+  if (scp) return { host: scp[1], path: stripGit(scp[2]) };
+
+  // url-like: (ssh|https|http|git)://[user@]host[:port]/org/repo(.git)
+  const url = r.match(/^[a-z]+:\/\/(?:[^@/]+@)?([^:/]+)(?::\d+)?\/(.+)$/i);
+  if (url) return { host: url[1], path: stripGit(url[2]) };
+
+  return null;
+}
+
+function stripGit(p) {
+  return p.replace(/\/+$/, "").replace(/\.git$/, "");
+}
+
+// Detecta el forge por el host. Heurística + default GitHub-style.
+export function detectForge(host) {
+  const h = (host || "").toLowerCase();
+  if (h.includes("gitlab")) return "gitlab";
+  if (h.includes("bitbucket")) return "bitbucket";
+  if (h.includes("github")) return "github";
+  return "github"; // default: el esquema más común
+}
+
+export function repoWebUrl(remote) {
+  const p = parseRemote(remote);
+  if (!p) return null;
+  return `https://${p.host}/${p.path}`;
+}
+
+const SCHEMES = {
+  github:    { tree: "/tree/",     commit: "/commit/"  },
+  gitlab:    { tree: "/-/tree/",   commit: "/-/commit/" },
+  bitbucket: { tree: "/src/",      commit: "/commits/" },
+};
+
+export function branchUrl(remote, branch) {
+  const base = repoWebUrl(remote);
+  if (!base || !branch) return null;
+  const s = SCHEMES[detectForge(parseRemote(remote).host)];
+  return base + s.tree + encodeURIComponent(branch).replace(/%2F/g, "/");
+}
+
+export function commitUrl(remote, sha) {
+  const base = repoWebUrl(remote);
+  if (!base || !sha) return null;
+  const s = SCHEMES[detectForge(parseRemote(remote).host)];
+  return base + s.commit + sha;
+}

package/cli/lib/fsutil.mjs

@@ -0,0 +1,24 @@
+// dai · utilidades de filesystem para el instalador (cero dependencias).
+
+import { readdirSync, statSync, readFileSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+
+// Mapa { pathRelativo → contenido } de todos los archivos bajo dir.
+export function fileMap(dir, base = dir, map = {}) {
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    const st = statSync(p);
+    if (st.isDirectory()) fileMap(p, base, map);
+    else map[relative(base, p)] = readFileSync(p, "utf8");
+  }
+  return map;
+}
+
+// ¿Dos directorios tienen exactamente los mismos archivos con el mismo contenido?
+export function dirsEqual(a, b) {
+  if (!existsSync(a) || !existsSync(b)) return false;
+  const ma = fileMap(a), mb = fileMap(b);
+  const ka = Object.keys(ma).sort(), kb = Object.keys(mb).sort();
+  if (ka.length !== kb.length || ka.some((k, i) => k !== kb[i])) return false;
+  return ka.every((k) => ma[k] === mb[k]);
+}

package/cli/lib/implements.mjs

@@ -0,0 +1,94 @@
+// dai · parseo y descubrimiento de implements.yaml (ADR-0004).
+// Parser YAML mínimo para NUESTRO schema (cero dependencias). No es un parser
+// general de YAML: cubre exactamente la forma del implements.yaml.
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", "vendor", "coverage", ".next", ".cache",
+  // scaffolding del propio dai: contienen implements.yaml de PLANTILLA, no trabajo real
+  ".claude", ".github", ".dai",
+]);
+
+// ¿El id es todavía un placeholder de plantilla (ABC-###, <change-id>)? No es una US real.
+export function isPlaceholderId(id) {
+  return !id || /[#<>]/.test(id);
+}
+
+function unquote(v) {
+  const t = v.trim();
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+    return t.slice(1, -1);
+  }
+  return t;
+}
+
+function stripComment(line) {
+  // quita comentarios: `#` al inicio o precedido por espacio (nuestros valores no llevan #)
+  return line.replace(/(^|\s)#.*$/, "").replace(/\s+$/, "");
+}
+
+// Parsea el texto de un implements.yaml a un objeto estructurado.
+export function parseImplements(text) {
+  const out = { change: null, repo: null, implements: [], introduces: [], autor: null };
+  let listKey = null;   // key top-level cuyo valor es una lista
+  let curObj = null;    // objeto actual dentro de una lista de objetos
+
+  for (const raw of text.split(/\r?\n/)) {
+    const line = stripComment(raw);
+    if (line.trim() === "") continue;
+    const indent = line.length - line.trimStart().length;
+    const body = line.trim();
+
+    if (indent === 0) {
+      const m = body.match(/^([\w-]+):\s*(.*)$/);
+      if (!m) continue;
+      const [, key, val] = m;
+      if (val === "") { out[key] = out[key] ?? []; listKey = key; curObj = null; }
+      else { out[key] = unquote(val); listKey = null; curObj = null; }
+      continue;
+    }
+
+    // línea indentada: pertenece a la lista listKey
+    if (!listKey) continue;
+    if (body.startsWith("- ")) {
+      const rest = body.slice(2).trim();
+      const kv = rest.match(/^([\w-]+):\s*(.*)$/);
+      if (kv && kv[2] !== "") {           // item objeto: "- id: X"
+        curObj = { [kv[1]]: unquote(kv[2]) };
+        out[listKey].push(curObj);
+      } else {                            // item escalar: "- valor"
+        out[listKey].push(unquote(rest));
+        curObj = null;
+      }
+    } else if (curObj) {                  // atributo del objeto actual: "version: v1"
+      const kv = body.match(/^([\w-]+):\s*(.*)$/);
+      if (kv) curObj[kv[1]] = unquote(kv[2]);
+    }
+  }
+  return out;
+}
+
+// Camina el árbol desde root y devuelve { path, ...parsed } por cada implements.yaml.
+export function discoverImplements(root) {
+  const found = [];
+  const walk = (dir) => {
+    let entries;
+    try { entries = readdirSync(dir); } catch { return; }
+    for (const name of entries) {
+      const full = join(dir, name);
+      let st;
+      try { st = statSync(full); } catch { continue; }
+      if (st.isDirectory()) {
+        if (!SKIP_DIRS.has(name)) walk(full);
+      } else if (name === "implements.yaml") {
+        try {
+          found.push({ path: full, ...parseImplements(readFileSync(full, "utf8")) });
+        } catch { /* archivo inválido: se ignora en el listado */ }
+      }
+    }
+  };
+  walk(root);
+  return found;
+}

package/cli/lib/link-us.mjs

@@ -0,0 +1,59 @@
+// dai · helpers puros de link-us (crear el link QUÉ↔CÓMO por construcción).
+// La parte con efectos (git, escribir archivos) vive en dai.mjs; acá solo la
+// lógica pura y testeable: slug, nombre de branch, título, render del yaml.
+
+// Key del tracker, agnóstico de herramienta: Jira (`ABC-482`), ClickUp (`86cxyz`),
+// custom, etc. Solo exige un identificador sano para una branch/URL: sin espacios,
+// sin barras, no vacío.
+export const US_KEY_RE = /^[\w.-]+$/;
+
+export function isValidKey(key) {
+  return US_KEY_RE.test((key || "").trim());
+}
+
+// slug: minúsculas, sin acentos/ñ, no-alfanumérico → guion, recortado.
+export function slugify(s, max = 42) {
+  let out = (s || "")
+    .normalize("NFD").replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (out.length > max) { out = out.slice(0, max); const cut = out.lastIndexOf("-"); if (cut > 0) out = out.slice(0, cut); }
+  return out.replace(/-+$/g, "");
+}
+
+export function branchName(key, title) {
+  return `feature/${key}-${slugify(title)}`;
+}
+
+// Título de la US: primer H1 que NO sea la cabecera de metadata.
+export function extractTitle(md) {
+  for (const line of (md || "").split(/\r?\n/)) {
+    const m = line.match(/^#\s+(.+?)\s*$/);
+    if (!m) continue;
+    const text = m[1].replace(/[🔗*_`#]/g, "").trim();
+    if (/metadata/i.test(text)) continue;   // saltea "# 🔗 Metadata de trazabilidad"
+    if (text === "") continue;
+    return text;
+  }
+  return null;
+}
+
+// Render del implements.yaml (schema ADR-0004).
+export function renderImplementsYaml({ change, repo, id, version = "v1", ac_hash, autor }) {
+  return `# Link QUÉ↔CÓMO · scaffoldeado por dai link-us. El ÚNICO link autorado a mano.
+# Schema: docs/adr/0004-ubicacion-y-schema-implements.md
+change: ${change}
+repo:   ${repo}
+
+implements:
+  - id: ${id}
+    version: ${version}
+    ac_hash: ${ac_hash}
+
+introduces:
+  - <capacidad-tecnica>   # completar: specs técnicas nuevas de este change
+
+autor: ${autor}
+`;
+}

package/cli/lib/pm-adapter.mjs

@@ -0,0 +1,59 @@
+// dai · adaptador de PM (decisión abierta #3). Un contrato, varios backends.
+//
+// El adaptador tiene DOS caras (ADR-0002/0003): las skills publican la US por el
+// MCP del asistente; el CLI (esto) lee/escribe por su cuenta. Backends CLI:
+//   md      — local, offline (cero deps)
+//   jira    — REST v2 (pm-jira.mjs)
+//   clickup — REST v2 (pm-clickup.mjs)
+//
+// Interfaz (fetchUS/stamp pueden ser sync o async — el CLI siempre await-ea):
+//   fetchUS(id)          → { id, title, spec_version, ac_hash } | null
+//   stamp(id, record)    → destino donde quedó la cobertura
+//   kind                 → nombre del backend
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { parseUS, renderCoverage } from "./us.mjs";
+import { slugify } from "./link-us.mjs";
+import { jiraAdapter } from "./pm-jira.mjs";
+import { clickupAdapter } from "./pm-clickup.mjs";
+
+// Re-export para compatibilidad (tests y CLI importan estos desde acá).
+export { parseUS, coverageStatus, statusLabel, renderCoverage } from "./us.mjs";
+
+// ── backend md (local, offline) ───────────────────────────────────────────────
+function mdAdapter(env) {
+  const dir = env.DAI_MD_US_DIR || ".dai/us";
+  return {
+    kind: "md",
+    fetchUS(id) {
+      const p = join(dir, `${id}.md`);
+      if (!existsSync(p)) return null;
+      return { id, ...parseUS(readFileSync(p, "utf8")) };
+    },
+    stamp(id, record) {
+      const p = join(dir, `${id}.coverage.md`);
+      mkdirSync(dirname(p), { recursive: true });
+      writeFileSync(p, renderCoverage(id, record));
+      return p;
+    },
+    createUS({ title, descriptionMarkdown }) {
+      const id = slugify(title);            // sin tracker, el "key" es el slug del título
+      const p = join(dir, `${id}.md`);
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(p, descriptionMarkdown.startsWith("# ") ? descriptionMarkdown : `# ${title}\n\n${descriptionMarkdown}`);
+      return { id, url: p };
+    },
+  };
+}
+
+export function getAdapter(env = process.env) {
+  const kind = (env.DAI_PM || "md").toLowerCase();
+  switch (kind) {
+    case "md": return mdAdapter(env);
+    case "jira": return jiraAdapter(env);
+    case "clickup": return clickupAdapter(env);
+    default:
+      throw new Error(`DAI_PM desconocido: '${kind}'. Valores: md | jira | clickup.`);
+  }
+}

package/cli/lib/pm-clickup.mjs

@@ -0,0 +1,54 @@
+// dai · backend ClickUp del adaptador de PM (REST v2, cara CLI).
+// Auth: token personal en el header Authorization (ADR-0007).
+// Config: DAI_CLICKUP_TOKEN.
+
+import { parseUS, renderCoverage } from "./us.mjs";
+
+const API = "https://api.clickup.com/api/v2";
+
+// include_markdown_description=true → la API devuelve el markdown real (con los
+// headings), necesario para encontrar el bloque "Criterios de aceptación".
+export function clickupTaskUrl(id) {
+  return `${API}/task/${encodeURIComponent(id)}?include_markdown_description=true`;
+}
+export function clickupCommentUrl(id) { return `${API}/task/${encodeURIComponent(id)}/comment`; }
+export function clickupAuthHeaders(env) {
+  return { Authorization: env.DAI_CLICKUP_TOKEN || "", "Content-Type": "application/json" };
+}
+// Arma el texto de la US desde la respuesta de ClickUp (name + description).
+export function clickupTaskToText(json) {
+  const desc = json.markdown_description || json.description || json.text_content || "";
+  return `# ${json.name || json.id || ""}\n\n${desc}`;
+}
+
+export function clickupAdapter(env) {
+  if (!env.DAI_CLICKUP_TOKEN) throw new Error("falta DAI_CLICKUP_TOKEN en el .env (backend clickup).");
+  return {
+    kind: "clickup",
+    async fetchUS(id) {
+      const res = await fetch(clickupTaskUrl(id), { headers: clickupAuthHeaders(env) });
+      if (res.status === 404) return null;
+      if (!res.ok) throw new Error(`clickup ${res.status}: ${await res.text()}`);
+      return { id, ...parseUS(clickupTaskToText(await res.json())) };
+    },
+    async stamp(id, record) {
+      const res = await fetch(clickupCommentUrl(id), {
+        method: "POST", headers: clickupAuthHeaders(env),
+        body: JSON.stringify({ comment_text: renderCoverage(id, record) }),
+      });
+      if (!res.ok) throw new Error(`clickup ${res.status}: ${await res.text()}`);
+      return `task ${id} (comentario)`;
+    },
+    async createUS({ title, descriptionMarkdown }) {
+      const list = env.DAI_CLICKUP_LIST_ID;
+      if (!list) throw new Error("falta DAI_CLICKUP_LIST_ID en el .env (la lista donde crear la tarea).");
+      const res = await fetch(`${API}/list/${encodeURIComponent(list)}/task`, {
+        method: "POST", headers: clickupAuthHeaders(env),
+        body: JSON.stringify({ name: title, markdown_content: descriptionMarkdown }),
+      });
+      if (!res.ok) throw new Error(`clickup ${res.status}: ${await res.text()}`);
+      const j = await res.json();
+      return { id: j.id, url: j.url || null };
+    },
+  };
+}