@dforce2055/dai 0.6.0 → 0.8.0

package/cli/lib/bootstrap.mjs

@@ -4,29 +4,79 @@
 
 const REPO_URL = "https://github.com/dforce2055/dai";
 
+// Un escalar YAML "plano" (sin comillas) no puede contener `: ` ni ` #`, ni empezar con
+// un indicador: YAML lo leería como un mapa, un comentario o una estructura.
+//
+// Esto importa porque el parser de acá es un regex, no YAML — se traga cualquier cosa.
+// Mientras dai CONVERTÍA el SKILL.md para Copilot y Cursor, el `JSON.stringify` de la
+// conversión citaba el valor y tapaba el problema sin querer. Al entregar el SKILL.md
+// crudo (ADR-0014) lo lee un parser YAML de verdad, y ahí una descripción con un `: `
+// suelto tira abajo la skill entera. Le pasó a `doc-to-backlog` y a `grill-epic`.
+const YAML_INDICATORS = /^[-?:,[\]{}#&*!|>'"%@`]/;
+export function yamlScalarIssue(raw) {
+  const v = String(raw ?? "").trim();
+  if (v === "") return "está vacío";
+  const quoted = (v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"));
+  if (quoted && v.length >= 2) return null;      // citado: YAML acepta lo que sea adentro
+  if (v.includes(": ")) return "contiene ': ' sin comillas (YAML lo lee como un mapa)";
+  if (v.includes(" #")) return "contiene ' #' sin comillas (YAML lo lee como un comentario)";
+  if (YAML_INDICATORS.test(v)) return `empieza con '${v[0]}', que YAML reserva`;
+  return null;
+}
+
+// El valor crudo de una clave del frontmatter, tal cual está escrito (con comillas si
+// las tiene). Es lo que hay que validar: `parseFrontmatter` ya las saca.
+export function rawFrontmatterValue(md, key) {
+  const m = md.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (!m) return null;
+  const line = m[1].match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+  return line ? line[1].trim() : null;
+}
+
+// Saca las comillas de un escalar YAML citado. Sin comillas, lo devuelve tal cual.
+function unquoteScalar(s) {
+  if (s == null) return null;
+  const v = s.trim();
+  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
+    try { return JSON.parse(v); } catch { return v.slice(1, -1); }
+  }
+  if (v.length >= 2 && v.startsWith("'") && v.endsWith("'")) return v.slice(1, -1).replace(/''/g, "'");
+  return v;
+}
+
 // Parsea el frontmatter YAML de un SKILL.md → { name, description, body }.
+// Devuelve los valores YA sin comillas, para que quien los reserialice (skillToCursor)
+// no los cite dos veces.
 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;
+  const name = unquoteScalar((fm.match(/^name:\s*(.+)$/m) || [])[1]) || null;
+  const description = unquoteScalar((fm.match(/^description:\s*(.+)$/m) || [])[1]) || 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`;
+// Valida el contrato MÍNIMO de un SKILL.md para que dai lo ingiera y los asistentes lo
+// carguen: frontmatter con `name` y `description`, y que ambos sean YAML válido — si no,
+// el asistente descarta la skill entera. Devuelve null si está OK, o el motivo.
+// NO valida el contenido de la skill — eso es criterio del equipo (ADR-0013).
+export function validateSkill(md) {
+  const { name, description } = parseFrontmatter(md);
+  if (!name && !description) return "sin frontmatter (falta name y description)";
+  if (!name) return "falta 'name' en el frontmatter";
+  if (!description) return "falta 'description' en el frontmatter";
+  for (const key of ["name", "description"]) {
+    const issue = yamlScalarIssue(rawFrontmatterValue(md, key));
+    if (issue) return `'${key}' no es YAML válido: ${issue} — citá el valor con comillas dobles`;
+  }
+  return null;
 }
 
+// Los archivos de Copilot que dai generaba ANTES de que Copilot adoptara Agent Skills
+// (ADR-0014). `dai init` los borra al reencontrarlos, para que no queden duplicando
+// cada `/comando` con una copia vieja y sin templates.
+export const stalePromptFiles = (skills) => skills.map((n) => `${n}.prompt.md`);
+
 // Transforma un SKILL.md (Claude) en un SKILL.md de Cursor.
 // Conserva name/description/body y ajusta solo el frontmatter.
 export function skillToCursor(md) {
@@ -48,7 +98,17 @@ export function envFor(pm) {
     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=jira\n" +
+      "DAI_JIRA_BASE_URL=\n" +
+      "DAI_JIRA_EMAIL=\n" +
+      "DAI_JIRA_TOKEN=\n" +
+      "# La clave del PROYECTO (p. ej. PROJ), no la de un ticket (PROJ-123).\n" +
+      "DAI_JIRA_PROJECT=\n" +
+      "DAI_JIRA_ISSUETYPE=Story\n" +
+      "# Campos propios que tu Jira exige al crear. Si el archivo no existe, se ignora.\n" +
+      "DAI_JIRA_FIELDS_FILE=.dai/jira-fields.json\n" +
+      "DAI_TRACKER_URL_TEMPLATE=\n";
   }
   return head + "DAI_PM=md\nDAI_MD_US_DIR=.dai/us\n";
 }
@@ -112,7 +172,7 @@ export function reconcileGitignore(text, want) {
 // 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**. Aplica 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."
+    ? "# Instrucciones de Copilot para este repo\n\nEste repo sigue la metodología **dai**. Aplica estas reglas en todo lo que generes.\n\n> **Superficie:** las skills de dai (`.github/skills/`) se invocan con `/nombre-skill`, o\n> cuando el agente las detecta por su descripción. Funcionan en el Copilot CLI, en la app,\n> y en modo agente de VS Code / JetBrains (ADR-0014). El CLI `dai` corre en cualquier\n> terminal."
     : kind === "cursor"
       ? "# Constitución del proyecto (dai)\n\nEste repo sigue la metodología **dai**. Estas reglas gobiernan todo el trabajo.\n\n> **Superficie:** las skills de dai (`.cursor/skills/`) se invocan con `/nombre-skill`\n> o cuando el agente las detecta por descripción. 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.";
@@ -133,6 +193,8 @@ export function constitution(kind) {
 - **Verifica el comportamiento, no solo que compile:** que pase el chequeo estático o el build no prueba que funcione; ejercita el flujo real antes de darlo por hecho.
 - **La IA confirma antes de construir:** el asistente declara que entendió esta constitución y la va a obedecer antes de generar código.
 - **Secretos:** en \`.env\` (nunca commiteados). git por **SSH**, APIs por **token scopeado**.
+- **No bajes la seguridad para avanzar:** si una llamada falla por el certificado, declara la CA (\`NODE_EXTRA_CA_CERTS\`). **Nunca** \`NODE_TLS_REJECT_UNAUTHORIZED=0\`, \`verify=False\`, \`-k\` ni equivalentes: apagan la verificación de toda la conexión, y por ahí viajan los tokens.
+- **Si el CLI no llega, para y dilo:** cuando \`dai\` no cubre un caso, repórtalo — no improvises una llamada a la API por fuera. El atajo publica igual, pero rompe el link QUÉ↔CÓMO en silencio y nadie se entera hasta que la trazabilidad ya está mal.
 - **Docs vivas:** una constitución o arquitectura desactualizada es un defecto, no documentación.
 - Separa el QUÉ (funcional) del CÓMO (técnico); no mezcles.
 

package/cli/lib/http.mjs

@@ -0,0 +1,61 @@
+// dai · fetch con diagnóstico de TLS (cero dependencias).
+//
+// En una red corporativa el proxy suele interceptar TLS con una CA propia. Node NO usa
+// el trust store del sistema (trae su propia lista de CAs), así que falla justo donde el
+// navegador anda — y el error crudo de undici no dice nada de eso.
+//
+// El fix es DECLARAR la CA (NODE_EXTRA_CA_CERTS), nunca apagar la verificación:
+// NODE_TLS_REJECT_UNAUTHORIZED=0 hace que la conexión acepte CUALQUIER certificado, y
+// por acá viajan los tokens del tracker. Este módulo existe para que el que se topa con
+// el muro encuentre el camino correcto antes que el atajo peligroso.
+
+const TLS_CODES = new Set([
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "CERT_HAS_EXPIRED",
+  "ERR_TLS_CERT_ALTNAME_INVALID",
+]);
+
+// Extrae el código de error TLS de un fallo de fetch, o null si no es de TLS.
+// undici anida el error real en `cause` (a veces dos niveles).
+export function tlsErrorCode(e) {
+  for (let cur = e, depth = 0; cur && depth < 4; cur = cur.cause, depth++) {
+    const code = cur.code;
+    if (code && TLS_CODES.has(code)) return code;
+  }
+  return null;
+}
+
+export function tlsHint(host, code) {
+  return [
+    `no pude verificar el certificado TLS de ${host} (${code}).`,
+    "",
+    "  Casi siempre es un proxy corporativo que intercepta TLS con su propia CA. Node no",
+    "  usa el trust store de Windows/macOS, por eso el navegador anda y dai no.",
+    "",
+    "  Solución: exportá la CA raíz de tu empresa a un .pem y declarásela a Node:",
+    "    Windows (PowerShell):  $env:NODE_EXTRA_CA_CERTS=\"C:\\ruta\\ca-empresa.pem\"",
+    "    macOS / Linux:         export NODE_EXTRA_CA_CERTS=/ruta/ca-empresa.pem",
+    "",
+    "  NO uses NODE_TLS_REJECT_UNAUTHORIZED=0. Eso no arregla nada: apaga la verificación",
+    "  entera, y tu token del tracker viajaría aceptando cualquier certificado — incluido",
+    "  el de alguien haciéndose pasar por el tracker.",
+  ].join("\n");
+}
+
+// fetch, pero traduciendo el fallo de TLS a un error accionable.
+export async function daiFetch(url, init) {
+  try {
+    return await fetch(url, init);
+  } catch (e) {
+    const code = tlsErrorCode(e);
+    if (!code) throw e;
+    let host = String(url);
+    try { host = new URL(url).host; } catch { /* url rara: mostramos lo que vino */ }
+    const err = new Error(tlsHint(host, code));
+    err.cause = e;
+    throw err;
+  }
+}

package/cli/lib/jira-fields.mjs

@@ -0,0 +1,143 @@
+// dai · campos obligatorios propios de Jira, declarados por issuetype (cero dependencias).
+//
+// El Jira de una empresa casi siempre exige campos propios (customfield_NNNNN) que el
+// alta de un issue rechaza si faltan. Y su valor no es config fija: "Clasificación" es
+// Mejora o Corrección SEGÚN LA US. Un default fijo publicaría todas iguales — un dato
+// incorrecto en Jira, en silencio, que es peor que fallar.
+//
+// Así que se declaran acá, con nombre humano, forma y opciones válidas, y dai valida
+// ANTES de llamar a la API: un typo da un error local con la lista, no un 400 críptico.
+//
+// .dai/jira-fields.json:
+//   {
+//     "Story": {
+//       "clasificacion": {
+//         "field":   "customfield_10042",   // el id de Jira (requerido)
+//         "shape":   "select",              // opcional — ver SHAPES
+//         "default": "Mejora",           // opcional — si falta, --field es obligatorio
+//         "options": ["Mejora", "Corrección"]   // opcional — si está, dai valida contra ella
+//       }
+//     },
+//     "Epic": { … }
+//   }
+//
+// Un campo DECLARADO tiene que resolver a un valor (default o --field): se declara porque
+// Jira lo exige. Si es opcional, no lo declares.
+
+// Cómo se envuelve el valor para la API de Jira:
+//   select → { "value": X }        el caso típico de un desplegable
+//   text   → X                     texto plano
+//   multi  → [{ "value": X }, …]   lista (el valor se parte por comas)
+//   raw    → JSON.parse(X)         escape hatch: cualquier forma que Jira pida
+const SHAPES = new Set(["select", "text", "multi", "raw"]);
+
+// JSON no admite comentarios, y este archivo lo edita gente que no escribe código. Las
+// claves que empiezan con "_" son notas y se ignoran — así el molde se explica solo.
+const isNote = (k) => k.startsWith("_");
+
+// Si no se declara `shape`: con options es un desplegable; sin options, texto.
+const shapeOf = (def) => def.shape || (Array.isArray(def.options) ? "select" : "text");
+
+const optionsHint = (def) => (Array.isArray(def.options) && def.options.length ? `\n  válidas: ${def.options.join(" | ")}` : "");
+
+// Valida la estructura del archivo y lo devuelve. Los errores nombran la ruta exacta
+// (`Story.clasificacion`) para que se arregle sin adivinar.
+export function parseFieldsFile(text, path = ".dai/jira-fields.json") {
+  let json;
+  try { json = JSON.parse(text); }
+  catch (e) { throw new Error(`${path} no es JSON válido: ${e.message}`); }
+  if (json === null || typeof json !== "object" || Array.isArray(json)) {
+    throw new Error(`${path}: se espera un objeto { "<issuetype>": { "<alias>": {…} } }`);
+  }
+  for (const [type, entry] of Object.entries(json)) {
+    if (isNote(type)) continue;    // JSON no tiene comentarios: las claves _x son notas
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`${path}: '${type}' tiene que ser un objeto de campos`);
+    }
+    for (const [alias, def] of Object.entries(entry)) {
+      if (isNote(alias)) continue;
+      const at = `${path}: ${type}.${alias}`;
+      if (def === null || typeof def !== "object" || Array.isArray(def)) throw new Error(`${at} tiene que ser un objeto`);
+      if (typeof def.field !== "string" || !def.field.trim()) {
+        throw new Error(`${at}: falta 'field' (el id de Jira, p. ej. "customfield_10042")`);
+      }
+      if (def.shape !== undefined && !SHAPES.has(def.shape)) {
+        throw new Error(`${at}: shape '${def.shape}' desconocido (${[...SHAPES].join(" | ")})`);
+      }
+      if (def.options !== undefined && !Array.isArray(def.options)) {
+        throw new Error(`${at}: 'options' tiene que ser una lista`);
+      }
+    }
+  }
+  return json;
+}
+
+// `--field alias=valor` (repetible) → { alias: "valor" }.
+export function parseFieldOverrides(input) {
+  const list = input === undefined ? [] : Array.isArray(input) ? input : [input];
+  const out = {};
+  for (const raw of list) {
+    if (typeof raw !== "string") throw new Error("--field espera 'alias=valor'");
+    const i = raw.indexOf("=");
+    if (i <= 0) throw new Error(`--field espera 'alias=valor' (recibí: '${raw}')`);
+    out[raw.slice(0, i).trim()] = raw.slice(i + 1);
+  }
+  return out;
+}
+
+// Los campos declarados para un issuetype. Exacto primero, después sin distinguir
+// mayúsculas ("story" encuentra "Story"), y {} si no hay nada declarado.
+function specFor(spec, issuetype) {
+  if (!spec || typeof spec !== "object") return {};
+  const lower = String(issuetype).toLowerCase();
+  const hit = Object.keys(spec).find((k) => !isNote(k) && (k === issuetype || k.toLowerCase() === lower));
+  if (!hit) return {};
+  return Object.fromEntries(Object.entries(spec[hit]).filter(([alias]) => !isNote(alias)));
+}
+
+function checkOptions(def, alias, value) {
+  if (!Array.isArray(def.options) || def.options.length === 0) return;
+  const values = shapeOf(def) === "multi" ? value.split(",").map((s) => s.trim()).filter(Boolean) : [value];
+  for (const v of values) {
+    if (!def.options.includes(v)) throw new Error(`'${v}' no es opción de '${alias}'.${optionsHint(def)}`);
+  }
+}
+
+function castValue(def, alias, value) {
+  switch (shapeOf(def)) {
+    case "select": return { value };
+    case "text":   return value;
+    case "multi":  return value.split(",").map((s) => s.trim()).filter(Boolean).map((v) => ({ value: v }));
+    case "raw":
+      try { return JSON.parse(value); }
+      catch (e) { throw new Error(`--field ${alias}: shape 'raw' espera JSON válido — ${e.message}`); }
+    default: throw new Error(`shape '${def.shape}' desconocido en '${alias}'`);
+  }
+}
+
+// Resuelve los campos declarados para este issuetype al payload que espera la API.
+// Lanza (sin tocar la red) si un override no existe, si falta un valor obligatorio,
+// o si el valor no está entre las opciones válidas.
+export function resolveJiraFields({ spec, issuetype, overrides = {} }) {
+  const entry = specFor(spec, issuetype);
+  const aliases = Object.keys(entry);
+
+  for (const a of Object.keys(overrides)) {
+    if (Object.prototype.hasOwnProperty.call(entry, a)) continue;
+    throw new Error(aliases.length
+      ? `--field '${a}' no está declarado para el issuetype '${issuetype}'.\n  declarados: ${aliases.join(" | ")}`
+      : `--field '${a}': no hay campos declarados para el issuetype '${issuetype}' (revisá el archivo de campos).`);
+  }
+
+  const out = {};
+  for (const [alias, def] of Object.entries(entry)) {
+    const raw = Object.prototype.hasOwnProperty.call(overrides, alias) ? overrides[alias] : def.default;
+    if (raw === undefined) {
+      throw new Error(`falta el valor de '${alias}' (lo exige el issuetype '${issuetype}').\n  pasalo con:  --field ${alias}=<valor>${optionsHint(def)}`);
+    }
+    const value = String(raw);
+    checkOptions(def, alias, value);
+    out[def.field] = castValue(def, alias, value);
+  }
+  return out;
+}

package/cli/lib/pm-jira.mjs

@@ -7,9 +7,30 @@
 // hasher encuentre "## Criterios de aceptación"); al ESCRIBIR el stamp, componemos ADF.
 
 import { parseUS } from "./us.mjs";
+import { daiFetch } from "./http.mjs";
 
 const trim = (b) => String(b || "").replace(/\/+$/, "");
 
+// La clave del PROYECTO (PROJ), no la de un ticket (PROJ-42). Confundirlas es el
+// 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).");
+  const k = String(key).trim();
+  const m = k.match(/^([A-Za-z][A-Za-z0-9_]*)-\d+$/);
+  if (m) {
+    throw new Error(
+      `DAI_JIRA_PROJECT='${k}' es la clave de un ticket, no la del proyecto.\n` +
+      `  Usá solo la parte de adelante:  DAI_JIRA_PROJECT=${m[1]}\n` +
+      `  Si lo que querías era colgar la US de esa épica:  dai publish <us.md> --parent ${k}`,
+    );
+  }
+  if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(k)) {
+    throw new Error(`DAI_JIRA_PROJECT='${k}' no parece una clave de proyecto (letras y números, empezando por letra — p. ej. PROJ).`);
+  }
+  return k;
+}
+
 export function jiraIssueUrl(base, id) {
   return `${trim(base)}/rest/api/3/issue/${encodeURIComponent(id)}?fields=summary,description`;
 }
@@ -85,37 +106,56 @@ export function renderCoverageAdf(id, r) {
   return { type: "doc", version: 1, content };
 }
 
+// Un 400 al crear casi siempre es un campo obligatorio del proyecto que no mandamos.
+// El cuerpo de Jira nombra el customfield_NNNNN pero no dice qué hacer: lo decimos acá.
+function createHint(status) {
+  if (status !== 400) return "";
+  return "\n\n  Si el error nombra un 'customfield_NNNNN', tu proyecto exige un campo propio.\n" +
+         "  Declaralo en .dai/jira-fields.json y volvé a publicar — no hace falta improvisar\n" +
+         "  una llamada a mano:\n" +
+         '    { "Story": { "clasificacion": { "field": "customfield_NNNNN",\n' +
+         '                                    "options": ["Mejora", "Corrección"] } } }\n' +
+         "    dai publish <us.md> --field clasificacion=Corrección";
+}
+
 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) });
+      const res = await daiFetch(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), {
+      const res = await daiFetch(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`, {
+    // `fields` son los campos propios del proyecto ya resueltos (ver jira-fields.mjs);
+    // `parent` cuelga la US de su épica. Ambos son opcionales: un Jira sin campos
+    // obligatorios sigue publicando igual que antes.
+    async createUS({ title, descriptionMarkdown, parent, issuetype, project, fields }) {
+      const key = assertProjectKey(project || env.DAI_JIRA_PROJECT);
+      const type = issuetype || env.DAI_JIRA_ISSUETYPE || "Story";
+      const payload = {
+        project: { key },
+        issuetype: { name: type },
+        summary: title,
+        description: markdownToAdf(descriptionMarkdown),
+        ...(fields || {}),
+      };
+      if (parent) payload.parent = { key: String(parent).trim() };
+      const res = await daiFetch(`${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),
-        } }),
+        body: JSON.stringify({ fields: payload }),
       });
-      if (!res.ok) throw new Error(`jira ${res.status}: ${await res.text()}`);
+      if (!res.ok) throw new Error(`jira ${res.status}: ${await res.text()}${createHint(res.status)}`);
       const j = await res.json();
       return { id: j.key, url: `${trim(base)}/browse/${j.key}` };
     },

package/cli/lib/skills-source.mjs

@@ -0,0 +1,26 @@
+// dai · resolución de una fuente de skills externas (`dai skills install --from`).
+// Núcleo puro (sin fs ni red): clasifica el argumento en git URL o path local y
+// separa el ref (`#branch`/`#tag`). Ver ADR-0013.
+
+// Devuelve { type: 'git'|'path', location, ref }.
+//   git   → URL clonable. `host/org/repo` (sin esquema) se normaliza a https://.
+//   path  → ruta local (relativa o absoluta). El `ref` se ignora aguas abajo.
+//   ref   → lo que va después de '#', o null.
+export function parseSource(src) {
+  const raw = String(src ?? "").trim();
+  if (!raw) throw new Error("fuente vacía (pasá un git URL o un path)");
+
+  // Separar el ref (#branch/tag). El scp de git (git@host:org/repo) no usa '#'.
+  let ref = null, loc = raw;
+  const hash = raw.lastIndexOf("#");
+  if (hash > 0) { ref = raw.slice(hash + 1) || null; loc = raw.slice(0, hash); }
+
+  // Path local explícito (./ ../ / ~/).
+  if (/^(\.\.?\/|\/|~\/)/.test(loc)) return { type: "path", location: loc, ref };
+  // git por sintaxis de URL (https, ssh, scp git@host:…).
+  if (/^(https?:\/\/|ssh:\/\/|git@|[\w.-]+@)/.test(loc)) return { type: "git", location: loc, ref };
+  // host/org/repo (p.ej. github.com/org/skills) → git https.
+  if (/^[\w.-]+\.[\w.-]+\/.+/.test(loc)) return { type: "git", location: "https://" + loc, ref };
+  // Resto: path local relativo sin ./.
+  return { type: "path", location: loc, ref };
+}

package/docs/adr/0013-skills-externas-install-from.md

@@ -0,0 +1,56 @@
+# ADR-0013 — `dai skills install --from` (skills externas por-stack)
+
+- **Estado:** aceptado
+- **Fecha:** 2026-07-14
+- **Decide:** lead / arquitecto de la metodología
+
+## Contexto
+
+dai distribuye **sus** skills (las bundleadas: `grill-*`, `link-us`, `tdd`, …) e
+instala/convierte para Claude, Cursor y Copilot. Pero los equipos tienen skills
+**propias de su stack** (.NET, Java, Rust, …) que hoy no tienen lugar: o las copian
+a mano por repo (duplicación, sin conversión a los 3 asistentes), o las meten en el
+paquete dai — que **rompe el ADN**: dai es agnóstico del stack, opina solo en su
+dominio (trazabilidad/distribución), no sobre *qué* dicen tus skills.
+
+Falta una forma de que dai **convierta e instale** skills externas, sin volverse
+dueño ni gatekeeper de ellas.
+
+## Decisión
+
+Agregamos **`dai skills install --from <git-url|path>[#ref]`**: instala skills
+**externas** desde un repo/dir (con estructura `skills/<nombre>/SKILL.md`, la misma
+de dai), **convertidas para los 3 asistentes** (Claude copia · Cursor `skillToCursor`
+· Copilot `skillToPrompt` → `.github/prompts/`).
+
+- **`dai skills` es el namespace canónico** de las operaciones de skills, consistente
+  con `dai forge <verb>`. `dai skills install` (sin `--from`) instala las de dai;
+  **`dai install` queda como alias** silencioso (backward-compatible).
+- **Self-service, one-off, sin registro.** No hay autorización central ni persistencia:
+  no existe `.dai/sources`, dai **no lleva registro** de qué repos usan skills externas.
+  El equipo las suma **bajo su propio criterio**.
+- **`dai sync` NO las toca** — sigue siendo **solo** de las skills de dai. Si el equipo
+  actualiza sus skills, re-corre `--from`.
+- **Colisión** con una skill built-in de dai → **warn + skip** (no se pisa la
+  metodología; renombran, p. ej. `tdd-dotnet`).
+
+## Consecuencias
+
+- **Más fácil:** cada equipo suma sus skills por-stack sin tocar dai ni pedir permiso,
+  y las escribe **una vez** (dai las sirve a Claude/Cursor/Copilot). El namespace
+  `dai skills` deja lugar a crecer (`skills list`, …) sin comandos sueltos.
+- **Se acepta pagar:** es **one-off** (dai no mantiene esas skills al día; re-corrés
+  `--from`). **Sin registro** → dai no sabe qué repos tienen skills externas, a
+  propósito: cero gatekeeping, bajo riesgo del equipo. Las fuentes remotas dependen de
+  git/red, y la **auth se delega en git** (público sin más; privado por SSH o credential
+  helper — dai no autentica): *si podés `git clone` la fuente, dai instala desde ahí*.
+
+## Alternativas consideradas
+
+- **Persistido (`.dai/sources`) + integrado a `dai sync`** — descartado: obliga a dai a
+  **registrar y mantener** fuentes externas (gatekeeping que el equipo no quiere), y
+  acopla `dai sync` —que debe ser solo de dai— a repos ajenos.
+- **Meter las skills de stack en el paquete dai** — descartado: rompe el ADN (dai
+  agnóstico del stack).
+- **Comando suelto `dai install --from` sin namespace** — descartado: `dai skills <verb>`
+  es más claro y consistente con `dai forge <verb>`; `dai install` queda como alias.

package/docs/adr/0014-copilot-agent-skills.md

@@ -0,0 +1,99 @@
+# ADR-0014 — Copilot lee SKILL.md nativo (Agent Skills)
+
+- **Estado:** aceptado
+- **Fecha:** 2026-07-15
+- **Decide:** lead / arquitecto de la metodología
+- **Modifica:** [ADR-0002](0002-agnostico-del-asistente.md) (la capa 3 del adaptador de Copilot)
+
+## Contexto
+
+La ADR-0002 definió tres capas: contenido portable (los `SKILL.md`), un CLI determinista
+y **adaptadores generados** por asistente. Para Copilot ese adaptador era
+`skillToPrompt()` → `.github/prompts/<nombre>.prompt.md`, porque los prompt files eran
+el único mecanismo que Copilot tenía. De ahí salía su consecuencia registrada: *"el
+analista sin IDE cierra con Claude Desktop"*, ya que los prompt files son solo-IDE.
+
+**Eso dejó de ser cierto.** En diciembre de 2025 GitHub adoptó **Agent Skills**, el
+estándar abierto de `SKILL.md` — el mismo formato que dai ya usa como fuente. Hoy la
+[documentación oficial](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)
+dice, literal:
+
+> "Agent skills work with Copilot cloud agent, Copilot code review, the GitHub Copilot
+> CLI, the GitHub Copilot app, and agent mode in Visual Studio Code and JetBrains IDEs."
+
+Con rutas estándar: **`.github/skills`**, `.claude/skills` o `.agents/skills` por repo;
+**`~/.copilot/skills`** o `~/.agents/skills` personales. El frontmatter requerido es
+`name` + `description` — exactamente lo que `validateSkill()` ya exige.
+
+Lo descubrimos con un analista funcional real que no lograba que Copilot viera sus
+skills. Tres fallas encadenadas, todas nuestras:
+
+1. **`dai skills install` las dejaba en `~/.claude/skills`.** Esa ruta es válida como
+   skill personal *en VS Code*, pero **no** en el Copilot CLI ni en la app, que solo
+   miran `~/.copilot/skills`. El CLI encima warneaba *"Copilot no tiene skills
+   instalables"* — falso desde diciembre.
+2. **`skillToPrompt()` perdía los `templates/`.** Solo leía el `SKILL.md`, así que
+   `grill-user-story/templates/user-story.md` nunca viajaba y el prompt quedaba con un
+   link roto. Copilot, en cambio, *"automatically discovers all of the files in the
+   skill's directory"*.
+3. **La conversión borraba el `name:`** (había un test afirmándolo como correcto), que
+   en Agent Skills es **requerido** y es lo que define el `/comando`.
+
+## Decisión
+
+**El adaptador de Copilot se elimina: dai le entrega el `SKILL.md` tal cual.**
+
+- **`dai init --for copilot`** → `.github/skills/<nombre>/` como **copia cruda** (igual
+  que Claude), con sus `templates/` adentro. Ya no genera `.github/prompts/`.
+- **`dai skills install --for copilot`** → `~/.copilot/skills/` (global) o
+  `.github/skills/` (local). Copilot **sí** tiene skills instalables.
+- **`skillToPrompt()` se borra.** Queda `stalePromptFiles()`: `dai init` **elimina los
+  `.prompt.md` que generó dai** en versiones previas — si no, cada `/comando` aparecería
+  duplicado, con una copia vieja y sin templates. Solo borra los suyos; los prompt files
+  propios del equipo no se tocan.
+- **`dai doctor` chequea Copilot** y, sobre todo, **solo reporta los asistentes que el
+  repo realmente usa**. Antes listaba los tres siempre: quien configuraba uno veía 14
+  warnings de los otros dos y leía "está todo roto" cuando estaba todo bien.
+- **Cada asistente conserva SU directorio** (`.claude/skills`, `.github/skills`,
+  `.cursor/skills`), aunque Copilot sepa leer los tres. La simetría es predecible y
+  mantiene la capa 3 de la ADR-0002 donde sigue haciendo falta (Cursor).
+
+## Consecuencias
+
+- **La conclusión de la ADR-0002 sobre el analista sin IDE queda revocada.** Un
+  funcional puede cerrar el ciclo con **Copilot CLI o la app de Copilot**, sin VS Code.
+  La tabla del README se corrige: la única superficie sin skills es el chat de
+  github.com.
+- **Los `templates/` de las skills llegan a Copilot por primera vez.**
+- **El frontmatter pasó a tener un lector estricto, y eso destapó un defecto viejo.**
+  Nuestro `parseFrontmatter` es un regex, no YAML: se tragaba cualquier cosa. Y la
+  conversión que borramos hacía `JSON.stringify(description)`, que citaba el valor —
+  o sea que **estaba tapando el bug sin querer**. Al entregar el `SKILL.md` crudo, lo
+  lee un parser YAML real, y `doc-to-backlog` y `grill-epic` **fallaron al cargar**: sus
+  descripciones tenían un `: ` suelto (*"…épicas finales: extrae…"*, *"…nivel
+  funcional/alcance: define…"*) que YAML interpreta como el arranque de un mapa. Las dos
+  skills que más necesita un analista funcional, invisibles.
+  Se citan las descripciones de las 7, y **`validateSkill` ahora valida que `name` y
+  `description` sean escalares YAML válidos** — el molde de `templates/skill.md` también
+  cita por defecto. La lección general: **un adaptador que "arregla" el input esconde el
+  defecto en la fuente**. Mientras convertíamos, el `SKILL.md` inválido era nuestro
+  secreto; entregándolo crudo, el contrato es real y hay que cumplirlo.
+- **Menos código, no más:** se borra una transformación y su test. La capa 3 de la
+  ADR-0002 sigue siendo la decisión correcta — lo que cambió es que Copilot dejó de
+  necesitarla, no que la idea estuviera mal. Cuando el formato de una skill es un
+  estándar abierto, el mejor adaptador es ninguno.
+- **Riesgo asumido:** un repo con `--for all` tendrá el mismo skill en `.claude/skills`
+  y `.github/skills`, y Copilot mira ambos. El estándar exige `name` único, así que
+  esperamos deduplicación por nombre; si en la práctica duplica, se resuelve entonces.
+- **Migración:** `dai init` es idempotente y limpia solo. Un repo viejo se pone al día
+  con `dai init --for copilot` (o `dai sync`).
+
+## Alternativas descartadas
+
+- **Mantener los `.prompt.md` "por compatibilidad".** Duplicaría cada `/comando` con una
+  copia peor. Copilot soporta skills en todas sus superficies desde enero; sostener el
+  camino viejo es sostener el bug.
+- **Escribir solo `.claude/skills` y que Copilot lo levante** (lo hace: *"if you've
+  already set up skills for Claude Code in the `.claude/skills` directory, Copilot will
+  pick them up automatically"*). Rompe la simetría del adaptador y sorprende: pedir
+  `--for copilot` y no tener nada de Copilot en el repo es un mal contrato.