agentic-workflow-manager 9.20.0 → 9.20.2

package/dist/tests/structural/native-release-artifacts.test.js

@@ -5,25 +5,161 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
 const CLI_ROOT = path_1.default.resolve(__dirname, '..', '..');
 const REPO_ROOT = path_1.default.resolve(CLI_ROOT, '..');
 function readWorkflow(name) {
     return fs_1.default.readFileSync(path_1.default.join(REPO_ROOT, '.github', 'workflows', name), 'utf8').replace(/\r\n/g, '\n');
 }
-function assertArmPartition(source) {
+const HOT_IGNORE = String.raw `node_modules|[/\\]cli[/\\]tests[/\\]commands[/\\]watch[/\\]track-(finalize|freeze)\.test\.ts$`;
+const CHANGES_PATTERN = String.raw `[/\\]cli[/\\]tests[/\\](core[/\\]changes|commands[/\\]changes?)[/\\]`;
+const HOT_STEP = 'Test hot Windows ARM suites';
+const CHANGES_STEP = 'Test Change Record Windows ARM suites';
+const CHANGES_RUN = `npx jest --runInBand --bail --testPathPatterns='${CHANGES_PATTERN}'`;
+const REMAINDER_COMMENT = "      # The ARM runner's slow suites run in two separate jobs (watch track-finalize/freeze, and the Change Record suites). Keep runInBand within each job; no test file may run twice or be dropped.\n";
+const HOT_RUN = 'npx jest --runTestsByPath tests/commands/watch/track-finalize.test.ts tests/commands/watch/track-freeze.test.ts --runInBand --bail';
+const RELEASE_GATE = ['test', 'windows-arm-changes', 'windows-arm-hot'];
+const SHARD_SETUP = [
+    { uses: 'actions/checkout@v4' },
+    { uses: 'actions/setup-node@v4', with: { 'node-version': '22' } },
+    { name: 'Install', 'working-directory': 'cli', run: 'npm ci' },
+    { name: 'Build', 'working-directory': 'cli', run: 'npm run native:build && npm run build' },
+    { name: 'Build test-only native addon', 'working-directory': 'cli', run: 'npm run native:test-build' },
+];
+// Jest compiles --testPathPatterns with the `i` flag but --testPathIgnorePatterns
+// without it, so a directory differing only in case would run in both the shard
+// and the remainder. Returns every directory that falls in that gap.
+function caseOnlyShardPaths(directories, pattern) {
+    const insensitive = new RegExp(pattern, 'i');
+    const sensitive = new RegExp(pattern);
+    return directories.filter((directory) => {
+        const candidate = `${directory}/`;
+        return insensitive.test(candidate) && !sensitive.test(candidate);
+    });
+}
+const SHARD_DIRECTORIES = [['core', 'changes'], ['commands', 'change'], ['commands', 'changes']];
+// Each real shard directory must exist with its exact case, hold at least one
+// suite and match CHANGES_PATTERN, so the case-only walk cannot pass vacuously.
+function shardDirectoryProblems(testsRoot) {
+    const shard = new RegExp(CHANGES_PATTERN);
+    const problems = [];
+    for (const segments of SHARD_DIRECTORIES) {
+        const label = segments.join('/');
+        let current = testsRoot;
+        let found = true;
+        for (const segment of segments) {
+            // readdirSync keeps the on-disk case even on case-insensitive file systems.
+            if (!fs_1.default.existsSync(current) || !fs_1.default.readdirSync(current).includes(segment)) {
+                found = false;
+                break;
+            }
+            current = path_1.default.join(current, segment);
+        }
+        if (!found) {
+            problems.push(`${label}: missing with this exact case`);
+            continue;
+        }
+        if (!fs_1.default.readdirSync(current).some((entry) => entry.endsWith('.test.ts'))) {
+            problems.push(`${label}: holds no *.test.ts`);
+        }
+        if (!shard.test(`${current}${path_1.default.sep}`)) {
+            problems.push(`${label}: does not match CHANGES_PATTERN`);
+        }
+    }
+    return problems;
+}
+function parseJobs(source) {
+    const parsed = js_yaml_1.default.load(source);
+    expect(parsed?.jobs).toBeDefined();
+    return parsed.jobs;
+}
+function getJob(jobs, name) {
+    const job = jobs[name];
+    expect(job).toBeDefined();
+    expect(Array.isArray(job.steps)).toBe(true);
+    return job;
+}
+function keysOf(value) {
+    return Object.keys(value);
+}
+// The release job publishes only when every test job passed: no if, no
+// continue-on-error, and needs is exactly the three gating jobs in any order.
+function assertReleaseGate(jobs) {
+    const release = getJob(jobs, 'release');
+    expect(keysOf(release)).not.toContain('if');
+    expect(keysOf(release)).not.toContain('continue-on-error');
+    for (const step of release.steps) {
+        expect(keysOf(step)).not.toContain('continue-on-error');
+    }
+    expect(Array.isArray(release.needs)).toBe(true);
+    const needs = release.needs;
+    expect(needs).toHaveLength(RELEASE_GATE.length);
+    expect([...needs].sort()).toEqual(RELEASE_GATE);
+}
+// Gate semantics are asserted on the parsed workflow, so key quoting or escaping
+// cannot hide an if or a continue-on-error. Text is checked only where the exact
+// text is the contract: the run lines and the A1 comment.
+function assertArmPartition(source, gatesRelease) {
     const workflow = source.replace(/\r\n/g, '\n');
-    expect(workflow.match(/^  windows-arm-hot:\s*$/gm)).toHaveLength(1);
-    const [matrixJob, rest] = workflow.split(/^  windows-arm-hot:\s*$/m);
-    expect(rest).toBeDefined();
-    const hotJob = rest.split(/^  [a-z][\w-]*:\s*$/m)[0];
-    // Optional env: (e.g. AWM_BASELINE_REGISTRY_ROOT for RF-5.1 docs contract) may
-    // sit between working-directory and run; release.yml still omits it.
-    expect(matrixJob).toMatch(/- name: Tests?\n        if: matrix\.target != 'win32-arm64'\n        working-directory: cli\n(?:        env:\n(?:          [^\n]+\n)+)?        run: npx jest --runInBand --bail\n/);
-    const remainder = matrixJob.match(/- name: Tests? \(Windows ARM remainder\)\n        if: matrix\.target == 'win32-arm64'\n        working-directory: cli\n(?:        env:\n(?:          [^\n]+\n)+)?        run: ([^\n]+)/)?.[1];
-    expect(remainder).toMatch(/^npx jest --runInBand --bail --testPathIgnorePatterns='[^']+'$/);
-    const ignorePattern = remainder?.match(/--testPathIgnorePatterns='([^']+)'/)?.[1];
-    expect(ignorePattern).toBe(String.raw `node_modules|[/\\]cli[/\\]tests[/\\]commands[/\\]watch[/\\]track-(finalize|freeze)\.test\.ts$`);
+    const jobs = parseJobs(source);
+    const names = keysOf(jobs);
+    const test = getJob(jobs, 'test');
+    const hot = getJob(jobs, 'windows-arm-hot');
+    const changes = getJob(jobs, 'windows-arm-changes');
+    expect(names.indexOf('windows-arm-hot')).toBeGreaterThan(names.indexOf('test'));
+    expect(names.indexOf('windows-arm-changes')).toBe(names.indexOf('windows-arm-hot') + 1);
+    // No gating job tolerates failure, at job or step level.
+    for (const job of [test, hot, changes]) {
+        expect(keysOf(job)).not.toContain('continue-on-error');
+        for (const step of job.steps) {
+            expect(keysOf(step)).not.toContain('continue-on-error');
+        }
+    }
+    // The ARM shards never skip, at job or step level.
+    for (const job of [hot, changes]) {
+        expect(keysOf(job)).not.toContain('if');
+        for (const step of job.steps) {
+            expect(keysOf(step)).not.toContain('if');
+        }
+    }
+    // In the matrix, only the two test steps are guarded, with complementary targets.
+    const guarded = test.steps.filter((step) => keysOf(step).includes('if'));
+    expect(guarded).toHaveLength(2);
+    const [regular, remainder] = guarded;
+    expect(regular.name).toMatch(/^Tests?$/);
+    expect(regular.if).toBe("matrix.target != 'win32-arm64'");
+    expect(regular['working-directory']).toBe('cli');
+    expect(regular.run).toBe('npx jest --runInBand --bail');
+    expect(remainder.name).toMatch(/^Tests? \(Windows ARM remainder\)$/);
+    expect(remainder.if).toBe("matrix.target == 'win32-arm64'");
+    expect(remainder['working-directory']).toBe('cli');
+    const ignorePattern = String(remainder.run).match(/^npx jest --runInBand --bail --testPathIgnorePatterns='([^']+)'$/)?.[1];
+    expect(ignorePattern).toBe(`${HOT_IGNORE}|${CHANGES_PATTERN}`);
+    expect(test.steps.filter((step) => step.uses === 'actions/upload-artifact@v4')).toHaveLength(1);
+    // A1 comment, directly above the remainder step.
+    expect(workflow.split(REMAINDER_COMMENT)).toHaveLength(2);
+    const aroundRemainder = workflow.split(/      - name: Tests? \(Windows ARM remainder\)\n/);
+    expect(aroundRemainder).toHaveLength(2);
+    expect(aroundRemainder[0].endsWith(REMAINDER_COMMENT)).toBe(true);
+    // Both shards share the same setup; only their test step differs.
+    expect(hot['runs-on']).toBe('windows-11-arm');
+    expect(hot.steps.slice(0, -1)).toEqual(SHARD_SETUP);
+    expect(hot.steps.at(-1)).toEqual({ name: HOT_STEP, 'working-directory': 'cli', run: HOT_RUN });
+    expect(changes.steps.at(-1)).toEqual({ name: CHANGES_STEP, 'working-directory': 'cli', run: CHANGES_RUN });
+    expect({ ...changes, steps: changes.steps.slice(0, -1) }).toEqual({ ...hot, steps: hot.steps.slice(0, -1) });
+    if (gatesRelease) {
+        expect(changes.permissions).toEqual({ contents: 'read' });
+    }
+    for (const job of [hot, changes]) {
+        expect(job.steps.some((step) => String(step.uses ?? '').includes('upload-artifact'))).toBe(false);
+        expect(JSON.stringify(job)).not.toContain('secure-fs-win32-arm64');
+    }
+    const lines = workflow.split('\n');
+    expect(lines).toContain(`        run: ${HOT_RUN}`);
+    expect(lines).toContain(`        run: ${CHANGES_RUN}`);
+    // The remainder ignores exactly the hot suites plus what the Change Record shard runs.
     const ignored = new RegExp(ignorePattern);
     for (const separator of ['/', '\\']) {
         const root = ['repo', 'cli', 'tests'].join(separator);
@@ -32,18 +168,100 @@ function assertArmPartition(source) {
             expect(ignored.test([root, 'other', `${suite}.test.ts`].join(separator))).toBe(false);
         }
     }
