agentic-workflow-manager 9.19.0 → 9.20.1

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/release/orchestrator-trailer.test.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// cli/tests/release/orchestrator-trailer.test.ts
+//
+// R6.1 (#217): the bump commit must be read as a Change Record opt-out by the code that reads it
+// (`hasOptOut`), not just contain the right text in a mocked argv. The orchestrator runs against a
+// real tmp git repo: `git add` and `git commit` execute for real with the argv the orchestrator
+// passes (never retyped here); every other command is faked.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const orchestrator_1 = require("../../src/release/orchestrator");
+const core_1 = require("../../src/release/core");
+const trailers_1 = require("../../src/core/changes/trailers");
+const helpers_1 = require("../core/changes/helpers");
+describe('release — the bump commit opts out of the Change Record (R6.1)', () => {
+    let repo;
+    beforeEach(() => { repo = (0, helpers_1.makeRepo)(); });
+    afterEach(() => repo.cleanup());
+    it('the commit the orchestrator creates is read as an opt-out and keeps its subject byte-identical', () => {
+        // Explicit environment for the child git: identity and config isolation never come from process.env alone.
+        const gitEnv = {
+            ...process.env, HOME: repo.home, GIT_CONFIG_GLOBAL: path_1.default.join(repo.home, 'gitconfig'), GIT_CONFIG_NOSYSTEM: '1',
+            GIT_AUTHOR_NAME: 't', GIT_AUTHOR_EMAIL: 't@t', GIT_COMMITTER_NAME: 't', GIT_COMMITTER_EMAIL: 't@t',
+        };
+        repo.commit({
+            'cli/package.json': '{"version":"2.1.1"}\n',
+            'cli/package-lock.json': '{"version":"2.1.1"}\n',
+            'CHANGELOG.md': '# Changelog\n',
+        }, 'chore: seed release files');
+        repo.git('config', 'commit.gpgsign', 'false');
+        expect((0, trailers_1.hasOptOut)(repo.root, ['-1', 'HEAD'])).toBe(false);
+        let pkgVersion = '2.1.1';
+        let changelog = '# Changelog\n';
+        const write = (rel, content) => fs_1.default.writeFileSync(path_1.default.join(repo.root, rel), content);
+        const commitArgv = [];
+        const io = {
+            run(cmd, args) {
+                if (cmd === 'git' && (args[0] === 'add' || args[0] === 'commit')) {
+                    if (args[0] === 'commit')
+                        commitArgv.push(args);
+                    return (0, child_process_1.execFileSync)('git', args, { cwd: repo.root, encoding: 'utf8', env: gitEnv });
+                }
+                if (cmd === 'git' && args[0] === 'rev-parse')
+                    return 'main';
+                if (cmd === 'git' && args[0] === 'log')
+                    return `feat: nueva${core_1.US}${core_1.RS}`;
+                return ''; // status, tag, npm view/publish: nothing there, nothing dirty
+            },
+            readPackageVersion: () => pkgVersion,
+            writePackageVersion: (v) => { pkgVersion = v; write('cli/package.json', `{"version":"${v}"}\n`); },
+            writeLockVersion: (v) => write('cli/package-lock.json', `{"version":"${v}"}\n`),
+            readChangelog: () => changelog,
+            writeChangelog: (c) => { changelog = c; write('CHANGELOG.md', c); },
+            writeNpmrc: () => { },
+            removeNpmrc: () => { },
+            today: () => '2026-06-25',
+            log: () => { },
+            env: { NPM_TOKEN: 'tok' },
+        };
+        const res = (0, orchestrator_1.release)({ dryRun: false, force: null, push: false, branch: 'main', cliDir: '/cli' }, io);
+        expect(res).toEqual({ released: true, version: '2.2.0' });
+        expect(commitArgv).toHaveLength(1); // the argv under test was really executed, once
+        expect(repo.git('log', '-1', '--format=%s')).toBe('chore(release): v2.2.0 [skip ci]');
+        expect((0, trailers_1.hasOptOut)(repo.root, ['-1', 'HEAD'])).toBe(true);
+        // The opt-out is a trailer paragraph of its own: the full message is subject, blank line, trailer.
+        expect(repo.git('log', '-1', '--format=%B')).toBe('chore(release): v2.2.0 [skip ci]\n\nChange-Record: none');
+    });
+});

package/dist/tests/release/orchestrator.test.js

