agentic-workflow-manager 3.13.4 → 3.13.5

package/dist/src/core/discovery.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.matchFrontmatterBlock = matchFrontmatterBlock;
+exports.findFrontmatterDescription = exports.isBlockScalarHeader = exports.readFrontmatterDescription = exports.matchFrontmatterBlock = void 0;
 exports.readArtifactDescription = readArtifactDescription;
 exports.discoverSkills = discoverSkills;
 exports.discoverWorkflows = discoverWorkflows;
@@ -12,31 +12,23 @@ exports.discoverAgents = discoverAgents;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const registries_1 = require("./registries");
-/** Extracts the raw frontmatter text (between the --- delimiters), or null if the block is missing/malformed. CRLF-tolerant. */
-function matchFrontmatterBlock(raw) {
-    const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-    return fmMatch ? fmMatch[1] : null;
-}
+// El parseo de frontmatter vive en el modulo HOJA `core/frontmatter.ts`
+// (sin imports, para que consumidores puros como export/transform.ts no
+// arrastren fs/git por transitividad). Se re-exporta aca porque este modulo
+// ya era el punto de entrada historico para esos helpers.
+var frontmatter_1 = require("./frontmatter");
+Object.defineProperty(exports, "matchFrontmatterBlock", { enumerable: true, get: function () { return frontmatter_1.matchFrontmatterBlock; } });
+Object.defineProperty(exports, "readFrontmatterDescription", { enumerable: true, get: function () { return frontmatter_1.readFrontmatterDescription; } });
+Object.defineProperty(exports, "isBlockScalarHeader", { enumerable: true, get: function () { return frontmatter_1.isBlockScalarHeader; } });
+Object.defineProperty(exports, "findFrontmatterDescription", { enumerable: true, get: function () { return frontmatter_1.findFrontmatterDescription; } });
+const frontmatter_2 = require("./frontmatter");
 function readArtifactDescription(filePath) {
     try {
         const raw = fs_1.default.readFileSync(filePath, 'utf-8');
-        const frontmatter = matchFrontmatterBlock(raw);
+        const frontmatter = (0, frontmatter_2.matchFrontmatterBlock)(raw);
         if (frontmatter === null)
             return '';
-        const line = frontmatter
-            .split(/\r?\n/)
-            .find((l) => /^description\s*:/.test(l));
-        if (!line)
-            return '';
-        let val = line.replace(/^description\s*:/, '').trim();
-        if ((val.startsWith('"') && val.endsWith('"')) ||
-            (val.startsWith("'") && val.endsWith("'"))) {
-            val = val.slice(1, -1);
-        }
-        const BLOCK_INDICATORS = new Set(['>-', '>', '|-', '|', '>+', '|+']);
-        if (BLOCK_INDICATORS.has(val.trim()))
-            return '';
-        return val.trim();
+        return (0, frontmatter_2.readFrontmatterDescription)(frontmatter);
     }
     catch {
         return '';

package/dist/src/core/export/transform.js

@@ -7,7 +7,10 @@ exports.claudeAiTransform = claudeAiTransform;
 //
 // Transform mecánico claude.ai (R3.1): función pura string → string.
 // Frontmatter line-based plano (los SKILL.md del baseline usan claves de una
-// línea) — sin parser YAML a propósito (YAGNI, cero deps).
+// línea) — sin parser YAML a propósito (YAGNI, cero deps). La única forma
+// multilínea soportada es el block scalar de `description:`, resuelto vía la
+// función compartida de discovery.ts (ver claudeAiTransform).
+const frontmatter_1 = require("../frontmatter");
 const DEFERENCE_LINE = (skillName) => `In environments with AWM installed (Claude Code), defer to the registry's ${skillName} skill — this port is for environments without filesystem access.`;
 exports.DEFERENCE_LINE = DEFERENCE_LINE;
 // Paths intra-registry: resuelven en Claude Code (donde el registry está en
@@ -73,34 +76,36 @@ function claudeAiTransform(skillMd, skillName) {
     const body = skillMd.slice(end + endMatch[0].length);
     const fmLines = skillMd.slice(startLen, end).split(/\r?\n/)
         .filter((l) => !/^(version|portable):/.test(l));
-    const descIdx = fmLines.findIndex((l) => /^description:/.test(l));
-    if (descIdx === -1) {
+    // UN SOLO camino para todas las formas de `description`. Antes habia uno por
+    // forma (plano / entrecomillado / bloque) y cada vez que el LECTOR aprendia
+    // una forma nueva, el ESCRITOR de aca quedaba atras — la divergencia exacta
+    // que este modulo dice cerrar. Casos reales que produjo esa asimetria:
+    //  - escalar plano multilinea: la deference line se insertaba en la primera
+    //    linea y la continuacion quedaba huerfana debajo, o sea la frase de
+    //    deference terminaba enterrada en el medio de la descripcion;
+    //  - escalar plano con ` # comentario` final: la deference line se anexaba
+    //    DESPUES del `#`, o sea YAML se la comia entera como comentario y el
+    //    artefacto exportado perdia en silencio la unica frase que este
+    //    transform existe para agregar.
+    // Ahora se resuelve el campo con la funcion compartida, se reemplaza su
+    // extension COMPLETA (startLine..endLine) y se emite siempre un escalar
+    // double-quoted via JSON.stringify — superset valido de YAML que cubre
+    // comillas, `:`, `#` y los `\n` de un literal `|` sin decidir estilo.
+    const field = (0, frontmatter_1.findFrontmatterDescription)(fmLines.join('\n'));
+    if (field.startLine === -1) {
         throw new Error('frontmatter has no description field');
     }
-    const descLine = fmLines[descIdx];
-    const value = descLine.slice('description:'.length).trim();
-    if (value === '' || value === '>' || value === '|' || value.startsWith('>') || value.startsWith('|')) {
-        throw new Error('description must be single-line (block scalars are not supported by the export transform)');
+    const rawValue = fmLines[field.startLine].replace(/^description\s*:/, '').trim();
+    // Empieza con `>`/`|` pero no es un indicador bien formado (ej. `>-basura`):
+    // YAML mismo lo rechaza. Fallar explicito en vez de publicar basura.
+    if (/^[>|]/.test(rawValue) && !(0, frontmatter_1.isBlockScalarHeader)(rawValue)) {
+        throw new Error(`malformed block scalar indicator in description: ${rawValue}`);
     }
-    const deference = (0, exports.DEFERENCE_LINE)(skillName);
-    // Quote-style detection mirrors readArtifactDescription in discovery.ts: both
-    // single- and double-quoted scalars are first-class, and we work off the
-    // trimmed value so trailing whitespace after a closing quote doesn't fool us.
-    const isDoubleQuoted = value.length >= 2 && value.startsWith('"') && value.endsWith('"');
-    const isSingleQuoted = value.length >= 2 && value.startsWith("'") && value.endsWith("'");
-    if ((value.startsWith('"') || value.startsWith("'")) && !isDoubleQuoted && !isSingleQuoted) {
-        throw new Error('description has trailing content after its closing quote (e.g. an inline comment) — not supported by the export transform; remove the comment or use a port.claude-ai.md override');
+    if (!field.value) {
+        throw new Error((0, frontmatter_1.isBlockScalarHeader)(rawValue) ? 'description block scalar has no content' : 'description is empty');
     }
-    // YAML single-quoted scalars escape a literal ' by doubling it (''); the
-    // deference text ("...registry's..." — see DEFERENCE_LINE) contains an
-    // apostrophe, so it must be escaped before splicing into a single-quoted
-    // description or it would prematurely close the YAML string.
-    const newValue = isDoubleQuoted
-        ? `${value.slice(0, -1)} ${deference}"`
-        : isSingleQuoted
-            ? `${value.slice(0, -1)} ${deference.replace(/'/g, "''")}'`
-            : `${value} ${deference}`;
-    fmLines[descIdx] = `description: ${newValue}`;
+    const merged = JSON.stringify(`${field.value} ${(0, exports.DEFERENCE_LINE)(skillName)}`);
+    fmLines.splice(field.startLine, field.endLine - field.startLine + 1, `description: ${merged}`);
     // Solo el body: el frontmatter ya se editó arriba y sus campos no son prosa
     // navegable (R2.4).
     return `---\n${fmLines.join('\n')}\n---\n${stripIntraRegistryPaths(body)}`;

package/dist/src/core/frontmatter.js

@@ -0,0 +1,223 @@
+"use strict";
+// src/core/frontmatter.ts
+//
+// Modulo HOJA: sin imports. Es la unica fuente de verdad para leer el
+// frontmatter YAML de un artefacto (SKILL.md, agents/*.md, workflows/*.md).
+//
+// Por que hoja: sus consumidores incluyen `core/export/transform.ts`, que se
+// documenta como funcion pura string -> string sin dependencias. Si esto
+// viviera en `discovery.ts` (que importa `registries.ts`, y este a su vez
+// resuelve `awmHome()` y carga `simple-git` en tiempo de import), un modulo
+// puro terminaria arrastrando la capa de fs/git por transitividad.
+//
+// Por que existe: el frontmatter se parseaba a mano en CUATRO lugares, cada
+// uno con su propia copia incompleta. Un block scalar YAML valido
+// (`description: >-`, con el texto en las lineas indentadas siguientes)
+// degradaba en silencio en discovery, crasheaba `awm add -a cursor|copilot`,
+// abortaba `awm export <bundle>` entero y rompia `awm add -a codex`. La
+// semantica de aca se verifica contra js-yaml (parser real) en
+// tests/core/frontmatter-description-vs-yaml.test.ts — no contra valores
+// esperados escritos a mano, que pueden envejecer hacia la expectativa
+// equivocada.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchFrontmatterBlock = matchFrontmatterBlock;
+exports.isBlockScalarHeader = isBlockScalarHeader;
+exports.findFrontmatterDescription = findFrontmatterDescription;
+exports.readFrontmatterDescription = readFrontmatterDescription;
+/** Texto crudo del frontmatter (entre los delimitadores `---`), o null si el
+ *  bloque falta o esta mal formado. Tolera CRLF. */
+function matchFrontmatterBlock(raw) {
+    const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    return fmMatch ? fmMatch[1] : null;
+}
+/** Indicador de block scalar en la linea de la clave: estilo (`>` folded /
+ *  `|` literal) + chomping opcional (`-`/`+`) + indentacion explicita opcional
+ *  + comentario final opcional. Detalles verificados contra js-yaml:
+ *   - la indentacion explicita es UN digito 1-9 (ni `0` ni `10`);
+ *   - `>- # nota` es valido y su bloque se lee normal;
+ *   - `>-basura` NO es valido y aca tampoco matchea. */
+const BLOCK_SCALAR_HEADER = /^([>|])(?:([+-])?([1-9])?|([1-9])?([+-])?)(?:\s+#.*)?$/;
+/** ¿El valor de la linea de la clave es un indicador de block scalar?
+ *  Cualquier caller que RAMIFIQUE sobre "esto es un bloque" debe usar esta
+ *  funcion, nunca una aproximacion propia: una guarda por prefijo (`/^[>|]/`)
+ *  y un resolver por match completo se desincronizan, y en ese hueco el
+ *  escritor borro contenido real creyendo que resolvia un bloque. */
+function isBlockScalarHeader(value) {
+    return BLOCK_SCALAR_HEADER.test(value.trim());
+}
+/** Indice de la comilla que CIERRA el escalar que empieza en la posicion 0, o
+ *  -1 si no cierra. Cada estilo escapa distinto: en single-quoted un `''` es
+ *  un apostrofe literal (no un cierre); en double-quoted un `\"` es una
+ *  comilla literal. */
+function findClosingQuote(value, quote) {
+    for (let i = 1; i < value.length; i++) {
+        if (quote === '"' && value[i] === '\\') {
+            i++;
+            continue;
+        }
+        if (value[i] !== quote)
+            continue;
+        if (quote === "'" && value[i + 1] === "'") {
+            i++;
+            continue;
+        }
+        return i;
+    }
+    return -1;
+}
+function foldBlock(stripped, isLiteral) {
+    if (isLiteral)
+        return stripped.join('\n').trim();
+    // Folded (`>`): las lineas al nivel base del bloque se pliegan entre si con
+    // UN espacio; una linea MAS indentada no se pliega (conserva su salto y su
+    // sangria — la regla que permite incrustar una lista dentro de un folded);
+    // y k lineas en blanco consecutivas producen k saltos de linea.
+    // Ojo: NO se hace trim por linea — YAML conserva los espacios finales de
+    // cada linea y el plegado agrega el suyo encima.
+    let out = '';
+    let prevLiteral = false;
+    let started = false;
+    let blanks = 0;
+    for (const line of stripped) {
+        if (line === '') {
+            blanks++;
+            continue;
+        }
+        const literal = /^[ \t]/.test(line);
+        if (!started) {
+            out = line;
+            started = true;
+            prevLiteral = literal;
+            blanks = 0;
+            continue;
+        }
+        if (blanks > 0) {
+            out += '\n'.repeat(blanks);
+            blanks = 0;
+        }
+        else if (literal || prevLiteral)
+            out += '\n';
+        else
+            out += ' ';
+        out += line;
+        prevLiteral = literal;
+    }
+    return out.trim();
+}
+/**
+ * Localiza y RESUELVE el campo `description` de un bloque de frontmatter,
+ * devolviendo tambien la extension exacta que ocupa (para que un escritor
+ * pueda reemplazarlo entero).
+ *
+ * Formas soportadas, todas contrastadas contra js-yaml: escalar plano (de una
+ * o varias lineas), escalar entrecomillado (simple y doble, con su escape
+ * propio deshecho), y block scalar folded/literal con chomping e indentacion
+ * explicita.
+ */
+function findFrontmatterDescription(frontmatter) {
+    const lines = frontmatter.split(/\r?\n/);
+    // Ancla en COLUMNA 0 a proposito: `description` en un frontmatter es
+    // siempre clave de nivel superior. Un `^\s*` haria ganar a un
+    // `description:` INDENTADO — anidado en otro mapa, o una linea de
+    // CONTENIDO de otro block scalar que casualmente empiece asi.
+    const startLine = lines.findIndex((l) => /^description\s*:/.test(l));
+    if (startLine === -1)
+        return { value: '', startLine: -1, endLine: -1 };
+    const raw = lines[startLine].replace(/^description\s*:/, '').trim();
+    if (isBlockScalarHeader(raw)) {
+        const isLiteral = raw.trim().startsWith('|');
+        // El bloque son las lineas ESTRICTAMENTE indentadas respecto de la
+        // clave (columna 0). Las lineas en blanco no lo cortan: pertenecen a el.
+        const block = [];
+        let last = startLine;
+        for (let i = startLine + 1; i < lines.length; i++) {
+            if (lines[i].trim() === '') {
+                block.push(lines[i]);
+                continue;
+            }
+            if (!/^[ \t]/.test(lines[i]))
+                break;
+            block.push(lines[i]);
+            last = i;
+        }
+        while (block.length > 0 && block[block.length - 1].trim() === '')
+            block.pop();
+        const first = block.find((l) => l.trim() !== '');
+        if (first === undefined)
+            return { value: '', startLine, endLine: startLine };
+        const declared = raw.match(/[1-9]/);
+        const blockIndent = declared !== null ? Number(declared[0]) : first.match(/^[ \t]*/)[0].length;
+        // Una linea con MENOS indentacion que el bloque es YAML invalido
+        // (js-yaml lanza "bad indentation"). Cortar a ciegas con slice()
+        // comeria caracteres reales: preferimos no inventar un valor.
+        if (block.some((l) => l.trim() !== '' && l.match(/^[ \t]*/)[0].length < blockIndent)) {
+            return { value: '', startLine, endLine: last };
+        }
+        const stripped = block.map((l) => l.slice(blockIndent));
+        return { value: foldBlock(stripped, isLiteral), startLine, endLine: last };
+    }
+    // Empieza con `>`/`|` pero NO es un indicador bien formado (`>0`, `>12`,
+    // `>-basura`): YAML lo rechaza. Devolver '' hace que los consumidores
+    // fallen fuerte (throw en parseSkillSource / claudeAiTransform) en vez de
+    // caer al camino de escalar plano de abajo, que publicaria el indicador
+    // mismo como si fuera la descripcion.
+    if (/^[>|]/.test(raw))
+        return { value: '', startLine, endLine: startLine };
+    // Continuacion multilinea. Aplica a DOS formas, y ambas la necesitan:
+    //  - escalar plano (`description: primera` + lineas indentadas), que YAML
+    //    pliega con espacios igual que un `>`;
+    //  - escalar ENTRECOMILLADO cuya comilla de cierre esta en una linea
+    //    posterior (`description: "hola` / `  mundo"`), que sin esto devolvia
+    //    `"hola` — con la comilla de apertura pegada — como descripcion.
+    // Sin juntar las lineas primero, del lado escritor ademas quedaban
+    // huerfanas en la salida exportada.
+    let endLine = startLine;
+    let value = raw;
+    const opensUnclosedQuote = /^['"]/.test(raw) && findClosingQuote(raw, raw[0]) === -1;
+    if (raw !== '' && (!/^['"]/.test(raw) || opensUnclosedQuote)) {
+        const cont = [];
+        for (let i = startLine + 1; i < lines.length; i++) {
+            if (lines[i].trim() === '')
+                break;
+            if (!/^[ \t]/.test(lines[i]))
+                break;
+            cont.push(lines[i].trim());
+            endLine = i;
+        }
+        if (cont.length > 0)
+            value = [raw, ...cont].join(' ');
+    }
+    // Escalares entrecomillados. Dos cosas que no alcanzan por separado:
+    //  1. Hay que ENCONTRAR la comilla de cierre real antes de mirar el resto:
+    //     lo que sigue a esa comilla es un comentario, no parte del valor.
+    //     Comparar con `endsWith` fallaba justo cuando habia comentario
+    //     (`description: "x" # nota` devolvia `"x"` CON las comillas literales,
+    //     mientras js-yaml devuelve `x`).
+    //  2. Hay que deshacer el escape propio de cada estilo: single-quoted
+    //     duplica el apostrofe (`''`); double-quoted es superset de la string
+    //     JSON, asi que JSON.parse resuelve \n, \t, \", \\ y \uXXXX.
+    const quote = value[0];
+    if (quote === "'" || quote === '"') {
+        const close = findClosingQuote(value, quote);
+        if (close !== -1) {
+            const scalar = value.slice(0, close + 1);
+            if (quote === "'") {
+                return { value: scalar.slice(1, -1).replace(/''/g, "'").trim(), startLine, endLine };
+            }
+            try {
+                return { value: String(JSON.parse(scalar)).trim(), startLine, endLine };
+            }
+            catch {
+                return { value: scalar.slice(1, -1).trim(), startLine, endLine };
+            }
+        }
+    }
+    // Escalar plano: un `#` PRECEDIDO DE ESPACIO abre un comentario y no forma
+    // parte del valor (un `#` pegado a texto, como en `C#`, si). Dentro de
+    // comillas el `#` es literal, y esas ramas ya retornaron.
+    return { value: value.replace(/\s+#.*$/, '').trim(), startLine, endLine };
+}
+/** Azucar para el caso comun: solo el valor resuelto de `description`. */
+function readFrontmatterDescription(frontmatter) {
+    return findFrontmatterDescription(frontmatter).value;
+}

package/dist/src/core/renderers/canonical-agent.js

@@ -1,21 +1,52 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseCanonicalAgent = parseCanonicalAgent;
+const frontmatter_1 = require("../frontmatter");
 function parseCanonicalAgent(source) {
     const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
     if (!match)
         throw new Error('canonical agent requires YAML frontmatter');
     const fields = new Map();
-    for (const line of match[1].split(/\r?\n/)) {
+    // La validacion linea-por-linea sigue siendo estricta a proposito (atrapa
+    // frontmatter malformado), pero debe reconocer los block scalars: sus
+    // lineas de CONTENIDO estan indentadas y no son pares `clave: valor`.
+    // Antes lanzaban "invalid canonical agent frontmatter line", asi que un
+    // agente con `description: >-` rompia `awm add <x> -a codex`. Peor aun
+    // tras unificar el discovery: el picker mostraba la descripcion bien
+    // resuelta y recien despues explotaba el install — dos caminos leyendo el
+    // MISMO archivo con reglas distintas.
+    const lines = match[1].split(/\r?\n/);
+    let sawKey = false;
+    for (const line of lines) {
+        // Toda linea INDENTADA (o en blanco) es continuacion del valor de la
+        // clave anterior, no una clave nueva: asi se ven tanto el contenido de
+        // un block scalar como el de un escalar plano multilinea, y ambos son
+        // YAML valido. El primer fix de esto solo contemplo el block scalar,
+        // asi que `description: primera\n  continuacion` seguia lanzando
+        // "invalid canonical agent frontmatter line" y rompiendo
+        // `awm add -a codex` — mientras discovery, leyendo el MISMO archivo con
+        // la funcion compartida, mostraba la descripcion correcta en el picker.
+        // Dos caminos sobre el mismo archivo o se arreglan juntos o divergen de
+        // una forma mas confusa que el bug original.
+        if (sawKey && (line.trim() === '' || /^[ \t]/.test(line)))
+            continue;
         const field = line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
         if (!field)
             throw new Error(`invalid canonical agent frontmatter line: ${line}`);
         if (fields.has(field[1]))
             throw new Error(`duplicate canonical agent frontmatter key: ${field[1]}`);
+        sawKey = true;
+        if ((0, frontmatter_1.isBlockScalarHeader)(field[2])) {
+            fields.set(field[1], '');
+            continue;
+        }
         fields.set(field[1], field[2].replace(/^(['"])(.*)\1$/, '$2').trim());
     }
     const name = fields.get('name') ?? '';
-    const description = fields.get('description') ?? '';
+    // La descripcion sale de la funcion compartida (resuelve block scalars y
+    // deshace el escape de los escalares entrecomillados) — nunca del mapa de
+    // arriba, que solo corta comillas.
+    const description = (0, frontmatter_1.readFrontmatterDescription)(match[1]);
     const instructions = match[2].trim();
     if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name))
         throw new Error('invalid agent name');

package/dist/src/core/renderers/skill-source.js

@@ -10,7 +10,7 @@ exports.parseSkillSource = parseSkillSource;
 // link. Reuses discovery.ts's `matchFrontmatterBlock` (already the single
 // source of truth for locating the frontmatter block elsewhere in this
 // codebase) rather than writing a second frontmatter parser.
-const discovery_1 = require("../discovery");
+const frontmatter_1 = require("../frontmatter");
 /**
  * Parses a raw SKILL.md source into its `description` frontmatter field and
  * body content. Mirrors discovery.ts's `readArtifactDescription` for the
@@ -20,26 +20,18 @@ const discovery_1 = require("../discovery");
  * empty description or body.
  */
 function parseSkillSource(source) {
-    const frontmatter = (0, discovery_1.matchFrontmatterBlock)(source);
+    const frontmatter = (0, frontmatter_1.matchFrontmatterBlock)(source);
     if (frontmatter === null)
         throw new Error('skill source requires YAML frontmatter');
-    const line = frontmatter.split(/\r?\n/).find((l) => /^description\s*:/.test(l));
-    if (!line)
-        throw new Error('skill source requires a non-empty description');
-    let description = line.replace(/^description\s*:/, '').trim();
-    if ((description.startsWith('"') && description.endsWith('"')) ||
-        (description.startsWith("'") && description.endsWith("'"))) {
-        description = description.slice(1, -1);
-    }
-    // A YAML block scalar indicator (`>-`, `|-`, `>`, `|`, `>+`, `|+`) means the
-    // real description text lives on the FOLLOWING indented lines, not on this
-    // line at all — treating the bare indicator as the description would embed
-    // literal "|-" into every rendered skill. Mirrors discovery.ts's
-    // readArtifactDescription, which detects the same shape and treats it as
-    // absent rather than mis-parsing it.
-    const BLOCK_INDICATORS = new Set(['>-', '>', '|-', '|', '>+', '|+']);
-    if (BLOCK_INDICATORS.has(description))
-        description = '';
+    // Delega en readFrontmatterDescription (discovery.ts) — la MISMA funcion
+    // que usa el discovery del CLI, incluyendo la resolucion de block scalars
+    // (`description: >-` + lineas indentadas). Antes esta funcion tenia su
+    // propia copia de la logica, y ambas colapsaban el indicador de block
+    // scalar a '' en vez de leer el texto de las lineas siguientes: eso
+    // crasheaba `awm add <bundle> -a copilot|cursor` contra un skill real del
+    // registry baseline. Una sola implementacion = no pueden volver a
+    // divergir.
+    const description = (0, frontmatter_1.readFrontmatterDescription)(frontmatter);
     if (!description)
         throw new Error('skill source requires a non-empty description');
     const bodyMatch = source.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n([\s\S]*)$/);

package/dist/src/ui/text.js

@@ -30,11 +30,19 @@ function displayWidth(s) {
     }
     return w;
 }
-/** Truncate plain text to `width` cells, appending '…'. Strips ANSI — color AFTER truncating. */
+/** Truncate plain text to `width` cells, appending '…'. Strips ANSI — color AFTER truncating.
+ *
+ *  Los saltos de linea se colapsan a un espacio: esto se usa para celdas de UNA
+ *  linea (filas de `awm list`), y `displayWidth` cuenta un `\n` como ancho 1 en
+ *  vez de reconocerlo como salto — o sea que una string multilinea podia pasar
+ *  el chequeo de ancho y emitirse cruda, partiendo la fila y desalineando todo
+ *  lo que viniera despues. Antes era inalcanzable; dejo de serlo cuando el
+ *  lector de frontmatter aprendio a resolver block scalars literales (`|`), que
+ *  producen saltos de linea REALES en la descripcion. */
 function truncate(s, width) {
     if (width <= 0)
         return '';
-    const plain = stripAnsi(s);
+    const plain = stripAnsi(s).replace(/\s*\r?\n\s*/g, ' ');
     if (displayWidth(plain) <= width)
         return plain;
     if (width === 1)

package/dist/tests/core/discovery.test.js

@@ -105,8 +105,17 @@ describe('Artifact Discovery', () => {
             fs_1.default.readFileSync.mockImplementation(() => { throw new Error('ENOENT'); });
             expect((0, discovery_1.readArtifactDescription)('/missing/SKILL.md')).toBe('');
         });
-        it('returns empty string for a block scalar description indicator', () => {
+        it('resuelve un block scalar leyendo sus lineas indentadas (antes descartaba el texto y devolvia vacio)', () => {
+            // Este test afirmaba `''` sobre un fixture que contiene literalmente
+            // "actual text" — codificaba la degradacion silenciosa, no un
+            // contrato. Un `description: >-` es YAML valido y su texto vive en
+            // las lineas indentadas siguientes; descartarlo dejaba el skill sin
+            // descripcion en todo el discovery del CLI.
             fs_1.default.readFileSync.mockReturnValue('---\ndescription: >-\n  actual text\n---\n');
+            expect((0, discovery_1.readArtifactDescription)('/any/SKILL.md')).toBe('actual text');
+        });
+        it('sigue devolviendo vacio si el indicador de block scalar no tiene lineas indentadas (genuinamente sin descripcion)', () => {
+            fs_1.default.readFileSync.mockReturnValue('---\ndescription: >-\nname: otra-clave\n---\n');
             expect((0, discovery_1.readArtifactDescription)('/any/SKILL.md')).toBe('');
         });
     });

package/dist/tests/core/export/transform.test.js

@@ -1,7 +1,24 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+const js_yaml_1 = __importDefault(require("js-yaml"));
 const transform_1 = require("../../../src/core/export/transform");
 const FM = (lines) => `---\n${lines.join('\n')}\n---\nBody line.\n`;
+/** Reparsea el frontmatter EXPORTADO con un YAML real y devuelve su
+ *  `description`. Lanza si la salida no es YAML valido — que es justamente lo
+ *  que queremos que falle fuerte, en vez de asertar sobre el texto crudo y no
+ *  enterarnos de que emitimos algo que ningun parser puede leer. */
+function descriptionOf(exported) {
+    const fm = exported.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fm)
+        throw new Error('la salida no tiene bloque de frontmatter');
+    const parsed = js_yaml_1.default.load(fm[1]);
+    if (typeof parsed.description !== 'string')
+        throw new Error('description ausente o no-string en la salida');
+    return parsed.description;
+}
 describe('claudeAiTransform', () => {
     it('strips version and portable, keeps other keys and body intact', () => {
         const input = FM(['name: mermaid-diagrams', 'version: "1.0.0"', 'portable: true', 'description: "Guide."']);
@@ -16,18 +33,25 @@ describe('claudeAiTransform', () => {
         const out = (0, transform_1.claudeAiTransform)(input, 'x');
         expect(out).toContain(`description: "Does things. ${(0, transform_1.DEFERENCE_LINE)('x')}"`);
     });
+    // NOTA sobre el estilo de la salida: el transform ya no conserva el estilo de
+    // comillas del fuente — emite SIEMPRE un escalar double-quoted via
+    // JSON.stringify, sea cual sea la forma de entrada (plano, entrecomillado,
+    // block scalar, multilinea). Antes habia una rama por forma, y cada vez que
+    // el lector aprendia una forma nueva el escritor quedaba atras: asi se
+    // colaron una deference line enterrada en medio de una descripcion
+    // multilinea y otra tragada entera por un `#` de comentario. Un solo camino
+    // hace imposible esa clase de divergencia. El contrato que estos tests
+    // protegen — YAML valido que conserva descripcion + deference line — se
+    // cumple igual, y se verifica reparseando la salida con js-yaml mas abajo.
     it('appends the deference line to an unquoted description', () => {
         const input = FM(['name: x', 'portable: true', 'description: Does things.']);
         const out = (0, transform_1.claudeAiTransform)(input, 'x');
-        expect(out).toContain(`description: Does things. ${(0, transform_1.DEFERENCE_LINE)('x')}`);
+        expect(out).toContain(`description: ${JSON.stringify(`Does things. ${(0, transform_1.DEFERENCE_LINE)('x')}`)}`);
     });
     it('appends the deference line inside a single-quoted description', () => {
         const input = FM(['name: x', 'portable: true', "description: 'Does things.'"]);
         const out = (0, transform_1.claudeAiTransform)(input, 'x');
-        // DEFERENCE_LINE itself always contains an apostrophe ("registry's"), so
-        // even a fixture with no apostrophe of its own must see it doubled ('')
-        // per YAML single-quote escaping once spliced into a single-quoted scalar.
-        expect(out).toContain(`description: 'Does things. ${(0, transform_1.DEFERENCE_LINE)('x').replace(/'/g, "''")}'`);
+        expect(out).toContain(`description: ${JSON.stringify(`Does things. ${(0, transform_1.DEFERENCE_LINE)('x')}`)}`);
     });
     it('appends the deference line inside a double-quoted description with trailing whitespace', () => {
         const input = FM(['name: x', 'portable: true', 'description: "Does things."   ']);
@@ -50,26 +74,91 @@ describe('claudeAiTransform', () => {
     it('throws on frontmatter without description', () => {
         expect(() => (0, transform_1.claudeAiTransform)(FM(['name: x', 'portable: true']), 'x')).toThrow(/description/);
     });
-    it('throws on multi-line (block scalar) description', () => {
-        expect(() => (0, transform_1.claudeAiTransform)(FM(['name: x', 'description: >', '  folded text']), 'x')).toThrow(/single-line/);
+    it('resuelve una descripcion en block scalar y le anexa la deference line (antes abortaba el export del bundle entero)', () => {
+        // Regresion real: esto lanzaba, y runExport propaga el throw — asi que UN
+        // skill del registry baseline con esta forma valida (extract-design-md)
+        // hacia fallar `awm export frontend` COMPLETO, no solo ese skill.
+        const out = (0, transform_1.claudeAiTransform)(FM(['name: x', 'description: >', '  folded text', '  segunda linea']), 'x');
+        const descLine = out.split('\n').find((l) => l.startsWith('description:'));
+        expect(descLine).toBe(`description: ${JSON.stringify(`folded text segunda linea ${(0, transform_1.DEFERENCE_LINE)('x')}`)}`);
+        // Las lineas indentadas del bloque se consumieron: no quedan sueltas.
+        expect(out).not.toContain('  folded text');
+        expect(out).not.toContain('description: >');
+    });
+    it('no absorbe las claves siguientes del frontmatter al consumir el bloque', () => {
+        const out = (0, transform_1.claudeAiTransform)(FM(['description: >-', '  solo esto', 'name: sigue-viva']), 'x');
+        expect(out).toContain('name: sigue-viva');
+        const descLine = out.split('\n').find((l) => l.startsWith('description:'));
+        expect(descLine).toContain('solo esto');
+        expect(descLine).not.toContain('sigue-viva');
+    });
+    it('sigue lanzando si el block scalar no tiene contenido', () => {
+        expect(() => (0, transform_1.claudeAiTransform)(FM(['name: x', 'description: >-']), 'x')).toThrow(/no content/);
+    });
+    it('lanza si description esta presente pero vacia (sin valor y sin bloque)', () => {
+        expect(() => (0, transform_1.claudeAiTransform)(FM(['name: x', 'description:']), 'x')).toThrow(/description is empty/);
     });
-    it('escapes an apostrophe in the deference line when appending to a single-quoted description', () => {
+    it('resuelve un block scalar CON comentario final sin perder el contenido (regresion: guarda por prefijo vs match completo)', () => {
+        // La guarda de la rama de bloque usaba un prefijo (/^[>|]/) mientras el
+        // resolver exigia match COMPLETO del indicador. Con `>- # nota` entraban en
+        // desacuerdo: se publicaba el indicador como descripcion y las lineas de
+        // contenido REALES se borraban del artefacto exportado, en silencio.
+        const out = (0, transform_1.claudeAiTransform)(FM(['name: x', 'description: >- # nota al margen', '  el texto real']), 'x');
+        const descLine = out.split('\n').find((l) => l.startsWith('description:'));
+        expect(descLine).toContain('el texto real');
+        expect(descLine).not.toContain('# nota al margen');
+        expect(out).not.toContain('description: >-');
+    });
+    it('lanza ante un indicador de bloque malformado en vez de emitir YAML invalido', () => {
+        // `>-basura` lo rechaza el propio YAML. Tratarlo como escalar plano emitiria
+        // `description: >-basura ...`, invalido porque `>` abre un indicador.
+        expect(() => (0, transform_1.claudeAiTransform)(FM(['name: x', 'description: >-basura', '  texto']), 'x'))
+            .toThrow(/malformed block scalar indicator/);
+    });
+    it('conserva la linea en blanco que separa el bloque de la clave siguiente', () => {
+        const out = (0, transform_1.claudeAiTransform)(FM(['description: >-', '  el texto', '', 'name: x']), 'x');
+        expect(out).toMatch(/description: .*\n\nname: x/);
+    });
+    it('no deja que el apostrofe de la deference line rompa el escalar emitido', () => {
+        // DEFERENCE_LINE siempre contiene un apostrofe ("registry's"). El fix
+        // original lo doblaba ('') porque la salida era single-quoted; hoy la
+        // salida es double-quoted, donde el apostrofe es un caracter comun. Lo
+        // que el test protege no es la convencion de comillas sino que el
+        // resultado sea YAML bien formado con el texto intacto — se verifica
+        // reparseando con js-yaml en vez de inspeccionar comillas a ojo.
         const input = FM(['name: mermaid', 'portable: true', "description: 'Diagrams and flowcharts.'"]);
         const out = (0, transform_1.claudeAiTransform)(input, 'mermaid');
-        // The apostrophe in "registry's" must be doubled ('') per YAML single-quote escaping.
-        expect(out).toContain("registry''s mermaid skill");
-        expect(out).not.toContain("registry's mermaid skill");
-        const descLine = out.split('\n').find((l) => l.startsWith('description:'));
-        expect(descLine).toBe(`description: 'Diagrams and flowcharts. ${(0, transform_1.DEFERENCE_LINE)('mermaid').replace(/'/g, "''")}'`);
-        // Sanity check the result is well-formed: single-quoted scalar body has no
-        // lone (unescaped) apostrophes — every ' is either the opening/closing
-        // quote or part of a doubled '' pair.
-        const body = descLine.slice('description: \''.length, -1);
-        expect(body.replace(/''/g, '')).not.toMatch(/'/);
-    });
-    it('throws when a quoted description has trailing content after its closing quote (e.g. inline comment)', () => {
+        expect(descriptionOf(out)).toBe(`Diagrams and flowcharts. ${(0, transform_1.DEFERENCE_LINE)('mermaid')}`);
+        expect(descriptionOf(out)).toContain("registry's mermaid skill");
+    });
+    it('resuelve un escalar entrecomillado con comentario final en vez de lanzar', () => {
+        // Antes lanzaba. Pero `description: "x" # nota` es YAML valido y js-yaml lo
+        // lee como "x": el comentario no forma parte del valor. Lanzar obligaba al
+        // autor a tocar un SKILL.md que no tenia nada malo.
         const input = FM(['name: x', 'portable: true', 'description: "Does things." # a comment']);
-        expect(() => (0, transform_1.claudeAiTransform)(input, 'x')).toThrow(/trailing content|comment/i);
+        expect(descriptionOf((0, transform_1.claudeAiTransform)(input, 'x'))).toBe(`Does things. ${(0, transform_1.DEFERENCE_LINE)('x')}`);
+    });
+    describe('round-trip: la salida se reparsea con un YAML real (par lector+escritor)', () => {
+        // Los tests del lector, por si solos, no habrian detectado que el ESCRITOR
+        // quedaba atras cuando el lector aprendia una forma nueva. Estos casos
+        // pasan cada forma por el transform y REPARSEAN el resultado, que es donde
+        // se ve si la deference line sobrevivio y si el YAML sigue siendo valido.
+        it.each([
+            ['plano', ['description: Does things.']],
+            ['plano multilinea', ['description: primera parte', '  y su continuacion']],
+            ['plano con comentario final', ['description: hola mundo # nota del autor']],
+            ['single-quoted', ["description: 'con apostrofe: it''s'"]],
+            ['double-quoted', ['description: "con dos puntos: si"']],
+            ['folded', ['description: >-', '  primera', '  segunda']],
+            ['literal', ['description: |-', '  primera', '  segunda']],
+            ['folded con comentario en el indicador', ['description: >- # nota', '  el texto']],
+        ])('%s', (_name, descLines) => {
+            const out = (0, transform_1.claudeAiTransform)(FM(['name: x', 'portable: true', ...descLines]), 'x');
+            const desc = descriptionOf(out); // lanza si la salida no es YAML valido
+            // La deference line es la razon de existir de este transform: nunca puede
+            // perderse en un comentario ni quedar sepultada en el medio del texto.
+            expect(desc.endsWith((0, transform_1.DEFERENCE_LINE)('x'))).toBe(true);
+        });
     });
     it('cleans intra-registry paths in the body', () => {
         const md = [

package/dist/tests/core/frontmatter-description-vs-yaml.test.js

@@ -0,0 +1,118 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Test DIFERENCIAL: readFrontmatterDescription (parser a mano, cero deps de
+// runtime) contra js-yaml (parser YAML real, devDependency solo de test).
+//
+// Por que existe: el repo parsea el frontmatter a mano a proposito (ver
+// core/export/transform.ts — "sin parser YAML a proposito, YAGNI, cero deps").
+// Esa decision es sostenible SOLO si algo verifica que la implementacion a
+// mano coincide con la semantica YAML real; si no, cada forma valida que el
+// parser casero no contempla es un bug esperando a un skill que la use. Ya
+// paso dos veces: (1) un block scalar (`description: >-`) se colapsaba a
+// vacio, rompiendo `awm add -a cursor|copilot` y abortando `awm export`
+// entero contra un skill real del registry; (2) este mismo test diferencial
+// descubrio que un escalar single-quoted no deshacia el escape YAML de `'`
+// (duplicado: `''`), devolviendo "it''s" en vez de "it's".
+//
+// js-yaml es devDependency: NO entra en el bundle que instalan los usuarios.
+// La regla de cero dependencias de runtime queda intacta — de hecho este test
+// es lo que la hace defendible.
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const discovery_1 = require("../../src/core/discovery");
+/** Cada caso es un bloque de frontmatter cuyo `description` debe resolverse
+ *  IGUAL que como lo hace un parser YAML real. Sin valores esperados
+ *  hardcodeados a proposito: la referencia es js-yaml, asi que el test no
+ *  puede "envejecer" hacia una expectativa equivocada. */
+const CASES = [
+    ['folded (>)', 'description: >\n  a\n  b'],
+    ['folded strip (>-)', 'description: >-\n  a\n  b'],
+    ['folded keep (>+)', 'description: >+\n  a\n  b'],
+    ['literal (|)', 'description: |\n  a\n  b'],
+    ['literal strip (|-)', 'description: |-\n  a\n  b'],
+    ['folded con parrafos', 'description: >-\n  a\n\n  b'],
+    ['literal con parrafos', 'description: |-\n  a\n\n  b'],
+    ['bloque seguido de otra clave', 'description: >-\n  solo\nname: x'],
+    ['bloque con indent 4', 'description: >-\n    a\n    b'],
+    ['bloque con indent explicito', 'description: >2\n  a\n  b'],
+    ['bloque de una sola linea', 'description: >-\n  sola'],
+    ['bloque con colon adentro', 'description: >-\n  clave: valor'],
+    ['bloque con hash adentro', 'description: >-\n  a #no-es-comentario'],
+    ['plain', 'description: hola mundo'],
+    ['plain con guion', 'description: usa - guiones'],
+    ['double-quoted con colon', 'description: "hola: mundo"'],
+    ['double-quoted con comilla escapada', 'description: "dice \\"hola\\""'],
+    ['double-quoted con \\n', 'description: "a\\nb"'],
+    ['double-quoted con backslash', 'description: "c:\\\\\\\\ruta"'],
+    ['single-quoted con apostrofe escapado', "description: 'it''s aqui'"],
+    ['single-quoted con doble apostrofe', "description: 'a''''b'"],
+    ['single-quoted con colon', "description: 'clave: valor'"],
+    ['double-quoted con em-dash', 'description: "em — dash"'],
+    // Casos que una revision adversarial encontro y los tests a mano no cubrian.
+    ['folded con lineas MAS indentadas (no se pliegan)', 'description: >-\n  intro\n    - item uno\n    - item dos\n  outro'],
+    ['folded con indentacion irregular', 'description: >\n  foo\n   bar\n  baz'],
+    ['indicador con comentario final', 'description: >- # nota al margen\n  el texto real'],
+    ['literal con comentario final', 'description: |- # nota\n  linea'],
+    ['clave description indentada NO gana sobre la real', 'metadata:\n  description: nota interna\ndescription: la verdadera'],
+    ['description dentro del contenido de otro bloque', 'example: |\n  description: falsa\ndescription: la verdadera'],
+    ['plain con comentario final', 'description: hola mundo # un comentario'],
+    ['plain con hash pegado (NO es comentario)', 'description: usar C# y F#'],
+    ['plain multilinea (se pliega como folded)', 'description: primera\n  segunda\n  tercera'],
+    ['quoted con hash adentro (literal)', 'description: "tiene # adentro"'],
+    // Segunda tanda de revision adversarial: espacios, blancos consecutivos y
+    // escalares entrecomillados que cierran en una linea posterior.
+    ['blancos consecutivos en folded', 'description: >-\n  a\n\n\n  b'],
+    ['espacios finales dentro de un folded', 'description: >-\n  a   \n  b'],
+    ['linea solo-espacios dentro de un folded', 'description: >-\n  a\n   \n  b'],
+    ['double-quoted multilinea', 'description: "hola\n  mundo"'],
+    ['single-quoted multilinea', "description: 'hola\n  mundo'"],
+    ['double-quoted con comentario final', 'description: "x" # comentario'],
+    ['single-quoted con comentario final', "description: 'y' # comentario"],
+    ['single-quoted con apostrofe y comentario', "description: 'it''s aqui' # nota"],
+];
+/** Formas que YAML RECHAZA: no hay valor correcto que devolver, y devolver el
+ *  indicador crudo como si fuera la descripcion seria peor que no devolver
+ *  nada (se publicaria en el artefacto). El contrato aca es '' — que hace
+ *  fallar fuerte a parseSkillSource y claudeAiTransform. */
+const INVALID_CASES = [
+    ['indicador con indent 0', 'description: >0\n  a'],
+    ['indicador con indent de 2 digitos', 'description: >12\n  a'],
+    ['indicador con basura pegada', 'description: >-basura\n  a'],
+    ['indicador con comentario sin espacio', 'description: >-#c\n  a'],
+];
+describe('readFrontmatterDescription coincide con un parser YAML real (js-yaml)', () => {
+    it.each(CASES)('%s', (_name, frontmatter) => {
+        const parsed = js_yaml_1.default.load(frontmatter);
+        // Guard del propio fixture: si js-yaml no lo lee como string, el caso
+        // esta mal escrito y el test seria vacuo — que falle fuerte.
+        expect(typeof parsed.description).toBe('string');
+        const expected = parsed.description.trim();
+        expect((0, discovery_1.readFrontmatterDescription)(frontmatter)).toBe(expected);
+    });
+    it.each(INVALID_CASES)('%s: YAML lo rechaza, nosotros devolvemos vacio (nunca el indicador crudo)', (_name, frontmatter) => {
+        // Guard del fixture: si js-yaml LO ACEPTARA, el caso esta mal clasificado
+        // y este test seria vacuo — que falle fuerte.
+        expect(() => js_yaml_1.default.load(frontmatter)).toThrow();
+        expect((0, discovery_1.readFrontmatterDescription)(frontmatter)).toBe('');
+    });
+    it('resuelve el SKILL.md real del registry igual que js-yaml (extract-design-md, el caso que origino el bug)', () => {
+        // Forma exacta del skill real de awm-baseline-registry que rompia
+        // `awm add -a cursor|copilot` y `awm export frontend`.
+        const frontmatter = [
+            'name: extract-design-md',
+            'version: "1.0.1"',
+            'description: >-',
+            '  Extract a comprehensive design system (DESIGN.md) directly from frontend source',
+            '  code — React, Vue, Svelte, Angular, plain HTML/CSS, or any web framework.',
+            'allowed-tools:',
+            '  - "Bash"',
+        ].join('\n');
+        const expected = (js_yaml_1.default.load(frontmatter).description).trim();
+        expect((0, discovery_1.readFrontmatterDescription)(frontmatter)).toBe(expected);
+        // Y no absorbio la clave siguiente ni sus items indentados.
+        expect((0, discovery_1.readFrontmatterDescription)(frontmatter)).not.toContain('allowed-tools');
+        expect((0, discovery_1.readFrontmatterDescription)(frontmatter)).not.toContain('Bash');
+    });
+});

package/dist/tests/core/renderers/canonical-agent.test.js

@@ -46,6 +46,42 @@ it('ignores provider-only mode while retaining canonical instructions', () => {
         instructions: expect.stringContaining('You do NOT write code directly.'),
     }); // verifies R8, R9
 });
+it('acepta una description en block scalar y la resuelve (regresion: rompia awm add -a codex)', () => {
+    // El parser exigia que TODA linea del frontmatter fuera `clave: valor`, asi
+    // que las lineas indentadas de un bloque lanzaban "invalid canonical agent
+    // frontmatter line" y abortaban el install de codex. Peor: discovery lee el
+    // MISMO archivo y (ya arreglado) mostraba la descripcion bien en el picker,
+    // asi que el crash llegaba despues de que la UI dijera que todo estaba OK.
+    const source = [
+        '---',
+        'name: bloque-agente',
+        'description: >-',
+        '  Primera linea de la descripcion',
+        '  y su continuacion.',
+        '---',
+        'Cuerpo de instrucciones.',
+    ].join('\n');
+    expect((0, canonical_agent_1.parseCanonicalAgent)(source)).toEqual({
+        name: 'bloque-agente',
+        description: 'Primera linea de la descripcion y su continuacion.',
+        instructions: 'Cuerpo de instrucciones.',
+    });
+});
+it('acepta un escalar plano multilinea y lo pliega (js-yaml lee exactamente esto)', () => {
+    // Ojo: una version previa de este test exigia un throw aca. Estaba mal —
+    // `description: x` seguido de una linea indentada es un escalar plano
+    // multilinea, YAML perfectamente valido, y js-yaml lo lee como
+    // "x suelta e indentada". Asertar el throw codificaba una divergencia con
+    // YAML, no un contrato.
+    const source = '---\nname: ok\ndescription: x\n  suelta e indentada\n---\nbody';
+    expect((0, canonical_agent_1.parseCanonicalAgent)(source).description).toBe('x suelta e indentada');
+});
+it('sigue rechazando una linea que no es ni clave ni continuacion indentada', () => {
+    // El fix no afloja la validacion estricta: una linea en columna 0 que no es
+    // `clave: valor` sigue siendo frontmatter malformado.
+    const source = '---\nname: ok\ndescription: x\nno soy un campo\n---\nbody';
+    expect(() => (0, canonical_agent_1.parseCanonicalAgent)(source)).toThrow('invalid canonical agent frontmatter line');
+});
 it.each([
     ['---\nname: Bad Name\ndescription: x\n---\nbody', 'invalid agent name'],
     ['---\nname: ok\ndescription:\n---\nbody', 'non-empty description'],

package/dist/tests/core/renderers/cursor-mdc.test.js

@@ -49,11 +49,18 @@ Body content.
     const rendered = (0, cursor_mdc_1.renderCursorMdc)(source);
     expect(rendered).toContain('description: "*starred description"');
 });
-it('throws rather than embedding a literal block-scalar indicator as the description', () => {
-    // Regression: a YAML block scalar (`description: >-` / `|-`) means the
-    // real text lives on the FOLLOWING indented lines, not on this line —
-    // the original code took the bare indicator itself as the description,
-    // which would have rendered the literal string ">-" into the .mdc file.
+it('resuelve un block scalar leyendo sus lineas indentadas, sin emitir el indicador literal', () => {
+    // Regression, en dos etapas:
+    //  1. La version original tomaba el indicador (`>-`) COMO la descripcion,
+    //     lo que habria escrito el literal ">-" dentro del .mdc.
+    //  2. El remedio siguiente lo detectaba pero lo colapsaba a '' (=> throw),
+    //     tratando una forma YAML valida como "descripcion ausente" — este
+    //     test codificaba ESE comportamiento parcial. Rompia `awm add
+    //     <bundle> -a cursor` contra un skill real del registry baseline
+    //     (extract-design-md), que usa exactamente esta forma.
+    // El contrato correcto, y el que se asserta ahora: leer el texto de las
+    // lineas indentadas. La intencion original del test — jamas emitir el
+    // indicador crudo — se conserva explicitamente abajo.
     const source = `---
 name: block-skill
 description: >-
@@ -63,16 +70,27 @@ description: >-
 
 Body content.
 `;
-    expect(() => (0, cursor_mdc_1.renderCursorMdc)(source)).toThrow('non-empty description');
+    const rendered = (0, cursor_mdc_1.renderCursorMdc)(source);
+    expect(rendered).toContain('description: This description spans multiple lines.');
+    expect(rendered).not.toContain('>-');
 });
 it('quotes a description containing a mid-string " #" (starts a YAML comment, truncating the rest)', () => {
     // Regression: the original YAML_UNSAFE regex only caught `#` at the START
     // of the string — a `#` preceded by whitespace ANYWHERE in a plain scalar
     // also starts a comment. Unquoted, "Use this #important skill" would
     // render as YAML that silently truncates to "Use this".
+    //
+    // El fuente esta ENTRECOMILLADO a proposito: ahi el `#` es literal y
+    // sobrevive al parseo, que es la unica manera de que un `#` llegue al
+    // renderer y haya algo que escapar. Antes el fixture usaba la forma SIN
+    // comillas, pero YAML dice que ahi ` #` abre un comentario — el lector lo
+    // trataba como texto (divergencia con cualquier parser real) y este test
+    // se apoyaba en esa divergencia. El contrato que el test realmente
+    // protege — nunca emitir un `#` sin comillas en la SALIDA — queda intacto
+    // y ahora se ejercita con una entrada que de verdad lo contiene.
     const source = `---
 name: hash-skill
-description: Use this #important skill
+description: "Use this #important skill"
 ---
 
 Body content.
@@ -81,6 +99,18 @@ Body content.
     expect(rendered).toContain('description: "Use this #important skill"');
     expect(rendered).not.toContain('description: Use this #important skill');
 });
+it('trata un " #" en una description SIN comillas como comentario YAML, igual que un parser real', () => {
+    const source = `---
+name: hash-plano
+description: Use this #important skill
+---
+
+Body content.
+`;
+    // js-yaml devuelve "Use this" para esta entrada: el comentario no es parte
+    // del valor. El renderer debe coincidir con esa lectura, no inventar texto.
+    expect((0, cursor_mdc_1.renderCursorMdc)(source)).toContain('description: Use this\n');
+});
 it('quotes a description containing an embedded null byte / control character instead of emitting it raw', () => {
     // Regression: an embedded control/null byte is invalid in a YAML plain
     // scalar regardless of position — the original code's YAML_UNSAFE regex

package/dist/tests/core/renderers/skill-source-block-scalar.test.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// Regresion: `description: >-` (YAML block scalar) rompia `awm add <bundle>
+// -a copilot|cursor` contra un skill REAL del registry baseline
+// (skills/extract-design-md/SKILL.md, que usa exactamente esta forma).
+//
+// Un block scalar es YAML perfectamente valido: el indicador (`>-`, `|`, ...)
+// va en la linea de la clave y el texto real vive en las lineas indentadas
+// que siguen. El parser trataba el indicador como si fuera el valor, lo
+// detectaba como "no es una descripcion de verdad", y lo colapsaba a ''  —
+// que en `parseSkillSource` significa throw ("requires a non-empty
+// description") y en `readArtifactDescription` significa degradar en
+// silencio a descripcion vacia. Ninguno de los dos leia jamas las lineas
+// siguientes, que es donde estaba el texto todo el tiempo.
+const skill_source_1 = require("../../../src/core/renderers/skill-source");
+const cursor_mdc_1 = require("../../../src/core/renderers/cursor-mdc");
+const copilot_instructions_1 = require("../../../src/core/renderers/copilot-instructions");
+// Copia fiel del frontmatter de skills/extract-design-md/SKILL.md en
+// awm-baseline-registry — el caso real que dispara el bug, no un fixture
+// inventado.
+const realBlockScalarSkill = `---
+name: extract-design-md
+version: "1.0.1"
+description: >-
+  Extract a comprehensive design system (DESIGN.md) directly from frontend source
+  code — React, Vue, Svelte, Angular, plain HTML/CSS, or any web framework.
+---
+
+# Extract Design MD
+
+Body content.
+`;
+describe('parseSkillSource: descripciones en block scalar (regresion real del registry)', () => {
+    it('lee el texto de las lineas indentadas de un `>-`, en vez de tratar el indicador como el valor', () => {
+        const { description } = (0, skill_source_1.parseSkillSource)(realBlockScalarSkill);
+        expect(description).toBe('Extract a comprehensive design system (DESIGN.md) directly from frontend source ' +
+            'code — React, Vue, Svelte, Angular, plain HTML/CSS, or any web framework.');
+    });
+    it('pliega (folded, `>`) las lineas en espacios — no conserva los saltos de linea del fuente', () => {
+        const source = `---
+name: folded
+description: >
+  primera linea
+  segunda linea
+---
+
+Body.
+`;
+        expect((0, skill_source_1.parseSkillSource)(source).description).toBe('primera linea segunda linea');
+    });
+    it('conserva los saltos de linea de un literal (`|`) — semantica YAML distinta de `>`', () => {
+        const source = `---
+name: literal
+description: |
+  primera linea
+  segunda linea
+---
+
+Body.
+`;
+        expect((0, skill_source_1.parseSkillSource)(source).description).toBe('primera linea\nsegunda linea');
+    });
+    it('trata una linea en blanco dentro de un folded como separador de parrafo, no como espacio', () => {
+        const source = `---
+name: folded-parrafos
+description: >-
+  parrafo uno
+
+  parrafo dos
+---
+
+Body.
+`;
+        expect((0, skill_source_1.parseSkillSource)(source).description).toBe('parrafo uno\nparrafo dos');
+    });
+    it('no absorbe las claves siguientes del frontmatter como parte del bloque (corta en la primera linea no indentada)', () => {
+        const source = `---
+description: >-
+  solo esto pertenece al bloque
+name: no-soy-parte-del-bloque
+version: "9.9.9"
+---
+
+Body.
+`;
+        expect((0, skill_source_1.parseSkillSource)(source).description).toBe('solo esto pertenece al bloque');
+    });
+    it('resuelve el bloque igual con line endings CRLF (el repo es CRLF-tolerante y corre CI en windows-latest)', () => {
+        const source = '---\r\nname: crlf\r\ndescription: >-\r\n  linea uno\r\n  linea dos\r\n---\r\n\r\nBody aqui.\r\n';
+        expect((0, skill_source_1.parseSkillSource)(source).description).toBe('linea uno linea dos');
+    });
+    it('sigue lanzando si el bloque esta genuinamente vacio — un indicador sin lineas indentadas NO es una descripcion', () => {
+        const source = `---
+name: bloque-vacio
+description: >-
+name: otra-clave
+---
+
+Body.
+`;
+        expect(() => (0, skill_source_1.parseSkillSource)(source)).toThrow(/non-empty description/);
+    });
+});
+describe('renderers: el skill real del registry se renderiza para ambos providers', () => {
+    it('renderCursorMdc emite la descripcion real, nunca el indicador `>-` literal', () => {
+        const rendered = (0, cursor_mdc_1.renderCursorMdc)(realBlockScalarSkill);
+        expect(rendered).toContain('Extract a comprehensive design system');
+        // El modo de fallo que este test ancla: emitir el indicador crudo.
+        expect(rendered).not.toContain('description: >-');
+        expect(rendered).not.toContain('description: ""');
+    });
+    it('renderCopilotInstructions no crashea (no necesita la descripcion, pero parseSkillSource la exigia igual)', () => {
+        const rendered = (0, copilot_instructions_1.renderCopilotInstructions)(realBlockScalarSkill);
+        expect(rendered).toContain('applyTo: "**"');
+        expect(rendered).toContain('# Extract Design MD');
+    });
+});

package/dist/tests/ui/text.test.js

@@ -44,6 +44,15 @@ describe('truncate', () => {
     it('returns empty for non-positive width', () => {
         expect((0, text_1.truncate)('abc', 0)).toBe('');
     });
+    it('colapsa saltos de linea a un espacio — la celda es de UNA linea', () => {
+        // Regresion: `displayWidth` cuenta `\n` como ancho 1, asi que una string
+        // multilinea corta pasaba el chequeo y se emitia cruda, partiendo la fila
+        // de `awm list` y desalineando todo lo siguiente. Alcanzable desde que el
+        // lector de frontmatter resuelve block scalars literales (`|`).
+        expect((0, text_1.truncate)('linea uno\nlinea dos', 80)).toBe('linea uno linea dos');
+        expect((0, text_1.truncate)('a\r\n  b', 80)).toBe('a b');
+        expect((0, text_1.truncate)('linea uno\nlinea dos', 12)).toBe('linea uno l…');
+    });
 });
 describe('wrap', () => {
     it('breaks text at word boundaries within width', () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-workflow-manager",
-  "version": "3.13.4",
+  "version": "3.13.5",
   "main": "dist/src/index.js",
   "bin": {
     "awm": "./dist/src/index.js"
@@ -43,10 +43,12 @@
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
+    "@types/js-yaml": "4.0.9",
     "@types/node": "^25.3.0",
     "dependency-cruiser": "^17.4.3",
     "eslint": "^10.4.1",
     "jest": "^30.2.0",
+    "js-yaml": "4.1.0",
     "ts-jest": "^29.4.6",
     "typescript": "^5.9.3"
   }