agentic-workflow-manager 9.3.0 → 9.4.1

package/dist/tests/core/plan/validate.test.js

@@ -0,0 +1,437 @@
+"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 child_process_1 = require("child_process");
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const json_1 = require("../../../src/core/plan/json");
+const validate_1 = require("../../../src/core/plan/validate");
+jest.mock('child_process', () => ({ exec: jest.fn(), execFileSync: jest.fn(), execSync: jest.fn(), spawn: jest.fn(), spawnSync: jest.fn() }));
+const START = '<!-- AWM:COMPACT-SLICES:START v1 -->';
+const END = '<!-- AWM:COMPACT-SLICES:END v1 -->';
+function expectApprovedPlanValid(report) {
+    if (report.state !== 'valid') {
+        const diagnostics = 'diagnostics' in report
+            ? report.diagnostics.map(({ code, message }) => `${code}: ${message}`).join('; ')
+            : 'none';
+        throw new Error(`approved compact plan validation failed: state=${report.state}; diagnostics=${diagnostics}`);
+    }
+    expect(report.schema).toBe('compact-slices/v1');
+}
+function fixture(root, mutate) {
+    fs_1.default.mkdirSync(path_1.default.join(root, 'docs'), { recursive: true });
+    fs_1.default.writeFileSync(path_1.default.join(root, 'docs', 'source.md'), '## Source\nKnown fact\n');
+    const manifest = {
+        schema: 'compact-slices/v1', planId: 'valid-plan', requirements: ['R4-VAL-2'],
+        sources: [{ id: 'SRC-ONE', path: 'docs/source.md', locator: '## Source', fact: 'Known fact' }],
+        commands: [{ id: 'CMD-ONE', program: 'npm', args: ['test'], covers: ['R4-VAL-2'] }],
+        slices: [{ id: 'S1', title: 'Validate one thing', requirements: ['R4-VAL-2'], dependsOn: [], sectionAnchor: 'slice-s1', sources: ['SRC-ONE'], redCommands: ['CMD-ONE'], greenCommands: ['CMD-ONE'], reviewEvidence: ['specification', 'code-quality'], risk: 'bounded', fallback: ['Use a reviewed fallback'] }],
+        closureCommands: ['CMD-ONE'],
+    };
+    mutate?.(manifest);
+    const markdown = `${START}\n${JSON.stringify(manifest, null, 2)}\n${END}\n\n<a id="slice-s1"></a>\n### Slice S1: Validate one thing\n\n#### Surfaces\n\nOne surface.\n\n#### Implementation\n\nOne implementation.\n\n#### Edge cases\n\nOne edge case.\n\n#### Evidence\n\nOne evidence item.\n\n#### Fallback\n\nOne fallback.\n`;
+    const plan = path_1.default.join(root, 'plan.md');
+    fs_1.default.writeFileSync(plan, markdown);
+    return plan;
+}
+describe('validatePlanFile', () => {
+    let root;
+    beforeEach(() => { root = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-plan-')); });
+    afterEach(() => { fs_1.default.rmSync(root, { recursive: true, force: true }); });
+    test('accepts a valid compact plan without modifying it', () => {
+        const plan = fixture(root);
+        const before = fs_1.default.readFileSync(plan, 'utf8');
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'valid', schema: 'compact-slices/v1' });
+        expect(fs_1.default.readFileSync(plan, 'utf8')).toBe(before);
+    });
+    test('accepts a valid compact plan converted to CRLF', () => {
+        const plan = fixture(root);
+        fs_1.default.writeFileSync(plan, fs_1.default.readFileSync(plan, 'utf8').replace(/\n/g, '\r\n'));
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'valid', schema: 'compact-slices/v1' });
+    });
+    test('accepts a contained plan when path.relative returns Windows separators', () => {
+        const plan = fixture(root);
+        const nestedPlan = path_1.default.join(root, 'docs', 'plan.md');
+        fs_1.default.renameSync(plan, nestedPlan);
+        const nativeRelative = path_1.default.relative;
+        const relative = jest.spyOn(path_1.default, 'relative');
+        relative.mockImplementation((from, to) => {
+            const result = nativeRelative(from, to);
+            return from === root && to === nestedPlan ? result.replace(/\//g, '\\') : result;
+        });
+        try {
+            expect((0, validate_1.validatePlanFile)(nestedPlan, root)).toMatchObject({ state: 'valid', schema: 'compact-slices/v1' });
+        }
+        finally {
+            relative.mockRestore();
+        }
+    });
+    test('accepts the approved plan with cross-cutting command coverage', () => {
+        const repositoryRoot = path_1.default.resolve(__dirname, '../../../..');
+        expectApprovedPlanValid((0, validate_1.validatePlanFile)('docs/plans/2026-08-26-r4a-compact-plan-cli-plan.md', repositoryRoot));
+    });
+    test('performs no execution, network request, model work, grouping, or rewrite', () => {
+        const plan = fixture(root);
+        const before = fs_1.default.readFileSync(plan, 'utf8');
+        const network = jest.spyOn(global, 'fetch');
+        const rewrite = jest.spyOn(fs_1.default, 'writeFileSync');
+        try {
+            const report = (0, validate_1.validatePlanFile)(plan, root);
+            expect(report).toMatchObject({ state: 'valid', manifest: { slices: [expect.objectContaining({ id: 'S1', requirements: ['R4-VAL-2'] })] } });
+            expect(child_process_1.execFileSync).not.toHaveBeenCalled();
+            expect(child_process_1.exec).not.toHaveBeenCalled();
+            expect(child_process_1.execSync).not.toHaveBeenCalled();
+            expect(child_process_1.spawn).not.toHaveBeenCalled();
+            expect(child_process_1.spawnSync).not.toHaveBeenCalled();
+            expect(network).not.toHaveBeenCalled();
+            expect(rewrite).not.toHaveBeenCalled();
+            expect(fs_1.default.readFileSync(plan, 'utf8')).toBe(before);
+        }
+        finally {
+            network.mockRestore();
+            rewrite.mockRestore();
+        }
+    });
+    test('rejects invalid UTF-8 bytes before interpreting plan text', () => {
+        const plan = path_1.default.join(root, 'invalid-utf8.md');
+        fs_1.default.writeFileSync(plan, Buffer.concat([Buffer.from(`${START}\n`), Buffer.from([0x80]), Buffer.from(`\n${END}\n`)]));
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_ENCODING' })] });
+    });
+    test('rejects a plan reached through a symlinked parent directory', () => {
+        const outside = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-plan-outside-'));
+        try {
+            const plan = fixture(outside);
+            fs_1.default.symlinkSync(outside, path_1.default.join(root, 'linked-parent'));
+            expect((0, validate_1.validatePlanFile)(path_1.default.join('linked-parent', path_1.default.basename(plan)), root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_PATH_UNSAFE' })] });
+        }
+        finally {
+            fs_1.default.rmSync(outside, { recursive: true, force: true });
+        }
+    });
+    test('rejects partial markers and identifies a safely readable future schema', () => {
+        const partial = path_1.default.join(root, 'partial.md');
+        fs_1.default.writeFileSync(partial, `${START}\n# incomplete`);
+        expect((0, validate_1.validatePlanFile)(partial, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_MARKERS' })] });
+        const future = path_1.default.join(root, 'future.md');
+        fs_1.default.writeFileSync(future, `${START}\n{"schema":"compact-slices/v2"}\n${END}`);
+        expect((0, validate_1.validatePlanFile)(future, root)).toMatchObject({ state: 'unsupported', schema: 'compact-slices/v2' });
+    });
+    test('keeps a future schema behind partial markers invalid rather than unsupported', () => {
+        const plan = path_1.default.join(root, 'partial-future.md');
+        fs_1.default.writeFileSync(plan, `${START}\n{"schema":"compact-slices/v2"}`);
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'unsupported', schema: 'compact-slices/v2' });
+    });
+    test('applies scalar limits before classifying a future schema as unsupported', () => {
+        const plan = path_1.default.join(root, 'future-too-large.md');
+        fs_1.default.writeFileSync(plan, `${START}\n{"schema":"compact-slices/${'v'.repeat(4097)}"}\n${END}`);
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_LIMIT' })] });
+    });
+    test('rejects a duplicate JSON key with a stable diagnostic', () => {
+        const plan = path_1.default.join(root, 'plan.md');
+        fs_1.default.writeFileSync(plan, `${START}\n{"schema":"compact-slices/v1","schema":"compact-slices/v1"}\n${END}`);
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_JSON' })] });
+    });
+    test('rejects JSON keys made equivalent by slash escaping', () => {
+        expect(() => (0, json_1.parseJsonNoDuplicate)('{"a/b":1,"a\\/b":2}')).toThrow('duplicate key');
+    });
+    test.each([
+        ['requirement', (m) => { m.requirements = [['R4-VAL-2']]; }, 'PLAN_SHAPE'],
+        ['source', (m) => { m.sources[0].id = ['SRC-ONE']; }, 'PLAN_SOURCE_SHAPE'],
+        ['command', (m) => { m.commands[0].id = ['CMD-ONE']; }, 'PLAN_COMMAND_SHAPE'],
+        ['slice', (m) => { m.slices[0].id = ['S1']; }, 'PLAN_SLICE_SHAPE'],
+    ])('rejects a non-string %s ID before applying ID syntax validation', (_name, mutate, code) => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, mutate), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code })] });
+    });
+    test('rejects slices with IDs that are semantically duplicate after coercion', () => {
+        const plan = fixture(root, (m) => {
+            m.requirements = ['R4-VAL-2', 'R4-VAL-3'];
+            m.commands.push({ id: 'CMD-TWO', program: 'npm', args: ['run', 'lint'], covers: ['R4-VAL-3'] });
+            m.slices.push({ id: ['S1'], title: 'Validate one thing', requirements: ['R4-VAL-3'], dependsOn: [], sectionAnchor: 'slice-s1', sources: ['SRC-ONE'], redCommands: ['CMD-TWO'], greenCommands: ['CMD-TWO'], reviewEvidence: ['specification', 'code-quality'], risk: 'bounded', fallback: ['Use a reviewed fallback'] });
+            m.closureCommands = ['CMD-ONE', 'CMD-TWO'];
+        });
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_SLICE_SHAPE' })] });
+    });
+    test.each([
+        ['unknown field', (m) => { m.extra = true; }, 'PLAN_UNKNOWN_FIELD'],
+        ['missing field', (m) => { delete m.planId; }, 'PLAN_MISSING_FIELD'],
+        ['limit', (m) => { m.requirements = Array.from({ length: 257 }, (_, i) => `R${i}`); }, 'PLAN_LIMIT'],
+        ['duplicate owner', (m) => { m.slices[0].requirements = ['R4-VAL-2', 'R4-VAL-2']; }, 'PLAN_REQUIREMENT_OWNER'],
+        ['orphan requirement', (m) => { m.requirements = ['R4-VAL-2', 'R4-VAL-5']; }, 'PLAN_REQUIREMENT_OWNER'],
+        ['cycle', (m) => { m.slices[0].dependsOn = ['S1']; }, 'PLAN_DEPENDENCY'],
+        ['review roles', (m) => { m.slices[0].reviewEvidence = ['specification', 'specification']; }, 'PLAN_REVIEW_EVIDENCE'],
+        ['shell argv', (m) => { m.commands[0].program = 'sh'; m.commands[0].args = ['-c', 'echo x']; }, 'PLAN_COMMAND_UNSAFE'],
+    ])('rejects %s with a stable diagnostic', (_name, mutate, code) => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, mutate), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code })] });
+    });
+    test('rejects source symlinks and missing locators', () => {
+        const linked = path_1.default.join(root, 'docs', 'linked.md');
+        fs_1.default.mkdirSync(path_1.default.dirname(linked), { recursive: true });
+        fs_1.default.symlinkSync(path_1.default.join(root, 'docs', 'source.md'), linked);
+        const symlink = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.sources[0].path = 'docs/linked.md'; }), root);
+        expect(symlink).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_SOURCE_UNSAFE' })] });
+        const locator = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.sources[0].locator = 'absent'; }), root);
+        expect(locator).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_SOURCE_LOCATOR' })] });
+    });
+    test('rejects an oversized source before reading its body', () => {
+        const plan = fixture(root);
+        const source = path_1.default.join(root, 'docs', 'source.md');
+        fs_1.default.writeFileSync(source, Buffer.alloc(1024 * 1024 + 1, 0x61));
+        const read = jest.spyOn(fs_1.default, 'readFileSync');
+        try {
+            expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_SOURCE_LIMIT' })] });
+            expect(read.mock.calls.some(([file]) => file === source)).toBe(false);
+        }
+        finally {
+            read.mockRestore();
+        }
+    });
+    test.each([
+        ['invalid UTF-8 source', (root) => fs_1.default.writeFileSync(path_1.default.join(root, 'docs', 'source.md'), Buffer.from([0x80])), 'PLAN_SOURCE_ENCODING'],
+        ['multiline locator', (_root) => undefined, 'PLAN_SOURCE_SHAPE'],
+    ])('rejects %s', (_name, prepare, code) => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => {
+            prepare(root);
+            if (code === 'PLAN_SOURCE_SHAPE')
+                m.sources[0].locator = 'Source\nKnown';
+        }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code })] });
+    });
+    test.each(['', '.', '..', '/tmp/source.md', 'C:\\source.md', 'docs\\source.md', 'docs/../source.md'])('rejects adversarial source path %j', (sourcePath) => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.sources[0].path = sourcePath; }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_SOURCE_SHAPE' })] });
+    });
+    test.each(['redCommands', 'greenCommands'])('requires a nonempty %s list', (field) => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.slices[0][field] = []; }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_SLICE_SHAPE' })] });
+    });
+    test('rejects a slice requirement absent from the top-level requirements', () => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => {
+            m.requirements = [];
+            m.slices[0].requirements = ['R4-VAL-9'];
+            m.commands[0].covers = [];
+        }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_SLICE_SHAPE' })] });
+    });
+    test('requires a non-whitespace fallback condition', () => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.slices[0].fallback = ['   ']; }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_SLICE_SHAPE' })] });
+    });
+    test.each(['locator', 'fact'])('requires source %s to contain non-whitespace text', (field) => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.sources[0][field] = ' '; }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_SOURCE_SHAPE' })] });
+    });
+    test('bounds sectionAnchor as a scalar string', () => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.slices[0].sectionAnchor = 'a'.repeat(4097); }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_SLICE_SHAPE' })] });
+    });
+    test('treats a document without any optimized signal as legacy', () => {
+        const plan = path_1.default.join(root, 'legacy.md');
+        fs_1.default.writeFileSync(plan, '# Legacy plan\n');
+        expect((0, validate_1.validatePlanFile)(plan, root)).toEqual({ state: 'legacy' });
+    });
+    test('does not classify an escaped future schema signal as legacy', () => {
+        const plan = path_1.default.join(root, 'escaped-future.md');
+        fs_1.default.writeFileSync(plan, '{"schema":"compact-slices\\u002fv2"}');
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'unsupported', schema: 'compact-slices/v2' });
+    });
+    test.each([
+        ['escaped schema key', '{"\\u0073chema":"compact-slices/v2"}'],
+        ['escaped schema hyphen', '{"schema":"compact\\u002dslices/v2"}'],
+    ])('does not classify a future schema with an %s as legacy', (_name, manifest) => {
+        const plan = path_1.default.join(root, 'escaped-future-schema.md');
+        fs_1.default.writeFileSync(plan, manifest);
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'unsupported', schema: 'compact-slices/v2' });
+    });
+    test('does not classify an escaped future schema embedded in Markdown without markers as legacy', () => {
+        const plan = path_1.default.join(root, 'embedded-escaped-future.md');
+        fs_1.default.writeFileSync(plan, '# Plan notes\n\n```json\n{"\\u0073chema":"compact\\u002dslices\\u002fv2"}\n```\n');
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'unsupported', schema: 'compact-slices/v2' });
+    });
+    test('rejects an unparseable escaped compact schema embedded in Markdown rather than treating it as legacy', () => {
+        const plan = path_1.default.join(root, 'embedded-escaped-malformed.md');
+        fs_1.default.writeFileSync(plan, '# Plan notes\n\n{"\\u0073chema":"compact\\u002dslices\\u002fv2"\n');
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_MARKERS' })] });
+    });
+    test('rejects a markerless malformed compact schema with an escaped JSON slash', () => {
+        const plan = path_1.default.join(root, 'escaped-slash-malformed.md');
+        fs_1.default.writeFileSync(plan, '{"schema":"compact-slices\\/v2"');
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_MARKERS' })] });
+    });
+    test('rejects an escaped current schema without compact markers', () => {
+        const plan = path_1.default.join(root, 'escaped-current-schema.md');
+        fs_1.default.writeFileSync(plan, '{"\\u0073chema":"compact\\u002dslices/v1"}');
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_MARKERS' })] });
+    });
+    test('rejects duplicate trace references and an oversized plan id', () => {
+        const duplicate = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.slices[0].sources = ['SRC-ONE', 'SRC-ONE']; }), root);
+        expect(duplicate).toMatchObject({ state: 'invalid' });
+        const planId = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.planId = 'a'.repeat(4097); }), root);
+        expect(planId).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_LIMIT' })] });
+    });
+    test('requires the slice heading immediately after its anchor', () => {
+        const plan = fixture(root);
+        fs_1.default.writeFileSync(plan, fs_1.default.readFileSync(plan, 'utf8').replace('<a id="slice-s1"></a>\n', '<a id="slice-s1"></a>\nintervening text\n'));
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_MARKDOWN_HEADING' })] });
+    });
+    test('rejects a blank line between the slice anchor and heading', () => {
+        const plan = fixture(root);
+        fs_1.default.writeFileSync(plan, fs_1.default.readFileSync(plan, 'utf8').replace('<a id="slice-s1"></a>\n', '<a id="slice-s1"></a>\n\n'));
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_MARKDOWN_HEADING' })] });
+    });
+    test('rejects a slice heading with a suffix beyond the manifest title', () => {
+        const plan = fixture(root);
+        fs_1.default.writeFileSync(plan, fs_1.default.readFileSync(plan, 'utf8').replace('### Slice S1: Validate one thing\n', '### Slice S1: Validate one thing extra\n'));
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_MARKDOWN_HEADING' })] });
+    });
+    test('rejects a repeated required Markdown subsection', () => {
+        const plan = fixture(root);
+        fs_1.default.writeFileSync(plan, fs_1.default.readFileSync(plan, 'utf8').replace('#### Fallback', '#### Evidence\n\nDuplicate evidence.\n\n#### Fallback'));
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_MARKDOWN_SECTION' })] });
+    });
+    test('ignores apparent slice delimiters and subsections inside fenced code blocks', () => {
+        const plan = fixture(root);
+        fs_1.default.writeFileSync(plan, fs_1.default.readFileSync(plan, 'utf8').replace('#### Fallback', '```markdown\n### Slice S99: Example only\n#### Surfaces\n#### Implementation\n#### Edge cases\n#### Evidence\n#### Fallback\n```\n\n#### Fallback'));
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'valid' });
+    });
+    test('rejects an additional slice heading that is not immediately anchored', () => {
+        const plan = fixture(root);
+        fs_1.default.appendFileSync(plan, '\n### Slice S1: Validate one thing\n');
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_MARKDOWN_HEADING' })] });
+    });
+    test.each(['TODO', 'TBD', 'placeholder', 'draft'])('rejects incomplete Markdown sentinel %s', (sentinel) => {
+        const plan = fixture(root);
+        fs_1.default.writeFileSync(plan, fs_1.default.readFileSync(plan, 'utf8').replace('One evidence item.', sentinel));
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_MARKDOWN_SECTION' })] });
+    });
+    test('rejects a contained command file without an executable mode', () => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => {
+            fs_1.default.writeFileSync(path_1.default.join(root, 'docs', 'program'), 'echo inert\n', { mode: 0o644 });
+            m.commands[0].program = 'docs/program';
+        }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_COMMAND_UNSAFE' })] });
+    });
+    test.each([
+        ['env wrapper', 'env', ['sh', '-c', 'echo safe']],
+        ['node interpreter', 'node', ['-e', 'process.exit()']],
+        ['busybox launcher', 'busybox', ['sh', '-c', 'echo safe']],
+    ])('rejects nested shell launcher %s', (_name, program, args) => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.commands[0].program = program; m.commands[0].args = args; }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_COMMAND_UNSAFE' })] });
+    });
+    test.each(['node-v22', 'nodejs-20', 'python3.12', 'bash-static', 'busybox-musl'])('rejects versioned launcher %s', (program) => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.commands[0].program = program; }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_COMMAND_UNSAFE' })] });
+    });
+    test.each(['cmd.exe', 'powershell.exe', 'pwsh.exe', 'wscript.exe', 'cscript.exe'])('rejects Windows launcher %s', (program) => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.commands[0].program = program; }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_COMMAND_UNSAFE' })] });
+    });
+    test.each(['bin/bash', 'tools/cmd.exe'])('rejects path-qualified interpreter launcher %s', (program) => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.commands[0].program = program; }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_COMMAND_UNSAFE' })] });
+    });
+    test.each(['FiSh.ExE', 'tools/EnV.eXe'])('rejects case-insensitive launcher %s even with a safe relative path', (program) => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => {
+            if (program.includes('/')) {
+                fs_1.default.mkdirSync(path_1.default.join(root, 'tools'), { recursive: true });
+                fs_1.default.writeFileSync(path_1.default.join(root, 'tools', 'EnV.eXe'), 'inert executable', { mode: 0o755 });
+            }
+            m.commands[0].program = program;
+        }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_COMMAND_UNSAFE' })] });
+    });
+    test.each(['py.exe', 'pythonw.exe', 'deno.exe', 'bun.exe', 'ruby3.3', 'perl5.38', 'ash', 'csh', 'tcsh'])('rejects interpreter family %s', (program) => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.commands[0].program = program; }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_COMMAND_UNSAFE' })] });
+    });
+    test('rejects a Windows path-like program as a bare executable', () => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.commands[0].program = 'C:\\tools\\safe.exe'; }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_COMMAND_UNSAFE' })] });
+    });
+    test('rejects a Windows drive-relative program', () => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.commands[0].program = 'C:cmd.exe'; }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_COMMAND_UNSAFE' })] });
+    });
+    test('applies Windows contained executable semantics and still denies symlinks', () => {
+        const platform = Object.getOwnPropertyDescriptor(process, 'platform');
+        Object.defineProperty(process, 'platform', { configurable: true, value: 'win32' });
+        try {
+            const executable = (0, validate_1.validatePlanFile)(fixture(root, (m) => {
+                fs_1.default.writeFileSync(path_1.default.join(root, 'docs', 'safe.exe'), 'inert executable');
+                m.commands[0].program = 'docs/safe.exe';
+            }), root);
+            expect(executable).toMatchObject({ state: 'valid' });
+            const symlink = (0, validate_1.validatePlanFile)(fixture(root, (m) => {
+                fs_1.default.writeFileSync(path_1.default.join(root, 'docs', 'safe.exe'), 'inert executable');
+                fs_1.default.symlinkSync(path_1.default.join(root, 'docs', 'safe.exe'), path_1.default.join(root, 'docs', 'linked.exe'));
+                m.commands[0].program = 'docs/linked.exe';
+            }), root);
+            expect(symlink).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_COMMAND_UNSAFE' })] });
+        }
+        finally {
+            if (platform)
+                Object.defineProperty(process, 'platform', platform);
+        }
+    });
+    test('rejects duplicate command coverage', () => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m.commands[0].covers = ['R4-VAL-2', 'R4-VAL-2']; }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_COMMAND_SHAPE' })] });
+    });
+    test('rejects command coverage unrelated to every referencing slice', () => {
+        const plan = fixture(root, (m) => {
+            m.requirements = ['R4-VAL-2', 'R4-VAL-3'];
+            m.commands.push({ id: 'CMD-TWO', program: 'npm', args: ['run', 'lint'], covers: ['R4-VAL-2'] });
+            m.slices.push({ id: 'S2', title: 'Validate two things', requirements: ['R4-VAL-3'], dependsOn: [], sectionAnchor: 'slice-s2', sources: ['SRC-ONE'], redCommands: ['CMD-TWO'], greenCommands: ['CMD-TWO'], reviewEvidence: ['specification', 'code-quality'], risk: 'bounded', fallback: ['Use a reviewed fallback'] });
+        });
+        fs_1.default.appendFileSync(plan, '\n<a id="slice-s2"></a>\n### Slice S2: Validate two things\n\n#### Surfaces\n\nOne surface.\n\n#### Implementation\n\nOne implementation.\n\n#### Edge cases\n\nOne edge case.\n\n#### Evidence\n\nOne evidence item.\n\n#### Fallback\n\nOne fallback.\n');
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid' });
+    });
+    test('rejects requirement coverage executed only by a different slice', () => {
+        const plan = fixture(root, (m) => {
+            m.requirements = ['R4-VAL-2', 'R4-VAL-3'];
+            m.commands[0].covers = ['R4-VAL-2'];
+            m.commands.push({ id: 'CMD-TWO', program: 'npm', args: ['run', 'lint'], covers: ['R4-VAL-2', 'R4-VAL-3'] });
+            m.commands.push({ id: 'CMD-THREE', program: 'npm', args: ['run', 'build'], covers: [] });
+            m.slices[0].redCommands.push('CMD-TWO');
+            m.slices[0].greenCommands.push('CMD-TWO');
+            m.slices.push({ id: 'S2', title: 'Validate two things', requirements: ['R4-VAL-3'], dependsOn: [], sectionAnchor: 'slice-s2', sources: ['SRC-ONE'], redCommands: ['CMD-THREE'], greenCommands: ['CMD-THREE'], reviewEvidence: ['specification', 'code-quality'], risk: 'bounded', fallback: ['Use a reviewed fallback'] });
+            m.closureCommands = ['CMD-ONE', 'CMD-TWO', 'CMD-THREE'];
+        });
+        fs_1.default.appendFileSync(plan, '\n<a id="slice-s2"></a>\n### Slice S2: Validate two things\n\n#### Surfaces\n\nOne surface.\n\n#### Implementation\n\nOne implementation.\n\n#### Edge cases\n\nOne edge case.\n\n#### Evidence\n\nOne evidence item.\n\n#### Fallback\n\nOne fallback.\n');
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_REQUIREMENT_COVER' })] });
+    });
+    test('rejects a command with neither requirement coverage nor closure membership', () => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => {
+            m.commands[0].covers = [];
+            m.closureCommands = [];
+        }), root);
+        expect(report).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_COMMAND_SHAPE' })] });
+    });
+    test.each(['requirements', 'sources', 'commands', 'slices', 'closureCommands'])('requires a nonempty v1 manifest %s collection', (field) => {
+        const report = (0, validate_1.validatePlanFile)(fixture(root, (m) => { m[field] = []; }), root);
+        expect(report).toMatchObject({ state: 'invalid' });
+    });
+    test('recognizes a parseable future schema when only the END marker is broken', () => {
+        const plan = path_1.default.join(root, 'future-missing-end.md');
+        fs_1.default.writeFileSync(plan, `${START}\n{"schema":"compact-slices/v2"}\n`);
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'unsupported', schema: 'compact-slices/v2' });
+    });
+    test('accepts CRLF Markdown with nested headings and fenced code in a required section', () => {
+        const plan = fixture(root);
+        const markdown = fs_1.default.readFileSync(plan, 'utf8')
+            .replace('One implementation.', 'Implementation prose.\n\n##### Nested detail\n\n```ts\n#### Not a real section\nconst value = true;\n```\n\nMore implementation prose.')
+            .replace(/\n/g, '\r\n');
+        fs_1.default.writeFileSync(plan, markdown);
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'valid', schema: 'compact-slices/v1' });
+    });
+    test('does not classify a malformed future schema behind one broken marker as unsupported', () => {
+        const plan = path_1.default.join(root, 'partial-future-malformed.md');
+        fs_1.default.writeFileSync(plan, `${START}\n{"schema":"compact-slices/v2"`);
+        expect((0, validate_1.validatePlanFile)(plan, root)).toMatchObject({ state: 'invalid', diagnostics: [expect.objectContaining({ code: 'PLAN_MARKERS' })] });
+    });
+});