-    const remainderStep = matrixJob.split(/- name: Tests? \(Windows ARM remainder\)\n/)[1]?.split(/^      - name:/m)[0];
-    expect(remainderStep).toBeDefined();
-    expect(remainderStep).not.toContain('continue-on-error: true');
-    expect(matrixJob.match(/uses: actions\/upload-artifact@v4/g)).toHaveLength(1);
-    expect(hotJob).toContain('runs-on: windows-11-arm');
-    expect(hotJob).toContain('run: npm run native:build');
-    expect(hotJob).toContain('run: npm run native:test-build');
-    expect(hotJob.split('\n')).toContain('        run: npx jest --runTestsByPath tests/commands/watch/track-finalize.test.ts tests/commands/watch/track-freeze.test.ts --runInBand --bail');
-    expect(hotJob).not.toContain('upload-artifact@v4');
-    expect(hotJob).not.toContain('secure-fs-win32-arm64');
-    expect(hotJob).not.toMatch(/^\s*if:/m);
-    expect(hotJob).not.toContain('continue-on-error: true');
+    const shardPattern = String(changes.steps.at(-1)?.run).match(/--testPathPatterns='([^']+)'$/)?.[1];
+    expect(shardPattern).toBe(CHANGES_PATTERN);
+    expect(ignorePattern).toBe(`${HOT_IGNORE}|${shardPattern}`);
+    const shard = new RegExp(shardPattern, 'i');
+    for (const separator of ['/', '\\']) {
+        const root = ['repo', 'cli', 'tests'].join(separator);
+        for (const file of [['core', 'changes', 'x.test.ts'], ['commands', 'change', 'new.test.ts'], ['commands', 'changes', 'list.test.ts']]) {
+            const candidate = [root, ...file].join(separator);
+            expect(shard.test(candidate)).toBe(true);
+            expect(ignored.test(candidate)).toBe(true);
+        }
+        for (const file of [['core', 'changesets', 'x.test.ts'], ['commands', 'changesets', 'x.test.ts'], ['commands', 'watch', 'track-finalize.test.ts']]) {
+            expect(shard.test([root, ...file].join(separator))).toBe(false);
+        }
+        expect(ignored.test([root, 'core', 'changesets', 'x.test.ts'].join(separator))).toBe(false);
+    }
+    if (gatesRelease) {
+        assertReleaseGate(jobs);
+        // CI-2 keeps the comment on the release job's needs line.
+        const releaseText = workflow.slice(workflow.search(/^  release:\n/m));
+        expect(releaseText.match(/^    needs: [^\n]*$/m)?.[0]).toMatch(/ # rojo en cualquier plataforma o shard ARM no publica$/);
+    }
+    else {
+        expect(names).not.toContain('release');
+    }
+}
+// Rewrites the release job's inline `needs` list in the workflow text.
+function rewriteReleaseNeeds(workflow, rewrite) {
+    const header = workflow.search(/^  release:\n/m);
+    expect(header).toBeGreaterThanOrEqual(0);
+    const head = workflow.slice(0, header);
+    const tail = workflow.slice(header).replace(/^(    needs: )\[([^\]\n]*)\]/m, (_line, prefix, list) => `${prefix}[${rewrite(list.split(',').map((job) => job.trim())).join(', ')}]`);
+    return head + tail;
+}
+function permutations(items) {
+    if (items.length <= 1)
+        return [items];
+    return items.flatMap((item, index) => permutations([...items.slice(0, index), ...items.slice(index + 1)]).map((rest) => [item, ...rest]));
+}
+// Every bypass of the partition or the release gate must make assertArmPartition
+// throw: a failed assertion or a mutated text that no longer parses as YAML.
+function assertMutationsRejected(workflow, gates) {
+    const jobLevel = (job, line) => workflow.replace(new RegExp(`^  ${job}:\\n`, 'm'), `  ${job}:\n    ${line}\n`);
+    const inStep = (step, line) => workflow.replace(`      - name: ${step}\n`, `      - name: ${step}\n        ${line}\n`);
+    const mutations = [
+        // Swapped matrix guards.
+        workflow.replace(/if: matrix\.target (?:!=|==) 'win32-arm64'/g, (guard) => guard.includes('!=') ? "if: matrix.target == 'win32-arm64'" : "if: matrix.target != 'win32-arm64'"),
+        // A second producer of the native artifact.
+        workflow.replace('uses: actions/upload-artifact@v4', 'uses: actions/upload-artifact@v4\n      - uses: actions/upload-artifact@v4'),
+        // A remainder that drops more than the shards run.
+        workflow.replace(/(--testPathIgnorePatterns='[^']+)(?=')/, '$1|runner\\.test\\.ts$'),
+        // A shard pattern that differs from the remainder's exclusion.
+        workflow.replace(/(--testPathPatterns='[^']+)changes\?/, '$1changes'),
+        // Masked shard runs.
+        workflow.replace(/(run: npx jest --runTestsByPath [^\n]+ --runInBand --bail)(?=\n)/, '$1; exit 0'),
+        workflow.replace(/(run: npx jest --runInBand --bail --testPathPatterns='[^']+')(?=\n)/, '$1; exit 0'),
+        // Skipped steps or jobs, in any key quoting.
+        inStep(HOT_STEP, 'if: false'),
+        inStep(HOT_STEP, '"if": always()'),
+        inStep(HOT_STEP, "'if': false"),
+        inStep(CHANGES_STEP, 'if: false'),
+        inStep(CHANGES_STEP, '"if": always()'),
+        inStep(CHANGES_STEP, "'if': false"),
+        inStep('Upload native secure-fs artifact', "'if': false"),
+        jobLevel('windows-arm-hot', '"if": always()'),
+        jobLevel('windows-arm-hot', "'if': false"),
+        jobLevel('windows-arm-changes', '"if": always()'),
+        jobLevel('windows-arm-changes', "'if': false"),
+        // Tolerated failures, in any key quoting, escaping or expression form.
+        jobLevel('test', "continue-on-error: ${{ matrix.target == 'win32-arm64' }}"),
+        jobLevel('test', '"continue-on-error": true'),
+        jobLevel('test', '"continue\\x2Don-error": true'),
+        jobLevel('windows-arm-hot', 'continue-on-error: true'),
+        jobLevel('windows-arm-hot', 'continue-on-error: ${{ true }}'),
+        jobLevel('windows-arm-hot', '"continue-on-error": true'),
+        jobLevel('windows-arm-changes', 'continue-on-error: true'),
+        jobLevel('windows-arm-changes', 'continue-on-error: ${{ true }}'),
+        jobLevel('windows-arm-changes', '"continue-on-error": true'),
+        inStep(HOT_STEP, '"continue-on-error": true'),
+        inStep(CHANGES_STEP, "'continue-on-error': true"),
+        workflow.replace(/^(        run: npx jest --runInBand --bail\n)/m, '$1        continue-on-error: true\n'),
+        workflow.replace(/(run: npx jest --runInBand --bail --testPathIgnorePatterns='[^']+'\n)/, '$1        continue-on-error: true\n'),
+        workflow.replace(/(run: npx jest --runInBand --bail --testPathIgnorePatterns='[^']+'\n)/, '$1        continue-on-error: ${{ true }}\n'),
+    ];
+    if (gates) {
+        mutations.push(rewriteReleaseNeeds(workflow, (jobs) => jobs.filter((job) => job !== 'windows-arm-changes')), rewriteReleaseNeeds(workflow, (jobs) => [...jobs, 'windows-arm-changes']), jobLevel('release', 'if: always()'), jobLevel('release', 'if: ${{ !cancelled() }}'), jobLevel('release', '"if": always()'), jobLevel('release', "'if': false"), jobLevel('release', 'continue-on-error: true'), jobLevel('release', '"continue-on-error": true'), 
+        // The needs comment is part of CI-2.
+        workflow.slice(0, workflow.search(/^  release:\n/m))
+            + workflow.slice(workflow.search(/^  release:\n/m)).replace(/^(    needs: [^\n]*?) # rojo en cualquier plataforma o shard ARM no publica$/m, '$1'));
+    }
+    for (const mutated of mutations) {
+        expect(mutated).not.toBe(workflow);
+        expect(() => assertArmPartition(mutated, gates)).toThrow();
+    }
 }
 describe('native release artifacts', () => {
     it('runs each platform suite once without weakening publication', () => {
@@ -54,44 +272,75 @@ describe('native release artifacts', () => {
             expect(workflow).toContain('run: npx jest --runInBand --bail');
         }
         const release = readWorkflow('release.yml');
-        expect(release).toMatch(/release:\s*\n\s*needs: \[test, windows-arm-hot\]/);
+        assertReleaseGate(parseJobs(release));
         for (const target of ['linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64', 'win32-x64', 'win32-arm64']) {
             expect(release).toContain(`target: ${target}`);
         }
         expect(release).toContain('cancel-in-progress: false');
     });
-    it('partitions the two hot ARM suites without duplicating the native artifact', () => {
+    it('partitions the hot and Change Record ARM shards without duplicating the native artifact', () => {
         for (const name of ['ci.yml', 'release.yml']) {
             const workflow = readWorkflow(name);
-            assertArmPartition(workflow);
+            assertArmPartition(workflow, name === 'release.yml');
         }
     });
     it('checks the same partition after a Windows CRLF checkout', () => {
         for (const name of ['ci.yml', 'release.yml']) {
             const workflow = readWorkflow(name);
-            assertArmPartition(workflow.replace(/\n/g, '\r\n'));
+            assertArmPartition(workflow.replace(/\n/g, '\r\n'), name === 'release.yml');
         }
     });
-    it('rejects swapped matrix guards, non-gating hot tests and duplicate artifacts', () => {
+    it('rejects swapped matrix guards, non-gating ARM shards, drifted partitions and duplicate artifacts', () => {
         for (const name of ['ci.yml', 'release.yml']) {
-            const workflow = readWorkflow(name);
-            const swapped = workflow.replace(/if: matrix\.target (?:!=|==) 'win32-arm64'/g, (guard) => guard.includes('!=') ? "if: matrix.target == 'win32-arm64'" : "if: matrix.target != 'win32-arm64'");
-            const nonGating = workflow.replace('  windows-arm-hot:\n', '  windows-arm-hot:\n    continue-on-error: true\n');
-            const duplicateArtifact = workflow.replace('uses: actions/upload-artifact@v4', 'uses: actions/upload-artifact@v4\n      - uses: actions/upload-artifact@v4');
-            const broadIgnore = workflow.replace(/(--testPathIgnorePatterns='[^']+)(?=')/, '$1|runner\\.test\\.ts$');
-            const skippedHot = workflow.replace('      - name: Test hot Windows ARM suites\n', '      - name: Test hot Windows ARM suites\n        if: false\n');
-            const nonGatingRemainder = workflow.replace(/(run: npx jest --runInBand --bail --testPathIgnorePatterns='[^']+'\n)/, '$1        continue-on-error: true\n');
-            const maskedHot = workflow.replace(/(run: npx jest --runTestsByPath [^\n]+ --runInBand --bail)(?=\n)/, '$1; exit 0');
-            for (const mutated of [swapped, nonGating, duplicateArtifact, broadIgnore, skippedHot, nonGatingRemainder, maskedHot]) {
-                expect(mutated).not.toBe(workflow);
+            assertMutationsRejected(readWorkflow(name), name === 'release.yml');
+        }
+    });
+    it('keeps the whole self-test green when release needs is reordered', () => {
+        const workflow = readWorkflow('release.yml');
+        let current = [];
+        rewriteReleaseNeeds(workflow, (jobs) => (current = jobs));
+        const reorderedJobs = permutations(current).find((jobs) => jobs.join() !== current.join());
+        expect(reorderedJobs).toBeDefined();
+        const reordered = rewriteReleaseNeeds(workflow, () => reorderedJobs);
+        expect(reordered).not.toBe(workflow);
+        expect(() => assertArmPartition(reordered, true)).not.toThrow();
+        expect(() => assertMutationsRejected(reordered, true)).not.toThrow();
+    });
+    it('reports a shard directory that is missing, renamed by case or holds no suite', () => {
+        const tmp = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-arm-shard-'));
+        try {
+            const testsRoot = path_1.default.join(tmp, 'cli', 'tests');
+            for (const segments of SHARD_DIRECTORIES) {
+                fs_1.default.mkdirSync(path_1.default.join(testsRoot, ...segments), { recursive: true });
+                fs_1.default.writeFileSync(path_1.default.join(testsRoot, ...segments, 'x.test.ts'), '');
             }
-            expect(() => assertArmPartition(swapped)).toThrow();
-            expect(() => assertArmPartition(nonGating)).toThrow();
-            expect(() => assertArmPartition(duplicateArtifact)).toThrow();
-            expect(() => assertArmPartition(broadIgnore)).toThrow();
-            expect(() => assertArmPartition(skippedHot)).toThrow();
-            expect(() => assertArmPartition(nonGatingRemainder)).toThrow();
-            expect(() => assertArmPartition(maskedHot)).toThrow();
+            expect(shardDirectoryProblems(testsRoot)).toEqual([]);
+            fs_1.default.renameSync(path_1.default.join(testsRoot, 'core', 'changes'), path_1.default.join(testsRoot, 'core', 'Changes'));
+            expect(shardDirectoryProblems(testsRoot)).toEqual([expect.stringContaining('core/changes')]);
+            fs_1.default.renameSync(path_1.default.join(testsRoot, 'core', 'Changes'), path_1.default.join(testsRoot, 'core', 'changes'));
+            fs_1.default.renameSync(path_1.default.join(testsRoot, 'commands', 'change', 'x.test.ts'), path_1.default.join(testsRoot, 'commands', 'change', 'helpers.ts'));
+            expect(shardDirectoryProblems(testsRoot)).toEqual([expect.stringContaining('commands/change')]);
+            fs_1.default.rmSync(path_1.default.join(testsRoot, 'commands', 'changes'), { recursive: true });
+            expect(shardDirectoryProblems(testsRoot)).toHaveLength(2);
+        }
+        finally {
+            fs_1.default.rmSync(tmp, { recursive: true, force: true });
+        }
+    });
+    it('flags test directories that only the case-insensitive shard pattern selects', () => {
+        expect(caseOnlyShardPaths(['repo/cli/tests/core/Changes'], CHANGES_PATTERN)).toEqual(['repo/cli/tests/core/Changes']);
+        expect(caseOnlyShardPaths(['repo\\cli\\tests\\commands\\CHANGE'], CHANGES_PATTERN)).toEqual(['repo\\cli\\tests\\commands\\CHANGE']);
+        expect(caseOnlyShardPaths(['repo/cli/tests/core/changes', 'repo/cli/tests/commands/change', 'repo/cli/tests/core/Changesets'], CHANGES_PATTERN)).toEqual([]);
+    });
+    it('has no test directory selected by the shard but kept by the remainder through case alone', () => {
+        const testsRoot = path_1.default.join(CLI_ROOT, 'tests');
+        const directories = fs_1.default.readdirSync(testsRoot, { recursive: true })
+            .map((relative) => path_1.default.join(testsRoot, relative))
+            .filter((candidate) => fs_1.default.statSync(candidate).isDirectory());
+        expect(shardDirectoryProblems(testsRoot)).toEqual([]);
+        const flagged = caseOnlyShardPaths(directories, CHANGES_PATTERN);
+        if (flagged.length > 0) {
+            throw new Error(`Case-only Change Record directories would run in both ARM shards: ${flagged.join(', ')}`);
         }
     });
     it('keeps native prebuilds generated instead of versioned source', () => {

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.2",
   "main": "dist/src/index.js",
   "bin": {
     "awm": "./dist/src/index.js"