agentic-workflow-manager 9.20.0 → 9.20.1

package/dist/src/core/process/model.js

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROCESS_NAME = void 0;
 exports.parseProcessFrontmatter = parseProcessFrontmatter;
@@ -7,40 +10,155 @@ exports.parseProcessFrontmatter = parseProcessFrontmatter;
 // Disciplina heredada literal de core/orchestrators.ts: NUNCA lanza. Un modelo
 // malformado se rechaza con diagnóstico y no invalida al registry que lo
 // contiene ni a los demás (R7.1).
+const js_yaml_1 = __importDefault(require("js-yaml"));
 const frontmatter_1 = require("../frontmatter");
 const types_1 = require("./types");
 /** El discriminador es literal: ningún documento se reconoce como modelo por su
  *  cuerpo, sus headings ni su nombre de archivo (R1.2). */
 const DISCRIMINATOR = 'process-model';
-const ALLOWED_FIELDS = ['awm', 'schema', 'name', 'status', 'entry_point', 'terminates_to', 'created', 'updated'];
+/** `description` es el único campo opcional: runtimes como Codex se niegan a
+ *  cargar un `SKILL.md` sin él, y el modelo *es* el `SKILL.md` del skill. */
+const ALLOWED_FIELDS = ['awm', 'schema', 'name', 'status', 'entry_point', 'terminates_to', 'created', 'updated', 'description'];
+/** Límite de Agent Skills que imponen los runtimes que consumen el skill.
+ *  Se cuenta en code points, no en unidades UTF-16. */
+const DESCRIPTION_MAX = 1024;
+/** Tope del bloque de frontmatter antes de entregarlo al parser YAML: acota el
+ *  costo de parsear contenido no confiable de un registry. Por encima no se
+ *  parsea (para `description`, se rechaza con el mensaje del límite de 1024). */
+const FRONTMATTER_MAX = 65536;
+/** Lo que un runtime mostraría mal o usaría para engañar: controles C0 (salvo
+ *  tab), DEL, C1, separadores U+2028/U+2029, marcas LRM/RLM/ALM, overrides e
+ *  isolates bidi, y surrogates sueltos (regex en vez de `isWellFormed`: el lib
+ *  de TS es ES2022). */
+const FORBIDDEN_CHAR = /[\u0000-\u0008\u000A-\u001F\u007F-\u009F\u061C\u200E\u200F\u2028\u2029\u202A-\u202E\u2066-\u2069]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/** Discriminador indentado: un modelo cuyas claves quedaron con sangría se
+ *  perdería en silencio como "no es un modelo". */
+const INDENTED_DISCRIMINATOR = /^awm[ \t]*:[ \t]*process-model$/;
 const STATUSES = ['draft', 'active'];
 /** El slug es lo único del modelo que puede viajar dentro de un id del Dashboard
  *  (ver sanitize.ts). Por eso se valida acá y no en la frontera de render: si
  *  admitiera rutas, markup o `=`, el id dejaría de ser seguro por construcción. */
 exports.PROCESS_NAME = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
 const DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** Caracteres de ancho cero: un valor hecho solo de ellos se ve vacío. */
