agentic-workflow-manager 9.3.0 → 9.4.1

package/dist/src/core/plan/validate.js

@@ -0,0 +1,393 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePlanFile = validatePlanFile;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const json_1 = require("./json");
+const START = '<!-- AWM:COMPACT-SLICES:START v1 -->';
+const END = '<!-- AWM:COMPACT-SLICES:END v1 -->';
+const MAX_PLAN = 1024 * 1024;
+const MAX_MANIFEST = 256 * 1024;
+const MAX_SOURCE = 1024 * 1024;
+const MAX_STRING = 4096;
+const ID = /^[A-Z][A-Z0-9-]{0,63}$/;
+const PLAN_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SHELL = new Set([
+    'sh', 'bash', 'zsh', 'dash', 'ksh', 'fish', 'cmd', 'powershell', 'pwsh',
+    'env', 'busybox', 'node', 'nodejs', 'deno', 'bun', 'python', 'python3', 'ruby', 'perl', 'php', 'lua',
+]);
+function isLauncher(program) {
+    const base = path_1.default.posix.basename(program).toLowerCase();
+    return SHELL.has(base.replace(/\.exe$/, '')) || /^(?:node(?:js)?|py(?:thon(?:w)?\d*(?:\.\d+)?)?|deno|bun|ruby(?:\d+(?:\.\d+)*)?|perl(?:\d+(?:\.\d+)*)?|(?:a|ba|c|tc|z|da|k)?sh|busybox|cmd|powershell|pwsh|wscript|cscript)(?:\.exe)?(?:[-.][a-z0-9][a-z0-9.-]*)?$/i.test(base);
+}
+function diagnostic(code, message, field) { return { state: 'invalid', diagnostics: [{ code, message, ...(field ? { field } : {}) }] }; }
+function unsupported(schema) { return { state: 'unsupported', schema, diagnostics: [{ code: 'PLAN_UNSUPPORTED_SCHEMA', message: 'unsupported compact plan schema; update the CLI' }] }; }
+function schemaClassification(candidate) {
+    if (!object(candidate) || !Object.prototype.hasOwnProperty.call(candidate, 'schema'))
+        return undefined;
+    if (typeof candidate.schema !== 'string')
+        return diagnostic('PLAN_MARKERS', 'compact markers must occur once in order');
+    if (Buffer.byteLength(candidate.schema, 'utf8') > MAX_STRING)
+        return diagnostic('PLAN_LIMIT', 'schema exceeds maximum string size');
+    if (candidate.schema.startsWith('compact-slices/') && candidate.schema !== 'compact-slices/v1')
+        return unsupported(candidate.schema);
+    return diagnostic('PLAN_MARKERS', 'compact markers must occur once in order');
+}
+function embeddedJsonObjects(text) {
+    const objects = [];
+    for (let start = 0; start < text.length && objects.length < 64; start += 1) {
+        if (text[start] !== '{')
+            continue;
+        let depth = 0;
+        let quoted = false;
+        let escaped = false;
+        let end = start;
+        for (; end < text.length && end - start <= MAX_MANIFEST; end += 1) {
+            const character = text[end];
+            if (quoted) {
+                if (escaped)
+                    escaped = false;
+                else if (character === '\\')
+                    escaped = true;
+                else if (character === '"')
+                    quoted = false;
+                continue;
+            }
+            if (character === '"') {
+                quoted = true;
+                continue;
+            }
+            if (character === '{')
+                depth += 1;
+            if (character === '}' && --depth === 0) {
+                objects.push(text.slice(start, end + 1));
+                start = end;
+                break;
+            }
+        }
+    }
+    return objects;
+}
+function markerlessSchemaClassification(text) {
+    const candidates = [text.trim(), ...embeddedJsonObjects(text)];
+    for (const source of candidates) {
+        try {
+            const classification = schemaClassification((0, json_1.parseJsonNoDuplicate)(source));
+            if (classification)
+                return classification;
+        }
+        catch { /* try the next bounded JSON object */ }
+    }
+    return undefined;
+}
+function count(text, token) { return text.split(token).length - 1; }
+function object(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function jsonStringAt(text, start) {
+    if (text[start] !== '"')
+        return undefined;
+    for (let end = start + 1; end < text.length && end - start <= MAX_STRING; end += 1) {
+        if (text[end] === '\\') {
+            end += 1;
+            continue;
+        }
+        if (text[end] !== '"')
+            continue;
+        try {
+            const value = JSON.parse(text.slice(start, end + 1));
+            return typeof value === 'string' ? { value, end: end + 1 } : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function compactSchemaSignal(text) {
+    for (let start = text.indexOf('"'); start >= 0; start = text.indexOf('"', start + 1)) {
+        const key = jsonStringAt(text, start);
+        if (!key)
+            continue;
+        if (key.value !== 'schema') {
+            start = key.end - 1;
+            continue;
+        }
+        const colon = text.slice(key.end).match(/^\s*:/);
+        if (!colon)
+            continue;
+        const value = jsonStringAt(text, key.end + colon[0].length);
+        if (value?.value.startsWith('compact-slices/'))
+            return true;
+    }
+    return false;
+}
+function exact(value, fields) {
+    return object(value) && Object.keys(value).length === fields.length && fields.every((field) => Object.prototype.hasOwnProperty.call(value, field));
+}
+function allStrings(value, max = MAX_STRING) { return Array.isArray(value) && value.every((item) => typeof item === 'string' && Buffer.byteLength(item, 'utf8') <= max); }
+function validId(value) { return typeof value === 'string' && ID.test(value); }
+function inside(root, candidate) { const relative = path_1.default.relative(root, candidate); return relative === '' || (!relative.startsWith(`..${path_1.default.sep}`) && relative !== '..' && !path_1.default.isAbsolute(relative)); }
+function validRelative(value) {
+    return typeof value === 'string' && value.length > 0 && Buffer.byteLength(value, 'utf8') <= MAX_STRING && !path_1.default.isAbsolute(value) && !path_1.default.win32.isAbsolute(value) && !value.includes('\\') && value.split('/').every((part) => part !== '' && part !== '.' && part !== '..') && path_1.default.posix.normalize(value) === value;
+}
+function regularInside(root, relative) {
+    if (!validRelative(relative))
+        return undefined;
+    const candidate = path_1.default.join(root, relative);
+    if (!inside(root, candidate))
+        return undefined;
+    const parts = relative.split('/');
+    let current = root;
+    try {
+        for (const part of parts) {
+            current = path_1.default.join(current, part);
+            if (fs_1.default.lstatSync(current).isSymbolicLink())
+                return undefined;
+        }
+        if (!fs_1.default.lstatSync(candidate).isFile())
+            return undefined;
+        const real = fs_1.default.realpathSync(candidate);
+        return inside(root, real) ? real : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function executableInside(root, relative) {
+    const file = regularInside(root, relative);
+    try {
+        return file && (process.platform === 'win32' ? /\.(?:exe|cmd|bat)$/i.test(file) : (fs_1.default.statSync(file).mode & 0o111) !== 0) ? file : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function refs(value, known) { return allStrings(value) && value.every((id) => known.has(id)); }
+function uniqueRefs(value, known) { return refs(value, known) && new Set(value).size === value.length; }
+function unsafeCommand(value) { return /[\0\r\n]|[`$]|\$\(|\$\{|[;&|<>*?\[\]{}()]/.test(value); }
+function normalizeLineEndings(text) { return text.replace(/\r\n?/g, '\n'); }
+function withoutFencedCode(text) {
+    let fence;
+    return text.split('\n').map((line) => {
+        const marker = /^(?: {0,3})(`{3,}|~{3,})/.exec(line)?.[1];
+        if (marker && (!fence || (marker[0] === fence.character && marker.length >= fence.length))) {
+            fence = fence ? undefined : { character: marker[0], length: marker.length };
+            return '';
+        }
+        return fence ? '' : line;
+    }).join('\n');
+}
+function checkMarkdown(text, slices) {
+    const markdown = withoutFencedCode(text);
+    const headingOffsets = new Set();
+    for (const slice of slices) {
+        const anchor = `<a id="${slice.sectionAnchor}"></a>`;
+        if (count(markdown, anchor) !== 1)
+            return diagnostic('PLAN_MARKDOWN_ANCHOR', 'slice anchor must occur exactly once');
+        const start = markdown.indexOf(anchor);
+        const heading = `### Slice ${slice.id}: ${slice.title}`;
+        const expectedHeading = start + anchor.length + 1;
+        if (markdown[start + anchor.length] !== '\n')
+            return diagnostic('PLAN_MARKDOWN_HEADING', 'slice heading must immediately follow anchor');
+        const headingEnd = markdown.indexOf('\n', expectedHeading);
+        if (markdown.slice(expectedHeading, headingEnd < 0 ? markdown.length : headingEnd) !== heading)
+            return diagnostic('PLAN_MARKDOWN_HEADING', 'slice heading must exactly match manifest after anchor');
+        const headingAt = expectedHeading;
+        headingOffsets.add(headingAt);
+    }
+    for (const match of markdown.matchAll(/^### Slice .*$/gm)) {
+        if (!headingOffsets.has(match.index ?? -1))
+            return diagnostic('PLAN_MARKDOWN_HEADING', 'slice headings must immediately follow declared anchors');
+    }
+    for (const slice of slices) {
+        const anchor = `<a id="${slice.sectionAnchor}"></a>`;
+        const start = markdown.indexOf(anchor);
+        const heading = `### Slice ${slice.id}: ${slice.title}`;
+        const headingAt = start + anchor.length + 1;
+        const next = markdown.indexOf('\n### Slice ', headingAt + heading.length);
+        const end = next < 0 ? markdown.length : next;
+        const section = markdown.slice(start, end);
+        for (const name of ['Surfaces', 'Implementation', 'Edge cases', 'Evidence', 'Fallback']) {
+            if ((section.match(new RegExp(`^#### ${name}\\s*$`, 'gm')) ?? []).length !== 1)
+                return diagnostic('PLAN_MARKDOWN_SECTION', 'each required slice subsection must occur exactly once');
+            const match = new RegExp(`^#### ${name}\\s*\\n\\s*([^#\\s][\\s\\S]*?)(?=\\n#### |$)`, 'm').exec(section);
+            if (!match || /\b(?:TODO|TBD|placeholder|draft)\b/i.test(match[1]))
+                return diagnostic('PLAN_MARKDOWN_SECTION', 'slice section must contain complete prose');
+        }
+    }
+    return undefined;
+}
+/** Read-only validator for a bounded compact-slices/v1 Markdown plan. */
+function validatePlanFile(planPath, cwd = process.cwd()) {
+    if (typeof planPath !== 'string' || planPath.length === 0)
+        throw new Error('planPath must be a non-empty path');
+    if (typeof cwd !== 'string' || cwd.length === 0)
+        throw new Error('cwd must be a non-empty directory path');
+    let root;
+    try {
+        root = fs_1.default.realpathSync(cwd);
+        if (!fs_1.default.statSync(root).isDirectory())
+            throw new Error();
+    }
+    catch {
+        throw new Error('cwd must resolve to an existing directory');
+    }
+    const candidate = path_1.default.resolve(root, planPath);
+    if (!inside(root, candidate))
+        return diagnostic('PLAN_PATH_UNSAFE', 'plan path must be inside cwd');
+    const relativePlan = path_1.default.relative(root, candidate).replace(/\\/g, '/');
+    const planFile = regularInside(root, relativePlan);
+    if (!planFile)
+        return diagnostic('PLAN_PATH_UNSAFE', 'plan path must be a contained regular non-symlink file');
+    let bytes;
+    try {
+        if (fs_1.default.statSync(planFile).size > MAX_PLAN)
+            return diagnostic('PLAN_LIMIT', 'plan exceeds maximum size');
+        bytes = fs_1.default.readFileSync(planFile);
+    }
+    catch {
+        return diagnostic('PLAN_READ', 'plan cannot be read');
+    }
+    let text;
+    try {
+        text = normalizeLineEndings(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch {
+        return diagnostic('PLAN_ENCODING', 'plan must be valid UTF-8');
+    }
+    const starts = count(text, START);
+    const ends = count(text, END);
+    const signaled = starts > 0 || ends > 0 || compactSchemaSignal(text);
+    if (!signaled)
+        return markerlessSchemaClassification(text) ?? { state: 'legacy' };
+    if (starts === 0 && ends === 0)
+        return markerlessSchemaClassification(text) ?? diagnostic('PLAN_MARKERS', 'compact markers must occur once in order');
+    if (starts !== 1 || ends !== 1 || text.indexOf(START) > text.indexOf(END)) {
+        const partial = starts === 1 ? text.slice(text.indexOf(START) + START.length, ends ? text.indexOf(END) : undefined).trim() : '';
+        try {
+            const candidate = (0, json_1.parseJsonNoDuplicate)(partial);
+            if (object(candidate) && typeof candidate.schema === 'string' && Buffer.byteLength(candidate.schema, 'utf8') <= MAX_STRING && candidate.schema.startsWith('compact-slices/') && candidate.schema !== 'compact-slices/v1')
+                return unsupported(candidate.schema);
+        }
+        catch { /* invalid below */ }
+        return diagnostic('PLAN_MARKERS', 'compact markers must occur once in order');
+    }
+    const body = text.slice(text.indexOf(START) + START.length, text.indexOf(END));
+    if (Buffer.byteLength(body, 'utf8') > MAX_MANIFEST)
+        return diagnostic('PLAN_LIMIT', 'manifest exceeds maximum size');
+    let raw;
+    try {
+        raw = (0, json_1.parseJsonNoDuplicate)(body.trim());
+    }
+    catch {
+        return diagnostic('PLAN_JSON', 'manifest must be valid JSON without duplicate keys');
+    }
+    if (!object(raw))
+        return diagnostic('PLAN_SHAPE', 'manifest must be an object');
+    if (typeof raw.schema === 'string' && Buffer.byteLength(raw.schema, 'utf8') > MAX_STRING)
+        return diagnostic('PLAN_LIMIT', 'schema exceeds maximum string size');
+    if (typeof raw.schema === 'string' && raw.schema.startsWith('compact-slices/') && raw.schema !== 'compact-slices/v1')
+        return unsupported(raw.schema);
+    if (!exact(raw, ['schema', 'planId', 'requirements', 'sources', 'commands', 'slices', 'closureCommands']))
+        return diagnostic(Object.keys(raw).some((key) => !['schema', 'planId', 'requirements', 'sources', 'commands', 'slices', 'closureCommands'].includes(key)) ? 'PLAN_UNKNOWN_FIELD' : 'PLAN_MISSING_FIELD', 'manifest fields must exactly match the contract');
+    if (!Array.isArray(raw.requirements) || !Array.isArray(raw.sources) || !Array.isArray(raw.commands) || !Array.isArray(raw.slices) || !Array.isArray(raw.closureCommands))
+        return diagnostic('PLAN_SHAPE', 'manifest collections are invalid');
+    if (raw.requirements.length > 256 || raw.sources.length > 256 || raw.commands.length > 512 || raw.slices.length > 64 || raw.closureCommands.length > 512)
+        return diagnostic('PLAN_LIMIT', 'manifest exceeds collection limits');
+    if (typeof raw.planId === 'string' && Buffer.byteLength(raw.planId, 'utf8') > MAX_STRING)
+        return diagnostic('PLAN_LIMIT', 'plan id exceeds maximum string size');
+    if (raw.schema !== 'compact-slices/v1' || typeof raw.planId !== 'string' || !PLAN_ID.test(raw.planId) || !allStrings(raw.requirements) || new Set(raw.requirements).size !== raw.requirements.length)
+        return diagnostic('PLAN_SHAPE', 'manifest scalar fields are invalid');
+    if (raw.requirements.some((id) => !ID.test(id)) || !allStrings(raw.closureCommands) || new Set(raw.closureCommands).size !== raw.closureCommands.length)
+        return diagnostic('PLAN_SHAPE', 'manifest arrays or identifiers are invalid');
+    const sourceIds = new Set();
+    for (const source of raw.sources) {
+        if (!exact(source, ['id', 'path', 'locator', 'fact']) || !validId(source.id) || sourceIds.has(source.id) || !validRelative(source.path) || typeof source.locator !== 'string' || source.locator.trim().length === 0 || /[\0\r\n]/.test(source.locator) || Buffer.byteLength(source.locator, 'utf8') > MAX_STRING || typeof source.fact !== 'string' || source.fact.trim().length === 0 || Buffer.byteLength(source.fact, 'utf8') > MAX_STRING)
+            return diagnostic('PLAN_SOURCE_SHAPE', 'source fields are invalid');
+        sourceIds.add(source.id);
+        const file = regularInside(root, source.path);
+        if (!file)
+            return diagnostic('PLAN_SOURCE_UNSAFE', 'source path must be a contained regular non-symlink file');
+        let bytes;
+        try {
+            if (fs_1.default.statSync(file).size > MAX_SOURCE)
+                return diagnostic('PLAN_SOURCE_LIMIT', 'source exceeds maximum size');
+            bytes = fs_1.default.readFileSync(file);
+        }
+        catch {
+            return diagnostic('PLAN_SOURCE_UNSAFE', 'source cannot be read');
+        }
+        let contents;
+        try {
+            contents = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        }
+        catch {
+            return diagnostic('PLAN_SOURCE_ENCODING', 'source must be valid UTF-8');
+        }
+        if (!contents.includes(source.locator))
+            return diagnostic('PLAN_SOURCE_LOCATOR', 'source locator must occur in source file');
+    }
+    const commandIds = new Set();
+    const closureIds = new Set(raw.closureCommands);
+    for (const command of raw.commands) {
+        if (!exact(command, ['id', 'program', 'args', 'covers']) || !validId(command.id) || commandIds.has(command.id) || typeof command.program !== 'string' || command.program.length === 0 || Buffer.byteLength(command.program, 'utf8') > MAX_STRING || !allStrings(command.args) || command.args.length > 128 || !allStrings(command.covers) || new Set(command.covers).size !== command.covers.length || (command.covers.length === 0 && !closureIds.has(command.id)) || command.covers.some((id) => !raw.requirements.includes(id)))
+            return diagnostic('PLAN_COMMAND_SHAPE', 'command fields are invalid');
+        commandIds.add(command.id);
+        const program = command.program;
+        if (isLauncher(program) || unsafeCommand(program) || program.includes('\\') || /^[a-zA-Z]:/.test(program) || /\s/.test(program) || (program.includes('/') && !executableInside(root, program)))
+            return diagnostic('PLAN_COMMAND_UNSAFE', 'command program is not inert and safe');
+        if (command.args.some(unsafeCommand))
+            return diagnostic('PLAN_COMMAND_UNSAFE', 'command arguments contain shell syntax');
+    }
+    const sliceIds = new Set();
+    const owners = new Map();
+    for (const slice of raw.slices) {
+        if (!exact(slice, ['id', 'title', 'requirements', 'dependsOn', 'sectionAnchor', 'sources', 'redCommands', 'greenCommands', 'reviewEvidence', 'risk', 'fallback']) || !validId(slice.id) || sliceIds.has(slice.id) || typeof slice.title !== 'string' || slice.title.length === 0 || Buffer.byteLength(slice.title, 'utf8') > MAX_STRING || !allStrings(slice.requirements) || slice.requirements.length === 0 || slice.requirements.some((id) => !raw.requirements.includes(id)) || !allStrings(slice.dependsOn) || typeof slice.sectionAnchor !== 'string' || slice.sectionAnchor.length === 0 || Buffer.byteLength(slice.sectionAnchor, 'utf8') > MAX_STRING || !uniqueRefs(slice.sources, sourceIds) || !uniqueRefs(slice.redCommands, commandIds) || slice.redCommands.length === 0 || !uniqueRefs(slice.greenCommands, commandIds) || slice.greenCommands.length === 0 || !allStrings(slice.fallback) || slice.fallback.length === 0 || slice.fallback.some((item) => item.trim().length === 0) || slice.risk !== 'bounded' && slice.risk !== 'full-context')
+            return diagnostic('PLAN_SLICE_SHAPE', 'slice fields are invalid');
+        sliceIds.add(slice.id);
+        if (!Array.isArray(slice.reviewEvidence) || slice.reviewEvidence.length !== 2 || new Set(slice.reviewEvidence).size !== 2 || !slice.reviewEvidence.includes('specification') || !slice.reviewEvidence.includes('code-quality'))
+            return diagnostic('PLAN_REVIEW_EVIDENCE', 'review evidence must be specification and code-quality');
+        for (const requirement of slice.requirements)
+            owners.set(requirement, (owners.get(requirement) ?? 0) + 1);
+    }
+    if (raw.requirements.some((requirement) => owners.get(requirement) !== 1))
+        return diagnostic('PLAN_REQUIREMENT_OWNER', 'each requirement must have exactly one owner');
+    const slices = raw.slices;
+    for (const slice of slices) {
+        if (new Set(slice.dependsOn).size !== slice.dependsOn.length || slice.dependsOn.includes(slice.id) || !slice.dependsOn.every((id) => sliceIds.has(id)))
+            return diagnostic('PLAN_DEPENDENCY', 'slice dependencies must resolve and be non-self unique');
+    }
+    const visited = new Set();
+    const visiting = new Set();
+    const byId = new Map(slices.map((slice) => [slice.id, slice]));
+    const cycle = (id) => { if (visiting.has(id))
+        return true; if (visited.has(id))
+        return false; visiting.add(id); const found = byId.get(id).dependsOn.some(cycle); visiting.delete(id); visited.add(id); return found; };
+    if (slices.some((slice) => cycle(slice.id)))
+        return diagnostic('PLAN_DEPENDENCY', 'slice dependencies must be acyclic');
+    for (const command of raw.commands) {
+        const covers = command.covers;
+        const references = slices.filter((slice) => slice.redCommands.includes(command.id) || slice.greenCommands.includes(command.id));
+        if (covers.length > 0 && !references.some((slice) => covers.some((requirement) => slice.requirements.includes(requirement))))
+            return diagnostic('PLAN_COMMAND_COVER', 'command coverage must relate to a referencing slice');
+    }
+    for (const slice of slices) {
+        for (const requirement of slice.requirements) {
+            const covered = raw.commands.some((command) => command.covers.includes(requirement) && (slice.redCommands.includes(command.id) || slice.greenCommands.includes(command.id)));
+            if (!covered)
+                return diagnostic('PLAN_REQUIREMENT_COVER', 'each requirement must be covered by a command executed by its owning slice');
+        }
+    }
+    const usedSources = new Set(slices.flatMap((slice) => slice.sources));
+    const usedCommands = new Set([...slices.flatMap((slice) => [...slice.redCommands, ...slice.greenCommands]), ...raw.closureCommands]);
+    if (Array.from(sourceIds).some((id) => !usedSources.has(id)) || Array.from(commandIds).some((id) => !usedCommands.has(id)) || !refs(raw.closureCommands, commandIds))
+        return diagnostic('PLAN_ORPHAN', 'sources and commands must be referenced');
+    if (raw.requirements.length === 0 || raw.sources.length === 0 || raw.commands.length === 0 || raw.slices.length === 0 || raw.closureCommands.length === 0)
+        return diagnostic('PLAN_SHAPE', 'manifest collections must be nonempty');
+    const markdown = checkMarkdown(text, slices);
+    if (markdown)
+        return markdown;
+    return { state: 'valid', schema: 'compact-slices/v1', manifest: raw };
+}

package/dist/src/index.js

@@ -31,6 +31,7 @@ const sensors_1 = require("./commands/sensors");
 const ledger_1 = require("./commands/ledger");
 const context_budget_1 = require("./commands/context-budget");
 const preflight_1 = require("./commands/preflight");
+const plan_1 = require("./commands/plan");
 const doctor_1 = require("./commands/doctor");
 const backup_1 = require("./commands/backup");
 const init_1 = require("./commands/init");
@@ -52,7 +53,11 @@ const update_check_1 = require("./core/update-check");
 const cli_version_1 = require("./core/cli-version");
 const program = new commander_1.Command();
 program.name('awm').description('Agentic Workflow Manager').version((0, cli_version_1.cliVersion)());
-program.hook('postAction', () => {
+program.hook('postAction', (_command, actionCommand) => {
+    if (actionCommand.name() === 'preflight')
+        return;
+    if (actionCommand.parent?.name() === 'plan' && actionCommand.name() === 'validate' && actionCommand.opts().json === true)
+        return;
     try {
         (0, update_check_1.maybeNotifyUpdate)();
     }
@@ -726,6 +731,7 @@ miroCmd.command('sync <storyMapPath>')
 (0, ledger_1.registerLedgerCommand)(program);
 (0, context_budget_1.registerContextBudgetCommand)(program);
 (0, preflight_1.registerPreflightCommand)(program);
+(0, plan_1.registerPlanCommand)(program);
 (0, doctor_1.registerDoctorCommand)(program);
 (0, backup_1.registerBackupCommand)(program);
 (0, init_1.registerInitCommand)(program);

package/dist/tests/commands/plan/index.test.js

@@ -0,0 +1,154 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const plan_1 = require("../../../src/commands/plan");
+const stdoutWrite = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+const valid = {
+    state: 'valid', schema: 'compact-slices/v1', manifest: {
+        schema: 'compact-slices/v1', planId: 'r4-plan', requirements: ['R4-VAL-1', 'R4-VAL-4'],
+        sources: [], commands: [], slices: [], closureCommands: [],
+    },
+};
+const invalid = {
+    state: 'invalid', diagnostics: [{ code: 'PLAN_MARKERS', message: 'compact markers must occur once in order' }],
+};
+const unsupported = {
+    state: 'unsupported', schema: 'compact-slices/v2', diagnostics: [{ code: 'PLAN_UNSUPPORTED_SCHEMA', message: 'unsupported compact plan schema; update the CLI' }],
+};
+function commandFor(report, calls = []) {
+    const program = new commander_1.Command();
+    program.exitOverride();
+    program.configureOutput({ writeErr: () => undefined });
+    (0, plan_1.registerPlanCommand)(program, {
+        validatePlanFile: (planPath, cwd) => {
+            calls.push([planPath, cwd]);
+            return report;
+        },
+    });
+    return program;
+}
+describe('plan validate Commander wiring', () => {
+    const previousExitCode = process.exitCode;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        process.exitCode = undefined;
+    });
+    afterAll(() => {
+        stdoutWrite.mockRestore();
+        process.exitCode = previousExitCode;
+    });
+    it('emits deterministic human output for a valid compact plan', async () => {
+        await commandFor(valid).parseAsync(['node', 'awm', 'plan', 'validate', 'plans/r4.md']);
+        expect(String(stdoutWrite.mock.calls[0][0])).toBe('Plan validation: valid "plans/r4.md" (compact-slices/v1; 0 slices; 2 requirements; complete ownership)\n');
+        expect(process.exitCode).toBe(0);
+    });
+    it('emits one stable JSON object without an update banner', async () => {
+        await commandFor(valid).parseAsync(['node', 'awm', 'plan', 'validate', 'plans/r4.md', '--json']);
+        expect(JSON.parse(String(stdoutWrite.mock.calls[0][0]))).toEqual({
+            state: 'valid', path: 'plans/r4.md', schema: 'compact-slices/v1', planId: 'r4-plan',
+            requirements: 2, sources: 0, commands: 0, slices: 0, completeOwnership: true,
+        });
+        expect(String(stdoutWrite.mock.calls[0][0])).not.toContain('update');
+    });
+    it('keeps a legacy plan on the existing full-quality path with exit 0', async () => {
+        await commandFor({ state: 'legacy' }).parseAsync(['node', 'awm', 'plan', 'validate', 'legacy.md']);
+        expect(String(stdoutWrite.mock.calls[0][0])).toBe('Plan validation: legacy "legacy.md" — existing full-quality path applies; compact optimization was not requested.\n');
+        expect(process.exitCode).toBe(0);
+    });
+    it.each([
+        ['invalid', invalid],
+        ['unsupported', unsupported],
+    ])('writes complete %s diagnostics before assigning semantic exit 2', async (state, report) => {
+        const observedExitCodes = [];
+        stdoutWrite.mockImplementation(() => {
+            observedExitCodes.push(process.exitCode);
+            return true;
+        });
+        await commandFor(report).parseAsync(['node', 'awm', 'plan', 'validate', 'broken.md', '--json']);
+        expect(JSON.parse(String(stdoutWrite.mock.calls[0][0]))).toMatchObject({ state, path: 'broken.md', diagnostics: report.diagnostics });
+        expect(observedExitCodes).toEqual([undefined]);
+        expect(process.exitCode).toBe(2);
+    });
+    it('passes an explicit cwd only to validation while retaining the original path text in output', async () => {
+        const calls = [];
+        await commandFor(valid, calls).parseAsync(['node', 'awm', 'plan', 'validate', 'plans/r4.md', '--cwd', 'fixture-root']);
+        expect(calls).toEqual([['plans/r4.md', 'fixture-root']]);
+        expect(String(stdoutWrite.mock.calls[0][0])).toContain('"plans/r4.md"');
+    });
+    it('rejects missing paths, extra arguments, and missing --cwd values before validation', async () => {
+        const calls = [];
+        await expect(commandFor(valid, calls).parseAsync(['node', 'awm', 'plan', 'validate'])).rejects.toThrow();
+        await expect(commandFor(valid, calls).parseAsync(['node', 'awm', 'plan', 'validate', 'one.md', 'two.md'])).rejects.toThrow();
+        await expect(commandFor(valid, calls).parseAsync(['node', 'awm', 'plan', 'validate', 'one.md', '--cwd', '--json'])).rejects.toThrow();
+        expect(calls).toEqual([]);
+    });
+    it.each(['plans/escape\u001b.md', 'plans/tab\t.md'])('rejects control characters in the public plan path %j', async (planPath) => {
+        const calls = [];
+        await expect(commandFor(valid, calls).parseAsync(['node', 'awm', 'plan', 'validate', planPath])).rejects.toThrow('plan path must be a non-empty path without control characters');
+        expect(calls).toEqual([]);
+    });
+    it.each(['fixture\u001b-root', 'fixture\troot'])('rejects control characters in the public --cwd value %j', async (cwd) => {
+        const calls = [];
+        await expect(commandFor(valid, calls).parseAsync(['node', 'awm', 'plan', 'validate', 'plans/r4.md', '--cwd', cwd])).rejects.toThrow('--cwd must be a non-empty path without control characters');
+        expect(calls).toEqual([]);
+    });
+    it('does not emit terminal control characters in unsupported human output', () => {
+        const report = {
+            state: 'unsupported', schema: 'compact-slices/v2\u001b[2J',
+            diagnostics: [{ code: 'PLAN\tSCHEMA', message: 'unsafe\u001b[31m diagnostic', field: 'schema\r' }],
+        };
+        const output = (0, plan_1.formatReport)(report, 'plans/unsafe\u001b.md');
+        expect(output.replace(/\n/g, '')).not.toMatch(/[\u0000-\u001f\u007f-\u009f]/);
+        expect(output).toContain('compact-slices/v2\\u001b[2J');
+    });
+    it('suppresses the passive update notification only for root-program JSON validation', () => {
+        const awmHome = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-plan-update-'));
+        const repoRoot = path_1.default.resolve(__dirname, '../../../..');
+        const indexPath = path_1.default.join(repoRoot, 'cli', 'src', 'index.ts');
+        const registerPath = require.resolve('ts-node/register');
+        fs_1.default.writeFileSync(path_1.default.join(awmHome, 'update-check.json'), JSON.stringify({ lastCheck: Date.now(), latest: '999.0.0' }));
+        try {
+            const result = (0, child_process_1.spawnSync)(process.execPath, ['-r', registerPath, indexPath, 'plan', 'validate', 'docs/plans/2026-08-26-r4a-compact-plan-cli-plan.md', '--cwd', repoRoot, '--json'], {
+                cwd: repoRoot,
+                encoding: 'utf8',
+                env: { ...process.env, AWM_HOME: awmHome, TS_NODE_PROJECT: path_1.default.join(repoRoot, 'cli', 'tsconfig.json') },
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            expect(result.status).toBe(0);
+            expect(() => JSON.parse(result.stdout)).not.toThrow();
+            expect(JSON.parse(result.stdout)).toMatchObject({ state: 'valid', path: 'docs/plans/2026-08-26-r4a-compact-plan-cli-plan.md' });
+            expect(result.stderr).toBe('');
+            const humanResult = (0, child_process_1.spawnSync)(process.execPath, ['-r', registerPath, indexPath, 'plan', 'validate', 'docs/plans/2026-08-26-r4a-compact-plan-cli-plan.md', '--cwd', repoRoot], {
+                cwd: repoRoot,
+                encoding: 'utf8',
+                env: { ...process.env, AWM_HOME: awmHome, TS_NODE_PROJECT: path_1.default.join(repoRoot, 'cli', 'tsconfig.json') },
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            expect(humanResult.status).toBe(0);
+            expect(humanResult.stderr).toContain('awm v999.0.0 available');
+        }
+        finally {
+            fs_1.default.rmSync(awmHome, { recursive: true, force: true });
+        }
+    });
+});
+describe('plan validation public boundaries', () => {
+    it.each([
+        ['valid', valid, 0],
+        ['legacy', { state: 'legacy' }, 0],
+        ['invalid', { state: 'invalid', diagnostics: [] }, 2],
+        ['unsupported', { state: 'unsupported', schema: 'compact-slices/v2', diagnostics: [] }, 2],
+    ])('maps %s reports to exit %i', (_state, report, code) => {
+        expect((0, plan_1.exitCodeFor)(report)).toBe(code);
+    });
+    it('fails loudly for an invalid validator dependency', () => {
+        expect(() => (0, plan_1.registerPlanCommand)(new commander_1.Command(), {})).toThrow('validatePlanFile must be a function');
+    });
+});