@@ -51,6 +51,7 @@ describe('release — happy path', () => {
         expect(calls).toContain('WRITE_PKG 2.2.0');
         const joined = calls.join('\n');
         expect(joined).toMatch(/git commit .*chore\(release\): v2.2.0/);
+        expect(joined).toMatch(/git commit .*chore\(release\): v2\.2\.0 \[skip ci\] -m Change-Record: none/);
         expect(joined).toMatch(/git tag -a v2.2.0/);
         expect(joined).toMatch(/npm publish/);
         expect(joined).toMatch(/git push origin main/);

package/dist/tests/structural/change-commands-are-registered.test.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// The Change Record commands are reachable from the real program: `awm change new|validate` and `awm changes list`. Every command
+// module is tested by registering it on a fresh Commander program, which would stay green if src/index.ts forgot the register call.
+const index_1 = require("../../src/index");
+const find = (parent, name) => parent.commands.find((c) => c.name() === name);
+const flags = (command) => (command?.options ?? []).map((o) => o.long ?? o.flags).sort();
+describe('the real awm program registers the Change Record commands', () => {
+    test('`awm change` has `new <slug>` and `validate [path]` with their options', () => {
+        const change = find(index_1.program, 'change');
+        expect(change).toBeDefined();
+        const created = find(change, 'new');
+        const validated = find(change, 'validate');
+        expect(created?.usage()).toContain('<slug>');
+        expect(flags(created)).toEqual(['--base', '--issue', '--model', '--plan', '--refresh', '--session']);
+        expect(validated?.usage()).toContain('[path]');
+        expect(flags(validated)).toEqual(['--base', '--json', '--strict']);
+    });
+    test('`awm changes` has `list` with --since, --base and --format', () => {
+        const changes = find(index_1.program, 'changes');
+        expect(changes).toBeDefined();
+        expect(flags(find(changes, 'list'))).toEqual(['--base', '--format', '--since']);
+    });
+    test('both are in the top-level help', () => {
+        const help = index_1.program.helpInformation();
+        expect(help).toMatch(/^\s+change\b/m);
+        expect(help).toMatch(/^\s+changes\b/m);
+    });
+});

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

@@ -0,0 +1,78 @@
+"use strict";
+// Structural guards for two defect classes that recurred through the Change Record cycle (#217,
+// harness-retro 2026-10-17; see the branch ledger signatures `s3-cq-dirty-duplicates-gitstate`,
+// `git-dir-env-not-scrubbed` and `silent-return-instead-of-skip`):
+//
+// 1. Every git child of the change-record code runs through `execGit`/`runGit`/`gitState`
+//    (core/changes/git-env.ts), which scrubs inherited GIT_* location/pathspec variables, closes
+//    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.
+//    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) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bareGitSpawns = bareGitSpawns;
+exports.silentWin32Returns = silentWin32Returns;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const CLI_ROOT = path_1.default.join(__dirname, '../..');
+function tsFiles(dir) {
+    if (!fs_1.default.existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+        const full = path_1.default.join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...tsFiles(full));
+        else if (entry.isFile() && entry.name.endsWith('.ts'))
+            out.push(full);
+    }
+    return out;
+}
+// Naive comment stripping, as in exec-invocation-explicit-stdio.test.ts: a false positive fails loud.
+function stripComments(source) {
+    return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+}
+const BARE_GIT_SPAWN = /\b(?:execFileSync|execFile|spawnSync|spawn)\(\s*['"`]git['"`]/;
+const SILENT_WIN32_RETURN = /\bif\s*\(\s*(?:process\.platform\s*===\s*['"]win32['"]|win32|isWindows)\s*\)\s*(?:\{\s*)?return\b/;
+function bareGitSpawns(source) {
+    return BARE_GIT_SPAWN.test(stripComments(source));
+}
+function silentWin32Returns(source) {
+    return SILENT_WIN32_RETURN.test(stripComments(source));
+}
+describe('change-record conventions (structural)', () => {
+    test('the detectors fire on the offending shapes and not on the sanctioned ones', () => {
+        expect(bareGitSpawns("execFileSync('git', ['status'])")).toBe(true);
+        expect(bareGitSpawns('spawnSync("git", args, opts)')).toBe(true);
+        expect(bareGitSpawns("runGit(root, ['status'])")).toBe(false);
+        expect(bareGitSpawns("// execFileSync('git', [])\nexecGit(root, [])")).toBe(false);
+        expect(silentWin32Returns("if (process.platform === 'win32') return;")).toBe(true);
+        expect(silentWin32Returns('if (win32) { return; }')).toBe(true);
+        expect(silentWin32Returns('posixOnly(() => { /* body */ });')).toBe(false);
+        expect(silentWin32Returns("// if (process.platform === 'win32') return;")).toBe(false);
+    });
+    test('git is spawned only by git-env.ts under core/changes and the change commands', () => {
+        const dirs = ['src/core/changes', 'src/commands/change', 'src/commands/changes'].map(d => path_1.default.join(CLI_ROOT, d));
+        const allowed = path_1.default.join(CLI_ROOT, 'src/core/changes/git-env.ts');
+        const offenders = dirs
+            .flatMap(tsFiles)
+            .filter(file => file !== allowed)
+            .filter(file => bareGitSpawns(fs_1.default.readFileSync(file, 'utf8')))
+            .map(file => path_1.default.relative(CLI_ROOT, file));
+        expect(offenders).toEqual([]);
+    });
+    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.19.0",
+  "version": "9.20.1",
   "main": "dist/src/index.js",
   "bin": {
     "awm": "./dist/src/index.js"