+const ZERO_WIDTH = /[\u200B-\u200D\u2060\uFEFF]/g;
 /** Lector de pares `clave: valor` de un frontmatter plano. El contrato no admite
- *  anidamiento ni block scalars, así que no se arrastra un parser YAML: cualquier
- *  línea que no sea `clave: valor` es un rechazo, no una interpretación. */
+ *  anidamiento ni block scalars: cualquier línea que no sea `clave: valor` es un
+ *  rechazo, no una interpretación. (El VALOR de `description` sí pasa por el
+ *  parser YAML, más abajo.) */
 function readPairs(block) {
     const pairs = new Map();
     const problems = [];
-    for (const raw of block.split(/\r?\n/)) {
-        const line = raw.trim();
+    const continuations = [];
+    // Mismo criterio que YAML, no que JS: se parte en TODO salto de línea YAML
+    // (un CR suelto también; si no, `a\rclave: x` sería un par para acá y dos
+    // claves para un runtime) y solo se recorta espacio y tab (`\s`/`trim()`
+    // comerían NBSP o U+3000, que para YAML son contenido).
+    const lines = block.split(/\r\n|\r|\n/);
+    for (const [index, raw] of lines.entries()) {
+        const line = raw.replace(/^[ \t]+|[ \t]+$/g, '');
+        // NEL/LS/PS son saltos de línea para YAML 1.1 (PyYAML) y no para js-yaml:
+        // un comentario podría esconder una clave que solo un runtime ve. Se
+        // reporta en CUALQUIER línea, comentarios incluidos, y solo por posición.
+        if (/[\u0085\u2028\u2029]/.test(raw))
+            problems.push(`frontmatter line ${index + 1} contains a YAML 1.1 line break (NEL, LS or PS)`);
         if (line === '' || line.startsWith('#'))
             continue;
-        const m = /^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$/.exec(line);
+        // El contrato es un mapa PLANO: una línea que empieza con espacio o tab
+        // es continuación de un valor multilínea, diga lo que diga. Si se
+        // recortara antes de mirar, `  KEY: x` pasaría por campo (y su nombre
+        // terminaría en un diagnóstico).
+        const indented = /^[ \t]/.test(raw);
+        if (indented)
+            continuations.push({ line: index + 1, text: line });
+        // `[\s\S]` y no `.`: un U+2028/U+2029 dentro del valor no lo vuelve
+        // "no-par" (la línea ya viene partida); lo rechaza el chequeo de controles.
+        const m = indented ? null : /^([A-Za-z_][A-Za-z0-9_]*)[ \t]*:[ \t]*([\s\S]*)$/.exec(line);
+        // Se reporta la POSICIÓN (1-based dentro del bloque), nunca el
+        // contenido: una línea suelta suele ser la continuación de un valor
+        // multilínea, y los diagnósticos no transportan valores de campos.
         if (!m) {
-            problems.push(`line is not a "key: value" pair: ${JSON.stringify(line.slice(0, 80))}`);
+            problems.push(`frontmatter line ${index + 1} is not a "key: value" pair (multi-line values are not supported)`);
             continue;
         }
         if (pairs.has(m[1])) {
             problems.push(`duplicate field ${JSON.stringify(m[1])}`);
             continue;
         }
-        pairs.set(m[1], m[2].trim());
+        pairs.set(m[1], m[2]);
     }
-    return { pairs, problems };
+    return { pairs, problems, continuations };
+}
+/** Carga el bloque de frontmatter COMPLETO con js-yaml (schema por defecto),
+ *  exactamente como lo lee un runtime. Por encima del tope no se parsea. NUNCA
+ *  lanza: un error de js-yaml es `invalid`. */
+function loadBlock(block) {
+    if (block.length > FRONTMATTER_MAX)
+        return { kind: 'too-long' };
+    try {
+        return { kind: 'loaded', doc: js_yaml_1.default.load(block) };
+    }
+    catch {
+        return { kind: 'invalid' };
+    }
+}
+function isPlainObject(doc) {
+    return doc !== null && typeof doc === 'object' && Object.getPrototypeOf(doc) === Object.prototype;
+}
+/** Valida `description` leyéndola del bloque entero con el parser YAML real, no
+ *  de la salida de readPairs (ya recortada y partida en `:`, que difiere de lo
+ *  que lee un runtime). Ni el valor ni el texto del error de js-yaml (que puede
+ *  citar contenido) llegan al problema. */
+/** ¿El valor crudo de la línea, cargado SOLO, da el mismo string que el bloque
+ *  entero? Si no, YAML lo plegó con líneas siguientes (p. ej. una comilla que
+ *  sigue abierta a través de una línea `# …`). NUNCA lanza. */
+function readsSameAlone(raw, value) {
+    let alone;
+    try {
+        alone = js_yaml_1.default.load(`description: ${raw}`);
+    }
+    catch {
+        return false;
+    }
+    return isPlainObject(alone) && alone.description === value;
+}
+function checkDescription(raw, block, keys) {
+    const singleLine = { problem: '"description" must be a single-line string (block scalars are not supported in a process model)' };
+    // El prefijo alcanza: todo header de block scalar (bien o mal formado)
+    // empieza con `>` o `|`.
+    if (/^[>|]/.test(raw))
+        return singleLine;
+    const tooLong = { problem: `"description" must be at most ${DESCRIPTION_MAX} characters` };
+    const loaded = loadBlock(block);
+    if (loaded.kind === 'too-long')
+        return tooLong;
+    if (loaded.kind === 'invalid' || !isPlainObject(loaded.doc))
+        return { problem: '"description" cannot be read: the frontmatter is not valid YAML' };
+    const doc = loaded.doc;
+    // Si YAML lee otras claves de nivel superior que readPairs (un CR suelto,
+    // una comilla que se traga la línea siguiente), lo validado acá no es lo
+    // que verá un runtime. Ni claves ni valores van al problema.
+    const yamlKeys = Object.keys(doc);
+    if (yamlKeys.length !== keys.size || yamlKeys.some((k) => !keys.has(k))) {
+        return { problem: '"description" cannot be read: the frontmatter does not read the same as YAML (check quotes and line breaks)' };
+    }
+    const value = doc.description;
+    const empty = { problem: '"description" must not be empty' };
+    if (value === null || value === undefined)
+        return empty;
+    if (typeof value !== 'string') {
+        return { problem: '"description" must be a string (quote values YAML reads as a boolean, a number, a date or a collection)' };
+    }
+    if (value.replace(ZERO_WIDTH, '').trim() === '')
+        return empty;
+    if ([...value].length > DESCRIPTION_MAX)
+        return tooLong;
+    if (FORBIDDEN_CHAR.test(value))
+        return { problem: '"description" must not contain control, line-break or bidirectional-override characters' };
+    if (!readsSameAlone(raw, value))
+        return singleLine;
+    // Se guarda tal cual lo devuelve YAML: sin trim, con NBSP/BOM intactos.
+    return { value };
 }
 function parseProcessFrontmatter(source, file) {
     let block;
@@ -52,7 +170,22 @@ function parseProcessFrontmatter(source, file) {
     }
     if (block === null)
         return { diagnostics: [] };
-    const { pairs, problems } = readPairs(block);
+    const { pairs, problems, continuations } = readPairs(block);
+    // Un modelo con las claves indentadas no tiene `awm` de nivel superior y se
+    // perdería en silencio como "otro documento". Se nombra solo la línea.
+    // Dispara con el prefiltro barato y, además, si el bloque NO carga como YAML
+    // (sangría parcial o con tab; por encima del tope cuenta como no cargable)
+    // o carga con `awm: process-model` en su nivel superior. Si carga sin `awm`
+    // arriba (mención bajo `metadata:` o dentro de un block scalar), silencio.
+    if (!pairs.has('awm')) {
+        const indentedAwm = continuations.find((c) => INDENTED_DISCRIMINATOR.test(c.text));
+        const loaded = indentedAwm ? loadBlock(block) : undefined;
+        const fires = loaded !== undefined
+            && (loaded.kind !== 'loaded' || (isPlainObject(loaded.doc) && loaded.doc.awm === DISCRIMINATOR));
+        if (indentedAwm && fires) {
+            return { diagnostics: [`${file}: invalid process model — frontmatter keys must not be indented (frontmatter line ${indentedAwm.line})`] };
+        }
+    }
     // Sin discriminador NO es un modelo de proceso: no es un error, es otro
     // documento. Devolver diagnóstico acá inundaría de ruido a todo registry
     // (cada SKILL.md normal caería en esta rama).
@@ -96,6 +229,15 @@ function parseProcessFrontmatter(source, file) {
         if (value !== '' && !DATE.test(value))
             problems.push(`"${field}" must be YYYY-MM-DD`);
     }
+    let description;
+    const rawDescription = pairs.get('description');
+    if (rawDescription !== undefined) {
+        const checked = checkDescription(rawDescription, block, new Set(pairs.keys()));
+        if ('problem' in checked)
+            problems.push(checked.problem);
+        else
+            description = checked.value;
+    }
     if (problems.length > 0) {
         return { diagnostics: [`${file}: invalid process model — ${problems.join('; ')}`] };
     }
@@ -103,6 +245,7 @@ function parseProcessFrontmatter(source, file) {
         model: {
             schema, name, status: status, entryPoint: entryPointRaw === 'true',
             terminatesTo, created: pairs.get('created'), updated: pairs.get('updated'),
+            ...(description !== undefined ? { description } : {}),
         },
         diagnostics: [],
     };

package/dist/tests/commands/process.test.js

@@ -42,6 +42,10 @@ describe('awm process show --json', () => {
         expect(parsed).toEqual(expect.objectContaining({ name: 'mi-proceso', schema: 1, status: 'draft' }));
         expect(parsed.body.routing).toEqual([{ when: 'Al empezar', requiredState: '', goesTo: 'OP-1.1', endsAt: 'SG-1' }]);
     });
+    it('emite description cuando el modelo la trae', () => {
+        const parsed = JSON.parse((0, process_1.runProcessShow)({ models: [model({ description: 'Use when tracing' })], diagnostics: [] }, 'mi-proceso', true).stdout);
+        expect(parsed.description).toBe('Use when tracing');
+    });
     it('el JSON no filtra el path del filesystem del registry', () => {
         const parsed = JSON.parse((0, process_1.runProcessShow)({ models: [model()], diagnostics: [] }, 'mi-proceso', true).stdout);
         expect(JSON.stringify(parsed)).not.toContain('/r/skills');

package/dist/tests/core/changes/helpers.js

@@ -135,8 +135,8 @@ function gitAtLeast(major, minor) {
     const v = gitVersion();
     return v !== null && (v[0] > major || (v[0] === major && v[1] >= minor));
 }
-/** `test` where symlinks and POSIX modes exist; reported as skipped (not as passed) on Windows. */
-exports.posixOnly = process.platform === 'win32' ? test.skip : test;
+var platform_1 = require("../../helpers/platform");
+Object.defineProperty(exports, "posixOnly", { enumerable: true, get: function () { return platform_1.posixOnly; } });
 /**
  * A copy of `template` in its own directory (same throwaway home, same git isolation): a few milliseconds instead of the
  * several git processes `makeRepo` spawns. For suites that need a fresh repository per test. `cleanup` removes only the copy;

package/dist/tests/core/dashboard/write-html.test.js

@@ -7,6 +7,7 @@ const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const write_html_1 = require("../../../src/core/dashboard/write-html");
+const platform_1 = require("../../helpers/platform");
 describe('writeHtmlAtomically', () => {
     let root;
     beforeEach(() => { root = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-html-')); });
@@ -85,9 +86,7 @@ describe('writeHtmlAtomically', () => {
             open.mockRestore();
         }
     });
-    it('uses mode 0600 for a POSIX adjacent temporary file', () => {
-        if (process.platform === 'win32')
-            return;
+    (0, platform_1.posixOnly)('uses mode 0600 for a POSIX adjacent temporary file', () => {
         const target = path_1.default.join(root, 'posix.html');
         const open = jest.spyOn(fs_1.default, 'openSync');
         try {

package/dist/tests/core/evidence/store.test.js

@@ -8,6 +8,7 @@ const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const evidence_fixtures_1 = require("../../helpers/evidence-fixtures");
 const store_1 = require("../../../src/core/evidence/store");
+const platform_1 = require("../../helpers/platform");
 describe('cycle evidence store', () => {
     let root;
     beforeEach(() => { root = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-evidence-')); });
@@ -20,9 +21,7 @@ describe('cycle evidence store', () => {
         expect(fs_1.default.readdirSync(dir)).toEqual([`${evidence.cycleId}.json`]);
         expect(JSON.parse(fs_1.default.readFileSync(path_1.default.join(dir, `${evidence.cycleId}.json`), 'utf8')).qa.fixes).toBe(0);
     });
-    test('rejects symlinked evidence ancestors without writing outside root', () => {
-        if (process.platform === 'win32')
-            return;
+    (0, platform_1.posixOnly)('rejects symlinked evidence ancestors without writing outside root', () => {
         const outside = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-evidence-outside-'));
         fs_1.default.symlinkSync(outside, path_1.default.join(root, '.awm'));
         expect(() => (0, store_1.writeCycleEvidence)(root, (0, evidence_fixtures_1.cycleEvidenceFixture)())).toThrow(/symlink/);

package/dist/tests/core/ledger/store.test.js

@@ -8,6 +8,7 @@ const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const store_1 = require("../../../src/core/ledger/store");
 const types_1 = require("../../../src/core/ledger/types");
+const platform_1 = require("../../helpers/platform");
 function mkTmp() {
     return fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-ledger-'));
 }
@@ -191,18 +192,11 @@ describe('ledger store — archive', () => {
         expect((0, store_1.listEntries)(cwd, 'feat-x')).toEqual([expect.objectContaining({ signature: 'active-evidence' })]);
         expect(fs_1.default.readFileSync(archivePath, 'utf-8')).toContain('archived-evidence');
     });
-    test('refuses a dangling symlink archive destination and preserves the active ledger', () => {
+    (0, platform_1.symlinkTest)('refuses a dangling symlink archive destination and preserves the active ledger', () => {
         (0, store_1.addEntry)(cwd, entry({ signature: 'active-evidence' }));
         const archivePath = path_1.default.join(cwd, '.awm', 'ledger', 'archive', 'feat-x-20260606T000000.jsonl');
         fs_1.default.mkdirSync(path_1.default.dirname(archivePath), { recursive: true });
-        try {
-            fs_1.default.symlinkSync(path_1.default.join(cwd, 'missing-target.jsonl'), archivePath);
-        }
-        catch (error) {
-            if (process.platform === 'win32')
-                return;
-            throw error;
-        }
+        fs_1.default.symlinkSync(path_1.default.join(cwd, 'missing-target.jsonl'), archivePath);
         expect(() => (0, store_1.archiveLedger)(cwd, 'feat-x', '20260606T000000')).toThrow(/archive.*already exists/i);
         expect(fs_1.default.lstatSync(archivePath).isSymbolicLink()).toBe(true);
         expect((0, store_1.listEntries)(cwd, 'feat-x')).toEqual([expect.objectContaining({ signature: 'active-evidence' })]);

package/dist/tests/core/process/discover.test.js

@@ -66,6 +66,27 @@ describe('discoverProcessModels', () => {
         expect(r.models.map((m) => m.name)).toEqual(['mi-proceso']);
         expect(r.diagnostics).toEqual([]);
     });
+    it('description sobrevive parse → discover, tal cual la lee YAML', () => {
+        const saved = { HOME: process.env.HOME, AWM_HOME: process.env.AWM_HOME };
+        process.env.HOME = path_1.default.join(tmp, 'home');
+        process.env.AWM_HOME = path_1.default.join(tmp, 'home', '.awm');
+        try {
+            const root = registry(path_1.default.join(tmp, 'rd'), {
+                'con-desc': FIXTURE.replace('NAME', 'con-desc').replace('created:', 'description: "Use when: tracing\\u00A0"\ncreated:'),
+            });
+            const r = (0, discover_1.discoverProcessModels)([root]);
+            expect(r.diagnostics).toEqual([]);
+            expect(r.models.map((m) => m.description)).toEqual(['Use when: tracing ']);
+        }
+        finally {
+            for (const [k, v] of Object.entries(saved)) {
+                if (v === undefined)
+                    delete process.env[k];
+                else
+                    process.env[k] = v;
+            }
+        }
+    });
     it('un modelo roto no impide descubrir los sanos', () => {
         const root = registry(path_1.default.join(tmp, 'r2'), {
             'sano': FIXTURE.replace('NAME', 'sano'),

package/dist/tests/core/process/model.test.js

@@ -1,5 +1,9 @@
 "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 model_1 = require("../../../src/core/process/model");
 const valid = `---
 awm: process-model
@@ -80,4 +84,338 @@ describe('parseProcessFrontmatter', () => {
         expect(r.model).toBeUndefined();
         expect(r.diagnostics.join(' ')).toMatch(new RegExp(`"${field}" is required`));
     });
+    describe('description (optional)', () => {
+        const withDescription = (line) => valid.replace('created:', `${line}\ncreated:`);
+        it('is optional: a model without it parses unchanged and has no description key', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(valid, 'p');
+            expect(r.diagnostics).toEqual([]);
+            expect(r.model).toBeDefined();
+            expect(Object.prototype.hasOwnProperty.call(r.model, 'description')).toBe(false);
+        });
+        it.each([
+            ['plain', 'description: Use when tracing a work session', 'Use when tracing a work session'],
+            ['double-quoted', 'description: "Use when: tracing \\"sessions\\""', 'Use when: tracing "sessions"'],
+            ['single-quoted', "description: 'It''s the entry point'", "It's the entry point"],
+        ])('accepts a %s single-line value and exposes it resolved', (_kind, line, expected) => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(line), 'p');
+            expect(r.diagnostics).toEqual([]);
+            expect(r.model?.description).toBe(expected);
+        });
+        it('accepts exactly 1024 characters and rejects 1025', () => {
+            expect((0, model_1.parseProcessFrontmatter)(withDescription(`description: ${'a'.repeat(1024)}`), 'p').model?.description).toHaveLength(1024);
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(`description: ${'a'.repeat(1025)}`), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toMatch(/"description" must be at most 1024 characters/);
+        });
+        it.each(['description:', 'description: ""', "description: ''", 'description: "   "'])('rejects an empty value: %s', (line) => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(line), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toMatch(/"description" must not be empty/);
+        });
+        it.each(['description: >', 'description: >-', 'description: |', 'description: |2+', 'description: >-basura'])('rejects a block scalar header: %s', (line) => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(`${line}\n  folded text`), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toMatch(/"description" must be a single-line string \(block scalars are not supported in a process model\)/);
+        });
+        it('still rejects every other unknown field next to a valid description', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription('description: ok\nsummary: nope'), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toMatch(/unknown field "summary"/);
+            expect(r.diagnostics.join(' ')).not.toMatch(/unknown field "description"/);
+        });
+        it('rejects a duplicated description', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription('description: a\ndescription: b'), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toMatch(/duplicate field "description"/);
+        });
+        it.each([
+            ['a block scalar', 'description: >-\n  SECRETVALUE here'],
+            ['a plain multi-line value', 'description: first\n  SECRETVALUE second'],
+            ['a quote closed on a later line', 'description: "hola\n  SECRETVALUE mundo"'],
+        ])('reports %s by line position and never echoes its content', (_kind, lines) => {
+            // Bloque del fixture: awm(1) … terminates_to(6); la línea description
+            // queda en 7 y su continuación en 8.
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(lines), 'p');
+            expect(r.model).toBeUndefined();
+            for (const d of r.diagnostics)
+                expect(d).not.toContain('SECRETVALUE');
+            expect(r.diagnostics.join(' ')).toContain('frontmatter line 8 is not a "key: value" pair (multi-line values are not supported)');
+        });
+        it.each([
+            ['a plain value', 'description: Use for\n  SECRETKEY: when X', false],
+            ['a block scalar', 'description: >-\n  SECRETKEY: x', true],
+        ])('treats an indented "KEY: x" after %s as a continuation, never as a field', (_kind, lines, isBlock) => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(lines), 'p');
+            expect(r.model).toBeUndefined();
+            for (const d of r.diagnostics)
+                expect(d).not.toContain('SECRETKEY');
+            expect(r.diagnostics.join(' ')).toContain('frontmatter line 8 is not a "key: value" pair (multi-line values are not supported)');
+            if (isBlock) {
+                expect(r.diagnostics.join(' ')).toMatch(/"description" must be a single-line string \(block scalars are not supported in a process model\)/);
+            }
+        });
+        const PARSE_ERROR = /"description" cannot be read: the frontmatter is not valid YAML/;
+        const NOT_A_STRING = /"description" must be a string \(quote values YAML reads as a boolean, a number, a date or a collection\)/;
+        it.each([
+            '- foo', '? foo', 'a:\tb', 'Use when: tracing', '"hola', "'hola", "'hola # x", '"hola # x', '"a" junk',
+            'ends with colon:', '@x', '\x1b',
+        ])('rejects a value YAML cannot parse as a single-line string: %j', (value) => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(`description: ${value}`), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toMatch(PARSE_ERROR);
+        });
+        it.each(['true', '123', '2026-01-01', '[a, b]'])('rejects a value YAML reads as a non-string: %s', (value) => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(`description: ${value}`), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toMatch(NOT_A_STRING);
+        });
+        it.each(['null', '~', '# x'])('rejects a value YAML reads as null as empty: %s', (value) => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(`description: ${value}`), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toMatch(/"description" must not be empty/);
+        });
+        it('never echoes the value or the YAML error text into a diagnostic', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription('description: SECRETVALUE: x'), 'p');
+            expect(r.diagnostics.join(' ')).toMatch(PARSE_ERROR);
+            for (const d of r.diagnostics)
+                expect(d).not.toContain('SECRETVALUE');
+        });
+        it('resolves YAML double-quoted escapes', () => {
+            expect((0, model_1.parseProcessFrontmatter)(withDescription('description: "\\x41"'), 'p').model?.description).toBe('A');
+        });
+        it('stores the YAML string untrimmed', () => {
+            expect((0, model_1.parseProcessFrontmatter)(withDescription('description: "  padded  "'), 'p').model?.description).toBe('  padded  ');
+        });
+        it.each([
+            ['description: "Use when: tracing"', 'Use when: tracing'],
+            ["description: 'It''s'", "It's"],
+        ])('accepts the quoted form %s', (line, expected) => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(line), 'p');
+            expect(r.diagnostics).toEqual([]);
+            expect(r.model?.description).toBe(expected);
+        });
+        const blockOf = (source) => source.slice(4, source.indexOf('\n---', 4));
+        /** Modelo válido con description `ok` cuyo bloque de frontmatter mide exactamente `target`. */
+        const withBlockLength = (target) => {
+            const base = withDescription('description: ok');
+            const pad = target - blockOf(base).length - 3;
+            const source = base.replace('\ncreated:', `\n# ${'x'.repeat(pad)}\ncreated:`);
+            expect(blockOf(source)).toHaveLength(target);
+            return source;
+        };
+        it('parses a frontmatter block of exactly 65536 characters', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(withBlockLength(65536), 'p');
+            expect(r.diagnostics).toEqual([]);
+            expect(r.model?.description).toBe('ok');
+        });
+        it('rejects a frontmatter block over 65536 characters with the 1024 message without parsing it', () => {
+            const source = withBlockLength(65537);
+            const load = jest.spyOn(js_yaml_1.default, 'load');
+            try {
+                const r = (0, model_1.parseProcessFrontmatter)(source, 'p');
+                expect(r.model).toBeUndefined();
+                expect(r.diagnostics.join(' ')).toMatch(/"description" must be at most 1024 characters/);
+                expect(load).not.toHaveBeenCalled();
+            }
+            finally {
+                load.mockRestore();
+            }
+        });
+        it('accepts a short value followed by a 20000-character comment', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(`description: ok # ${'x'.repeat(20000)}`), 'p');
+            expect(r.diagnostics).toEqual([]);
+            expect(r.model?.description).toBe('ok');
+        });
+        it('accepts an escape-heavy value that resolves to 1024 code points', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(`description: "${'\\x41'.repeat(1024)}"`), 'p');
+            expect(r.diagnostics).toEqual([]);
+            expect(r.model?.description).toBe('A'.repeat(1024));
+        });
+        it('preserves NBSP, U+3000 and BOM exactly as YAML reads them', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription('description: \u00A0hello\u3000world\uFEFF'), 'p');
+            expect(r.diagnostics).toEqual([]);
+            expect(r.model?.description).toBe('\u00A0hello\u3000world\uFEFF');
+        });
+        it('rejects description:value with no space after the colon', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription('description:value'), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toMatch(PARSE_ERROR);
+        });
+        const CONTROL = /"description" must not contain control, line-break or bidirectional-override characters/;
+        it.each([
+            '"a\\nb"', '"a\\rb"', '"\\0"', '"\\e[31m"', '"\\x7f"', '"\\x85"', '"\\x9f"',
+            '"a\\u2028b"', '"a\\u2029b"', '"\\u202A"', '"\\u202E"', '"\\u2066"', '"\\u2069"',
+            '"\\uD800"', '"\\uDC00"', 'a\u2028b', 'a\u2029b', 'a\u202Eb', 'a\u0085b',
+        ])('rejects control, line-break, bidi or lone-surrogate content: %j', (value) => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(`description: ${value}`), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toMatch(CONTROL);
+        });
+        it.each([
+            ['an escaped tab', '"a\\tb"', 'a\tb'],
+            ['a surrogate pair', '"\\uD83D\\uDE00"', '\u{1F600}'],
+        ])('accepts %s', (_kind, value, expected) => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(`description: ${value}`), 'p');
+            expect(r.diagnostics).toEqual([]);
+            expect(r.model?.description).toBe(expected);
+        });
+        it.each(['"\\u200B"', '"\\u200B\\u200C\\u200D"', '"\\u2060\\uFEFF "'])('rejects a value made only of zero-width characters as empty: %j', (value) => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(`description: ${value}`), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toMatch(/"description" must not be empty/);
+        });
+        it.each(['"a\\bb"', '"a\\x1fb"', '"a\\u200Eb"', '"a\\u200Fb"', '"a\\u061Cb"'])('rejects backspace, US and LRM/RLM/ALM: %j', (value) => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(`description: ${value}`), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toMatch(CONTROL);
+        });
+        const DIVERGES = /"description" cannot be read: the frontmatter does not read the same as YAML \(check quotes and line breaks\)/;
+        it('rejects a bare CR that smuggles a second top-level key', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription('description: hello\rallowed-tools: x'), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toMatch(DIVERGES);
+            for (const d of r.diagnostics)
+                expect(d).not.toContain('allowed-tools');
+        });
+        it('rejects an unclosed quote that YAML folds into the following name line', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(valid.replace('name: ejemplo-proceso', 'description: "hola\nname: ejemplo-proceso"'), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toMatch(DIVERGES);
+        });
+        it('validates a description that follows a comment on a bare CR', () => {
+            const bad = (0, model_1.parseProcessFrontmatter)(withDescription('#\rdescription: 123'), 'p');
+            expect(bad.model).toBeUndefined();
+            expect(bad.diagnostics.join(' ')).toMatch(NOT_A_STRING);
+            const ok = (0, model_1.parseProcessFrontmatter)(withDescription('#\rdescription: ok'), 'p');
+            expect(ok.diagnostics).toEqual([]);
+            expect(ok.model?.description).toBe('ok');
+        });
+        it('reads NBSP followed by > as a string, not as a block-scalar header', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription('description: \u00A0>'), 'p');
+            expect(r.diagnostics).toEqual([]);
+            expect(r.model?.description).toBe('\u00A0>');
+        });
+        it.each([['NEL', '\u0085'], ['LS', '\u2028'], ['PS', '\u2029']])('rejects a %s inside a comment line by position', (_kind, ch) => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(`# SECRET${ch}name: smuggled`), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toContain('frontmatter line 7 contains a YAML 1.1 line break (NEL, LS or PS)');
+            for (const d of r.diagnostics)
+                expect(d).not.toContain('SECRET');
+        });
+        it.each([['NEL', '\u0085'], ['LS', '\u2028'], ['PS', '\u2029']])('rejects a %s inside a value line of any field by position', (_kind, ch) => {
+            const inDescription = (0, model_1.parseProcessFrontmatter)(withDescription(`description: a${ch}b`), 'p');
+            expect(inDescription.model).toBeUndefined();
+            expect(inDescription.diagnostics.join(' ')).toContain('frontmatter line 7 contains a YAML 1.1 line break (NEL, LS or PS)');
+            const inName = (0, model_1.parseProcessFrontmatter)(valid.replace('name: ejemplo-proceso', `name: ejemplo${ch}proceso`), 'p');
+            expect(inName.model).toBeUndefined();
+            expect(inName.diagnostics.join(' ')).toContain('frontmatter line 3 contains a YAML 1.1 line break (NEL, LS or PS)');
+        });
+        it.each(['description: "foo\n# bar"', "description: 'foo\n# bar'"])('rejects a quoted value that YAML folds across a following comment line: %j', (lines) => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(lines), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toMatch(/"description" must be a single-line string \(block scalars are not supported in a process model\)/);
+            for (const d of r.diagnostics)
+                expect(d).not.toContain('bar');
+        });
+        it.each([
+            ['description: "Use when: tracing a work session"', 'Use when: tracing a work session'],
+            ['description: Use when tracing a work session # nota', 'Use when tracing a work session'],
+            ["description: 'It''s the entry point' # nota", "It's the entry point"],
+            ['description: "Traza la sesión \\u2014 sin perder pasos"\n# comentario aparte', 'Traza la sesión \u2014 sin perder pasos'],
+        ])('keeps accepting a realistic description: %j', (lines, expected) => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription(lines), 'p');
+            expect(r.diagnostics).toEqual([]);
+            expect(r.model?.description).toBe(expected);
+        });
+        it('lists description in the unknown-field message', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription('summary: nope'), 'p');
+            expect(r.diagnostics.join(' ')).toMatch(/the contract admits only [^;]*\bdescription\b/);
+        });
+        it('accepts a closed quote followed by a comment', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription('description: "a" # note'), 'p');
+            expect(r.diagnostics).toEqual([]);
+            expect(r.model?.description).toBe('a');
+        });
+        it('rejects a comment-only value as empty and never echoes it', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription('description: # x'), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).toMatch(/"description" must not be empty/);
+            for (const d of r.diagnostics)
+                expect(d).not.toContain('# x');
+        });
+        it('counts the 1024 limit in code points, not UTF-16 units', () => {
+            const ok = (0, model_1.parseProcessFrontmatter)(withDescription(`description: ${'😀'.repeat(1024)}`), 'p');
+            expect(ok.diagnostics).toEqual([]);
+            expect([...(ok.model?.description ?? '')]).toHaveLength(1024);
+            const tooLong = (0, model_1.parseProcessFrontmatter)(withDescription(`description: ${'😀'.repeat(1025)}`), 'p');
+            expect(tooLong.model).toBeUndefined();
+            expect(tooLong.diagnostics.join(' ')).toMatch(/"description" must be at most 1024 characters/);
+        });
+        it('keeps skipping an indented comment line after a valid description', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription('description: ok\n  # comentario'), 'p');
+            expect(r.diagnostics).toEqual([]);
+            expect(r.model?.description).toBe('ok');
+        });
+        it('accepts a plain value followed by a comment, without the comment', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription('description: plain text # note'), 'p');
+            expect(r.diagnostics).toEqual([]);
+            expect(r.model?.description).toBe('plain text');
+        });
+        it('accepts escaped quotes inside a closed double-quoted value', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(withDescription('description: "a \\"b\\""'), 'p');
+            expect(r.diagnostics).toEqual([]);
+            expect(r.model?.description).toBe('a "b"');
+        });
+        it('never throws on hostile description values', () => {
+            for (const line of ['description: "unclosed', "description: '''", 'description: \x00', `description: ${'"'.repeat(5000)}`]) {
+                expect(() => (0, model_1.parseProcessFrontmatter)(withDescription(line), 'p')).not.toThrow();
+            }
+        });
+    });
+    describe('indented frontmatter keys', () => {
+        const indentAll = (source) => source.replace(/^---\n([\s\S]*?)\n---/, (_m, block) => `---\n${block.split('\n').map((l) => `  ${l}`).join('\n')}\n---`);
+        it('reports a model whose keys are all indented instead of ignoring it', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(indentAll(valid), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics).toEqual(['p: invalid process model — frontmatter keys must not be indented (frontmatter line 1)']);
+        });
+        it('allows whitespace around the colon and counts comment lines', () => {
+            const r = (0, model_1.parseProcessFrontmatter)('---\n# nota\n  awm :  process-model\n  name: x\n---\n', 'p');
+            expect(r.diagnostics).toEqual(['p: invalid process model — frontmatter keys must not be indented (frontmatter line 2)']);
+        });
+        it.each([
+            ['another indented value', '---\nname: x\nmetadata:\n  awm: other\n---\n'],
+            ['a mention nested under metadata', '---\nname: x\nmetadata:\n  awm: process-model\n---\n'],
+            ['a mention inside a block-scalar description', '---\nname: x\ndescription: >\n  awm: process-model\n---\n'],
+            ['a near-miss discriminator', '---\n  awm: process-model-x\n  name: x\n---\n'],
+        ])('stays silent for a non-model with %s', (_kind, source) => {
+            expect((0, model_1.parseProcessFrontmatter)(source, 'p')).toEqual({ diagnostics: [] });
+        });
+        it.each([
+            ['only the awm line indented', valid.replace('awm: process-model', '  awm: process-model')],
+            ['a tab-indented awm line', valid.replace('awm: process-model', '\tawm: process-model')],
+        ])('reports %s even though YAML cannot load the block', (_kind, source) => {
+            expect((0, model_1.parseProcessFrontmatter)(source, 'p')).toEqual({
+                diagnostics: ['p: invalid process model — frontmatter keys must not be indented (frontmatter line 1)'],
+            });
+        });
+        it('gives no indented diagnostic to a top-level-awm model with a nested metadata.awm', () => {
+            const r = (0, model_1.parseProcessFrontmatter)(valid.replace('created:', 'metadata:\n  awm: process-model\ncreated:'), 'p');
+            expect(r.model).toBeUndefined();
+            expect(r.diagnostics.join(' ')).not.toMatch(/must not be indented/);
+        });
+        it('reports an indented discriminator in a block over 65536 characters without loading it', () => {
+            const source = indentAll(valid.replace('\ncreated:', `\n# ${'x'.repeat(65536)}\ncreated:`));
+            const load = jest.spyOn(js_yaml_1.default, 'load');
+            try {
+                expect((0, model_1.parseProcessFrontmatter)(source, 'p')).toEqual({
+                    diagnostics: ['p: invalid process model — frontmatter keys must not be indented (frontmatter line 1)'],
+                });
+                expect(load).not.toHaveBeenCalled();
+            }
+            finally {
+                load.mockRestore();
+            }
+        });
+    });
 });