package/dist/tests/integration/preflight-json-pipe.e2e.test.js

@@ -10,6 +10,44 @@ const path_1 = __importDefault(require("path"));
 const crypto_1 = __importDefault(require("crypto"));
 const cliRoot = path_1.default.resolve(__dirname, '../..');
 const bin = path_1.default.join(cliRoot, 'dist', 'src', 'index.js');
+function wait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+test.each([
+    ['plain preflight', ['preflight']],
+    ['JSON preflight', ['preflight', '--json']],
+    ['JSON sensor-verification preflight', ['preflight', '--verify-sensors', '--json']],
+])('%s never starts the passive update worker', async (_name, args) => {
+    const root = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-preflight-update-'));
+    const project = path_1.default.join(root, 'project');
+    const awmHome = path_1.default.join(root, 'awm-home');
+    const fetchStub = path_1.default.join(root, 'fetch-stub.cjs');
+    const updateCache = path_1.default.join(awmHome, 'update-check.json');
+    // The worker inherits NODE_OPTIONS. A deterministic immediate response makes a
+    // pre-fix worker write observable without relying on the network or a timeout.
+    fs_1.default.writeFileSync(fetchStub, "global.fetch = async () => ({ ok: true, json: async () => ({ version: '999.0.0' }) });\n");
+    fs_1.default.mkdirSync(project, { recursive: true });
+    try {
+        const result = (0, child_process_1.spawnSync)(process.execPath, [bin, ...args], {
+            cwd: project,
+            encoding: 'utf8',
+            env: {
+                ...process.env,
+                AWM_HOME: awmHome,
+                AWM_NO_UPDATE_CHECK: '',
+                NODE_OPTIONS: `${process.env.NODE_OPTIONS ?? ''} --require=${fetchStub}`.trim(),
+            },
+        });
+        expect(result.status).toBe(1);
+        // A spawned worker using the deterministic response above writes well inside
+        // this window; the delay also verifies it was never merely deferred.
+        await wait(1_000);
+        expect(fs_1.default.existsSync(updateCache)).toBe(false);
+    }
+    finally {
+        fs_1.default.rmSync(root, { recursive: true, force: true });
+    }
+});
 test('preserves actionable no-manifest preflight JSON when verify-sensors is piped', () => {
     const project = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-preflight-pipe-'));
     try {

package/dist/tests/structural/r4-plan-currentness-docs.test.js

@@ -0,0 +1,37 @@
+"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 cliReference = fs_1.default.readFileSync(path_1.default.resolve(__dirname, '../../../docs/cli-reference.md'), 'utf8');
+const readme = fs_1.default.readFileSync(path_1.default.resolve(__dirname, '../../../README.md'), 'utf8');
+const installation = fs_1.default.readFileSync(path_1.default.resolve(__dirname, '../../../docs/installation.md'), 'utf8');
+const developmentProcess = fs_1.default.readFileSync(path_1.default.resolve(__dirname, '../../../docs/guides/development-process.md'), 'utf8');
+describe('R4 plan/currentness documentation contract', () => {
+    it('documents plan validation and the unchanged legacy path', () => {
+        expect(cliReference).toContain('awm plan validate PLAN_PATH');
+        expect(cliReference).toMatch(/legacy/i);
+    });
+    it('documents strict currentness separately from minCliVersion compatibility', () => {
+        expect(cliReference).toContain('--require-current');
+        expect(cliReference).toContain('minCliVersion');
+        expect(cliReference).toMatch(/currentness[\s\S]{0,700}compatib|compatib[\s\S]{0,700}currentness/i);
+    });
+    it('documents the exact cache-resistant bootstrap and its enforceable boundary', () => {
+        expect(cliReference).toContain('npm exec --yes --package=agentic-workflow-manager@latest -- awm preflight --require-current');
+        expect(cliReference).toMatch(/fresh CLI\/bootstrap/i);
+        expect(cliReference).toMatch(/cannot update a host or cached container that\s+never runs new code/i);
+    });
+    it('keeps supported commands, remedies, bootstrap, and the enforceable boundary discoverable across user docs', () => {
+        expect(readme).toContain('awm plan validate PLAN_PATH');
+        expect(readme).toContain('awm preflight --require-current');
+        expect(installation).toContain('npm exec --yes --package=agentic-workflow-manager@latest -- awm preflight --require-current');
+        expect(installation).toMatch(/cannot update a host or cached container that\s+never runs new code/i);
+        expect(developmentProcess).toContain('awm preflight --require-current');
+        expect(developmentProcess).toContain('awm plan validate PLAN_PATH');
+        expect(developmentProcess).toMatch(/awm update --yes/);
+        expect(cliReference).toMatch(/awm unpin REGISTRY_NAME.*awm update --yes/s);
+    });
+});

package/package.json

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