package/dist/tests/helpers/platform.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.symlinkTest = exports.canCreateSymlinks = exports.posixOnly = void 0;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+/** `test` where symlinks and POSIX modes exist; reported as skipped (not as passed) on Windows. */
+exports.posixOnly = process.platform === 'win32' ? test.skip : test;
+/** True when this process can create a symlink (Windows needs the privilege or developer mode). */
+exports.canCreateSymlinks = (() => {
+    const dir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-symlink-probe-'));
+    try {
+        fs_1.default.symlinkSync(path_1.default.join(dir, 'missing-target'), path_1.default.join(dir, 'link'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        fs_1.default.rmSync(dir, { recursive: true, force: true });
+    }
+})();
+/** `test` that needs to create symlinks; reported as skipped (not as passed) where it cannot. */
+exports.symlinkTest = exports.canCreateSymlinks ? test : test.skip;

package/dist/tests/structural/change-record-git-and-platform-conventions.test.js

@@ -8,7 +8,8 @@
 //    stdin, bounds time and output and sets GIT_NO_LAZY_FETCH. A bare `execFileSync('git', ...)`
 //    in these directories silently loses all of that, and reviewers found such leaks four times.
 // 2. A test that returns early on Windows is reported as PASSED by the 3-platform release gate.
-//    These suites use `posixOnly` (test.skip with a visible reason) instead.
+//    Every suite under cli/tests uses a visible skip instead: `posixOnly`, or `symlinkTest` when the
+//    test only needs symlinks (cli/tests/helpers/platform.ts).
 //
 // The detectors are exercised on inline samples below, so each guard demonstrably fires.
 var __importDefault = (this && this.__importDefault) || function (mod) {
@@ -66,10 +67,10 @@ describe('change-record conventions (structural)', () => {
             .map(file => path_1.default.relative(CLI_ROOT, file));
         expect(offenders).toEqual([]);
     });
-    test('change-record tests skip with posixOnly instead of returning early on Windows', () => {
-        const dirs = ['tests/core/changes', 'tests/commands/change', 'tests/commands/changes'].map(d => path_1.default.join(CLI_ROOT, d));
-        const offenders = dirs
-            .flatMap(tsFiles)
+    test('no test under cli/tests returns early on Windows instead of skipping visibly', () => {
+        // This file is excluded: its detector samples are offending shapes on purpose.
+        const offenders = tsFiles(path_1.default.join(CLI_ROOT, 'tests'))
+            .filter(file => file !== __filename)
             .filter(file => silentWin32Returns(fs_1.default.readFileSync(file, 'utf8')))
             .map(file => path_1.default.relative(CLI_ROOT, file));
         expect(offenders).toEqual([]);

package/dist/tests/structural/process-model-description-contract.test.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const DESIGN = path_1.default.resolve(__dirname, '../../../docs/plans/2026-08-23-process-lifecycle-design.md');
+function artifactSection() {
+    const text = fs_1.default.readFileSync(DESIGN, 'utf8');
+    const start = text.indexOf('### El artefacto');
+    expect(start).toBeGreaterThan(-1);
+    const end = text.indexOf('\n### ', start + 1);
+    return text.slice(start, end === -1 ? undefined : end);
+}
+describe('process-model contract documents the optional description (PD-4)', () => {
+    it('lists description in the frontmatter block as optional', () => {
+        const section = artifactSection();
+        expect(section).toMatch(/^description: <texto de una línea> {2}# opcional$/m);
+    });
+    it('states the rules the parser enforces and why the field exists', () => {
+        /** Whitespace-normalized so re-wrapping the prose never breaks a pinned phrase. */
+        const section = artifactSection().replace(/\s+/g, ' ');
+        expect(section).toContain('#### Enmienda 2026-10-18 — `description` opcional');
+        expect(section).toContain('una sola línea');
+        expect(section).toContain('1024 caracteres');
+        expect(section).toContain('Codex');
+        expect(section).toContain('único campo opcional');
+        expect(section).toContain('parser YAML');
+        expect(section).not.toContain('no reemplaza a un parser YAML');
+        expect(section).toContain('code points');
+        expect(section).toContain('caracteres de control');
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-workflow-manager",
-  "version": "9.20.0",
+  "version": "9.20.1",
   "main": "dist/src/index.js",
   "bin": {
     "awm": "./dist/src/index.js"