gate-evm-tools 1.0.27 → 1.0.31

package/dist-runtime/workflow/lib/plan.js

@@ -0,0 +1,324 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptyPlan = exports.TASK_STATUSES = exports.SECTIONS = exports.PLAN_FILE = exports.PLAN_SCHEMA = void 0;
+exports.assertPortableInput = assertPortableInput;
+exports.parsePlan = parsePlan;
+exports.renderPlan = renderPlan;
+exports.readPlanFile = readPlanFile;
+exports.writePlanFile = writePlanFile;
+exports.planSummary = planSummary;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const yaml_1 = __importDefault(require("yaml"));
+/**
+ * Read and write `handoff.md`, the plan-level carrier shared by the GateFlow
+ * entry point and the Codex command line.
+ *
+ * This is deliberately NOT the execution-level `handoff.json`: that one records
+ * deployment evidence and is validated byte for byte by the deployment gates.
+ * The plan layer says what is to be done; the execution layer proves what was.
+ * Keeping them in separate files is the point -- neither should have to carry
+ * the other's fields.
+ *
+ * Nothing here trusts the file. A plan that moves between two runtimes is
+ * exactly where a crafted document would be worth writing, so the parse is
+ * strict, the forbidden-field list is checked recursively, and the writer is
+ * the only sanctioned producer of the deterministic parts.
+ */
+exports.PLAN_SCHEMA = "gateflow-plan/v1";
+exports.PLAN_FILE = "handoff.md";
+exports.SECTIONS = ["development", "audit", "deployment"];
+exports.TASK_STATUSES = ["pending", "ready", "running", "completed", "failed", "cancelled"];
+/** Local bindings. A plan changes entry point, so none of these can travel. */
+const FORBIDDEN_FIELDS = [
+    "sessionid", "runtimerunid", "stageid", "attemptid", "workspacepath",
+    "authorizationid", "executionlock", "localstate", "planid", "workspacerelativepath",
+];
+const SAFE_KEY = /^[a-z0-9][a-z0-9-]{0,199}$/;
+function fail(message) {
+    throw new Error(`handoff.md: ${message}`);
+}
+function normalizeFieldName(key) {
+    return key.replace(/[_-]/g, "").toLowerCase();
+}
+/** Recursive, because a forbidden name is just as bad nested as at the top. */
+function assertNoForbiddenFields(value, where) {
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => assertNoForbiddenFields(item, `${where}[${index}]`));
+        return;
+    }
+    if (!value || typeof value !== "object")
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        if (FORBIDDEN_FIELDS.includes(normalizeFieldName(key))) {
+            fail(`${where}.${key} is a local binding and cannot travel between entry points`);
+        }
+        assertNoForbiddenFields(child, `${where}.${key}`);
+    }
+}
+const ABSOLUTE = /^(?:\/|\\|[A-Za-z]:[\\/]|~\/)/;
+function assertNoSecretsOrPaths(value, where) {
+    if (typeof value === "string") {
+        if (ABSOLUTE.test(value))
+            fail(`${where} must not be an absolute path`);
+        if (/-----BEGIN .*PRIVATE KEY-----/.test(value))
+            fail(`${where} must not contain a private key`);
+        if (/\bBearer\s+\S+/.test(value))
+            fail(`${where} must not contain a bearer token`);
+        if (/[?&](?:api[_-]?key|token|secret)=\S+/i.test(value))
+            fail(`${where} must not contain a credentialed URL`);
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => assertNoSecretsOrPaths(item, `${where}[${index}]`));
+        return;
+    }
+    if (!value || typeof value !== "object")
+        return;
+    for (const [key, child] of Object.entries(value))
+        assertNoSecretsOrPaths(child, `${where}.${key}`);
+}
+/**
+ * Check caller input before it is reduced to known fields. The CLI builds
+ * tasks from a whitelist, so a forbidden name dropped there would never reach
+ * the parser's check -- it would vanish silently instead of being refused.
+ */
+function assertPortableInput(value, where) {
+    assertNoForbiddenFields(value, where);
+    assertNoSecretsOrPaths(value, where);
+}
+function nonEmptyString(value, where) {
+    if (typeof value !== "string" || !value.trim())
+        fail(`${where} must be a non-empty string`);
+    return value;
+}
+function stringArray(value, where, options = {}) {
+    if (!Array.isArray(value))
+        fail(`${where} must be an array`);
+    const items = value.map((item, index) => nonEmptyString(item, `${where}[${index}]`));
+    if (options.min !== undefined && items.length < options.min) {
+        fail(`${where} must contain at least ${options.min} item(s)`);
+    }
+    return items;
+}
+function parseTask(raw, where) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        fail(`${where} must be an object`);
+    const value = raw;
+    const planKey = nonEmptyString(value.planKey, `${where}.planKey`);
+    if (!SAFE_KEY.test(planKey)) {
+        fail(`${where}.planKey must be lower-case alphanumeric with hyphens: "${planKey}"`);
+    }
+    const status = nonEmptyString(value.status ?? "pending", `${where}.status`);
+    if (!exports.TASK_STATUSES.includes(status)) {
+        fail(`${where}.status must be one of ${exports.TASK_STATUSES.join(", ")}`);
+    }
+    const task = {
+        planKey,
+        title: nonEmptyString(value.title, `${where}.title`),
+        objective: nonEmptyString(value.objective, `${where}.objective`),
+        acceptance: stringArray(value.acceptance, `${where}.acceptance`, { min: 1 }),
+        dependsOn: value.dependsOn === undefined ? [] : stringArray(value.dependsOn, `${where}.dependsOn`),
+        status: status,
+    };
+    if (value.scope !== undefined)
+        task.scope = value.scope;
+    if (value.parameters !== undefined) {
+        if (!Array.isArray(value.parameters))
+            fail(`${where}.parameters must be an array`);
+        task.parameters = value.parameters;
+    }
+    if (value.expectedArtifacts !== undefined) {
+        task.expectedArtifacts = stringArray(value.expectedArtifacts, `${where}.expectedArtifacts`);
+    }
+    if (value.allowedChanges !== undefined) {
+        task.allowedChanges = stringArray(value.allowedChanges, `${where}.allowedChanges`);
+    }
+    assertNoForbiddenFields(task, where);
+    assertNoSecretsOrPaths(task, where);
+    return task;
+}
+/** Dependency rules are enforced across the whole plan, not per task. */
+function assertDependencyGraph(tasks) {
+    const byKey = new Map(tasks.map((task) => [task.planKey, task]));
+    if (byKey.size !== tasks.length) {
+        const seen = new Set();
+        for (const task of tasks) {
+            if (seen.has(task.planKey))
+                fail(`duplicate planKey "${task.planKey}"`);
+            seen.add(task.planKey);
+        }
+    }
+    for (const task of tasks) {
+        if (task.dependsOn.includes(task.planKey))
+            fail(`task "${task.planKey}" depends on itself`);
+        for (const dependency of task.dependsOn) {
+            if (!byKey.has(dependency)) {
+                fail(`task "${task.planKey}" depends on unknown task "${dependency}"`);
+            }
+        }
+    }
+    // Iterative colouring; a cycle here means the plan must be re-cut, not patched.
+    const state = new Map();
+    const visit = (key, trail) => {
+        const current = state.get(key);
+        if (current === "done")
+            return;
+        if (current === "visiting")
+            fail(`dependency cycle: ${[...trail, key].join(" -> ")}`);
+        state.set(key, "visiting");
+        for (const dependency of byKey.get(key).dependsOn)
+            visit(dependency, [...trail, key]);
+        state.set(key, "done");
+    };
+    for (const task of tasks)
+        visit(task.planKey, []);
+}
+const FRONTMATTER = /^---\n([\s\S]*?)\n---/;
+const TASK_BLOCK = /```gateflow-task\n([\s\S]*?)\n```/g;
+function parsePlan(text) {
+    const match = text.match(FRONTMATTER);
+    if (!match)
+        fail("missing YAML frontmatter");
+    let meta;
+    try {
+        meta = yaml_1.default.parse(match[1]);
+    }
+    catch (error) {
+        fail(`frontmatter is not valid YAML: ${error.message}`);
+    }
+    if (!meta || typeof meta !== "object")
+        fail("frontmatter must be a mapping");
+    assertNoForbiddenFields(meta, "frontmatter");
+    assertNoSecretsOrPaths(meta, "frontmatter");
+    if (meta.schema !== exports.PLAN_SCHEMA)
+        fail(`schema must be "${exports.PLAN_SCHEMA}"`);
+    const taskId = nonEmptyString(meta.taskId, "frontmatter.taskId");
+    if (!SAFE_KEY.test(taskId))
+        fail("frontmatter.taskId must be lower-case alphanumeric with hyphens");
+    const revision = meta.revision;
+    if (!Number.isInteger(revision) || revision < 1)
+        fail("frontmatter.revision must be a positive integer");
+    const title = nonEmptyString(meta.title, "frontmatter.title");
+    // Each heading exactly once, in the fixed order.
+    const body = text.slice(match[0].length);
+    const headings = [...body.matchAll(/^## (.+)$/gm)].map((item) => item[1].trim());
+    if (headings.length !== exports.SECTIONS.length || exports.SECTIONS.some((section, index) => headings[index] !== section)) {
+        fail(`body must contain exactly these headings in order: ${exports.SECTIONS.map((s) => `## ${s}`).join(", ")}`);
+    }
+    const tasks = {};
+    const sections = {};
+    exports.SECTIONS.forEach((section, index) => {
+        const start = body.indexOf(`## ${section}`) + `## ${section}`.length;
+        const end = index + 1 < exports.SECTIONS.length ? body.indexOf(`## ${exports.SECTIONS[index + 1]}`) : body.length;
+        const chunk = body.slice(start, end);
+        const declared = meta.sections;
+        const fromFrontmatter = declared && typeof declared === "object" && !Array.isArray(declared)
+            ? declared[section]
+            : undefined;
+        const inline = chunk.match(/^\s*(enabled|disabled)\s*$/m)?.[1];
+        const state = (fromFrontmatter ?? inline);
+        if (state !== "enabled" && state !== "disabled") {
+            fail(`section "${section}" must declare "enabled" or "disabled"`);
+        }
+        sections[section] = state;
+        const parsed = [...chunk.matchAll(TASK_BLOCK)].map((block, order) => {
+            let value;
+            try {
+                value = JSON.parse(block[1]);
+            }
+            catch (error) {
+                fail(`section "${section}" task ${order + 1} is not valid JSON: ${error.message}`);
+            }
+            return parseTask(value, `section "${section}" task ${order + 1}`);
+        });
+        if (state === "disabled" && parsed.length > 0) {
+            fail(`section "${section}" is disabled but carries ${parsed.length} task(s)`);
+        }
+        tasks[section] = parsed;
+    });
+    const all = exports.SECTIONS.flatMap((section) => tasks[section]);
+    if (all.length === 0)
+        fail("plan contains no tasks in any enabled section");
+    assertDependencyGraph(all);
+    return {
+        schema: exports.PLAN_SCHEMA,
+        taskId,
+        revision: revision,
+        title,
+        sections,
+        updatedAt: nonEmptyString(meta.updatedAt ?? new Date(0).toISOString(), "frontmatter.updatedAt"),
+        tasks,
+    };
+}
+function renderPlan(plan) {
+    const frontmatter = yaml_1.default.stringify({
+        schema: exports.PLAN_SCHEMA,
+        taskId: plan.taskId,
+        revision: plan.revision,
+        title: plan.title,
+        sections: plan.sections,
+        updatedAt: plan.updatedAt,
+    }).trimEnd();
+    const body = exports.SECTIONS.map((section) => {
+        const blocks = plan.tasks[section]
+            .map((task) => `\n\`\`\`gateflow-task\n${JSON.stringify(task, null, 2)}\n\`\`\``)
+            .join("\n");
+        return `## ${section}\n\n${plan.sections[section]}${blocks}`;
+    }).join("\n\n");
+    return `---\n${frontmatter}\n---\n\n${body}\n`;
+}
+function readPlanFile(root, relative = exports.PLAN_FILE) {
+    const file = path_1.default.join(root, relative);
+    if (!fs_1.default.existsSync(file))
+        fail(`not found at ${relative}`);
+    return parsePlan(fs_1.default.readFileSync(file, "utf8"));
+}
+function writeAtomic(file, contents) {
+    fs_1.default.mkdirSync(path_1.default.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        fs_1.default.writeFileSync(temporary, contents);
+        fs_1.default.renameSync(temporary, file);
+    }
+    catch (error) {
+        if (fs_1.default.existsSync(temporary))
+            fs_1.default.unlinkSync(temporary);
+        throw error;
+    }
+}
+function writePlanFile(root, plan, relative = exports.PLAN_FILE) {
+    const file = path_1.default.join(root, relative);
+    writeAtomic(file, renderPlan(plan));
+    return file;
+}
+const emptyPlan = (taskId, title, sections) => ({
+    schema: exports.PLAN_SCHEMA,
+    taskId,
+    revision: 1,
+    title,
+    sections,
+    updatedAt: new Date().toISOString(),
+    tasks: { development: [], audit: [], deployment: [] },
+});
+exports.emptyPlan = emptyPlan;
+/** Deterministic summary for callers that only need to report what changed. */
+function planSummary(plan) {
+    const all = exports.SECTIONS.flatMap((section) => plan.tasks[section]);
+    return {
+        taskId: plan.taskId,
+        revision: plan.revision,
+        sections: plan.sections,
+        taskCount: all.length,
+        tasks: exports.SECTIONS.flatMap((section) => plan.tasks[section].map((task) => ({
+            planKey: task.planKey,
+            section,
+            status: task.status,
+            dependsOn: task.dependsOn,
+        }))),
+    };
+}
+//# sourceMappingURL=plan.js.map

package/dist-runtime/workflow/lib/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../runtime/workflow/lib/plan.ts"],"names":[],"mappings":"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"}

package/dist-runtime/workflow/lib/planCli.d.ts

@@ -0,0 +1,14 @@
+import { emptyPlan, type PlanTask } from "./plan";
+export declare const runPlanReadCli: (argv: string[], root?: string) => Record<string, unknown>;
+/**
+ * Replace the plan. `revision` is not taken from the caller: the writer owns it,
+ * because it is the one number every consumer depends on and the one easiest to
+ * get wrong by hand. It advances only when the execution contract changes.
+ */
+export declare const runPlanWriteCli: (argv: string[], root?: string) => Record<string, unknown>;
+/** Append one task, advancing the revision. The common case, so it gets a verb. */
+export declare const runPlanAddCli: (argv: string[], root?: string) => Record<string, unknown>;
+export declare const contractOf: (task: PlanTask) => string;
+/** Move one task's status: `--task <planKey> --to <status>`. */
+export declare const runPlanStatusCli: (argv: string[], root?: string) => Record<string, unknown>;
+export { emptyPlan };

package/dist-runtime/workflow/lib/planCli.js

@@ -0,0 +1,279 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptyPlan = exports.runPlanStatusCli = exports.contractOf = exports.runPlanAddCli = exports.runPlanWriteCli = exports.runPlanReadCli = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const plan_1 = require("./plan");
+Object.defineProperty(exports, "emptyPlan", { enumerable: true, get: function () { return plan_1.emptyPlan; } });
+/**
+ * `plan-read` / `plan-write` / `plan-add`.
+ *
+ * The three exist so the plan never has to be hand-written. In a document that
+ * two runtimes both produce and consume, the fields most likely to be wrong are
+ * exactly the mechanical ones -- revision accounting, the section headings, the
+ * block syntax, the forbidden-field rules -- and those are the ones a command
+ * can own outright. The LLM's job is the objective and the acceptance criteria;
+ * the file's shape is not its job.
+ */
+const parseArgs = (argv) => {
+    const values = new Map();
+    for (let index = 0; index < argv.length; index += 1) {
+        const item = argv[index];
+        if (!item.startsWith("--"))
+            continue;
+        const equalAt = item.indexOf("=");
+        const key = item.slice(2, equalAt > 2 ? equalAt : undefined);
+        const next = argv[index + 1];
+        // A trailing flag with no value is a switch, not a malformed option.
+        if (equalAt < 0 && (!next || next.startsWith("--"))) {
+            values.set(key, "true");
+            continue;
+        }
+        const value = equalAt > 2 ? item.slice(equalAt + 1) : next;
+        if (!value || value.startsWith("--"))
+            throw new Error(`--${key} requires a value`);
+        if (values.has(key))
+            throw new Error(`--${key} may be provided only once`);
+        values.set(key, value.trim());
+        if (equalAt < 0)
+            index += 1;
+    }
+    return values;
+};
+const readJsonInput = (values, root) => {
+    const inline = values.get("input");
+    const file = values.get("inputFile");
+    if (inline && file)
+        throw new Error("--input and --inputFile are mutually exclusive");
+    if (file) {
+        const absolute = path_1.default.isAbsolute(file) ? file : path_1.default.join(root, file);
+        if (!fs_1.default.existsSync(absolute))
+            throw new Error(`--inputFile not found: ${file}`);
+        return JSON.parse(fs_1.default.readFileSync(absolute, "utf8"));
+    }
+    if (inline)
+        return JSON.parse(inline);
+    throw new Error("--input or --inputFile is required");
+};
+const asRecord = (value, label) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be a JSON object`);
+    }
+    return value;
+};
+const parseSections = (value) => {
+    const record = value === undefined ? {} : asRecord(value, "sections");
+    const read = (key, fallback) => {
+        const raw = record[key] ?? fallback;
+        if (raw !== "enabled" && raw !== "disabled") {
+            throw new Error(`sections.${key} must be "enabled" or "disabled"`);
+        }
+        return raw;
+    };
+    return {
+        development: read("development", "enabled"),
+        audit: read("audit", "enabled"),
+        deployment: read("deployment", "enabled"),
+    };
+};
+/** A task from the caller, without the fields the writer owns. */
+const toTask = (value, where) => {
+    const record = asRecord(value, where);
+    return {
+        planKey: String(record.planKey ?? ""),
+        title: String(record.title ?? ""),
+        objective: String(record.objective ?? ""),
+        acceptance: Array.isArray(record.acceptance) ? record.acceptance.map(String) : [],
+        dependsOn: Array.isArray(record.dependsOn) ? record.dependsOn.map(String) : [],
+        status: (record.status ?? "pending"),
+        ...(record.scope !== undefined ? { scope: asRecord(record.scope, `${where}.scope`) } : {}),
+        ...(record.parameters !== undefined
+            ? { parameters: (() => {
+                    if (!Array.isArray(record.parameters))
+                        throw new Error(`${where}.parameters must be an array`);
+                    return record.parameters;
+                })() }
+            : {}),
+        ...(record.expectedArtifacts !== undefined
+            ? { expectedArtifacts: record.expectedArtifacts.map(String) }
+            : {}),
+        ...(record.allowedChanges !== undefined
+            ? { allowedChanges: record.allowedChanges.map(String) }
+            : {}),
+    };
+};
+const sectionOf = (value) => {
+    const section = String(value ?? "development");
+    if (section !== "development" && section !== "audit" && section !== "deployment") {
+        throw new Error(`--section must be development, audit or deployment (got "${section}")`);
+    }
+    return section;
+};
+const runPlanReadCli = (argv, root = process.cwd()) => {
+    const values = parseArgs(argv);
+    const plan = (0, plan_1.readPlanFile)(root, values.get("path") || plan_1.PLAN_FILE);
+    return values.has("full")
+        ? { ...(0, plan_1.planSummary)(plan), plan: (0, plan_1.renderPlan)(plan) }
+        : (0, plan_1.planSummary)(plan);
+};
+exports.runPlanReadCli = runPlanReadCli;
+/**
+ * Replace the plan. `revision` is not taken from the caller: the writer owns it,
+ * because it is the one number every consumer depends on and the one easiest to
+ * get wrong by hand. It advances only when the execution contract changes.
+ */
+const runPlanWriteCli = (argv, root = process.cwd()) => {
+    const values = parseArgs(argv);
+    const input = asRecord(readJsonInput(values, root), "--input");
+    (0, plan_1.assertPortableInput)(input, "--input");
+    const relative = values.get("path") || plan_1.PLAN_FILE;
+    const sections = parseSections(input.sections);
+    const tasksInput = input.tasks;
+    const tasks = { development: [], audit: [], deployment: [] };
+    if (tasksInput !== undefined) {
+        const record = asRecord(tasksInput, "tasks");
+        for (const section of ["development", "audit", "deployment"]) {
+            const list = record[section];
+            if (list === undefined)
+                continue;
+            if (!Array.isArray(list))
+                throw new Error(`tasks.${section} must be an array`);
+            tasks[section] = list.map((item, index) => toTask(item, `tasks.${section}[${index}]`));
+        }
+    }
+    const existing = fs_1.default.existsSync(path_1.default.join(root, relative)) ? (0, plan_1.readPlanFile)(root, relative) : undefined;
+    const previousContracts = existing
+        ? new Map(["development", "audit", "deployment"]
+            .flatMap((section) => existing.tasks[section])
+            .map((task) => [task.planKey, (0, exports.contractOf)(task)]))
+        : new Map();
+    const nextAll = ["development", "audit", "deployment"].flatMap((section) => tasks[section]);
+    let revision = existing ? existing.revision : 1;
+    if (existing) {
+        const changed = nextAll.length !== previousContracts.size
+            || nextAll.some((task) => previousContracts.get(task.planKey) !== (0, exports.contractOf)(task))
+            || JSON.stringify(existing.sections) !== JSON.stringify(sections);
+        if (changed)
+            revision = existing.revision + 1;
+    }
+    const plan = {
+        schema: "gateflow-plan/v1",
+        taskId: String(input.taskId ?? existing?.taskId ?? ""),
+        revision,
+        title: String(input.title ?? existing?.title ?? ""),
+        sections,
+        updatedAt: new Date().toISOString(),
+        tasks,
+    };
+    // The writer is the one place the document is produced, so the whole plan is
+    // validated on the way out -- same checks an import would run.
+    const text = (0, plan_1.renderPlan)(plan);
+    const validated = (0, plan_1.parsePlan)(text);
+    fs_1.default.mkdirSync(path_1.default.dirname(path_1.default.join(root, relative)), { recursive: true });
+    fs_1.default.writeFileSync(path_1.default.join(root, relative), text);
+    const added = nextAll.filter((task) => !previousContracts.has(task.planKey)).map((task) => task.planKey);
+    const removed = [...previousContracts.keys()].filter((key) => !nextAll.some((task) => task.planKey === key));
+    return {
+        ...(0, plan_1.planSummary)(validated),
+        path: relative,
+        revisionBumped: !existing || revision !== existing.revision,
+        added,
+        // Reported, never silently applied: dropping a task from the file makes it
+        // look like it never existed to the other entry point.
+        removed,
+        ...(removed.length > 0
+            ? { warning: `tasks were dropped from the plan: ${removed.join(", ")}. Cancelling (status=cancelled) is usually what you want instead.` }
+            : {}),
+    };
+};
+exports.runPlanWriteCli = runPlanWriteCli;
+/** Append one task, advancing the revision. The common case, so it gets a verb. */
+const runPlanAddCli = (argv, root = process.cwd()) => {
+    const values = parseArgs(argv);
+    const input = asRecord(readJsonInput(values, root), "--input");
+    (0, plan_1.assertPortableInput)(input, "--input");
+    const relative = values.get("path") || plan_1.PLAN_FILE;
+    const plan = (0, plan_1.readPlanFile)(root, relative);
+    const section = sectionOf(input.section);
+    const task = toTask(input.task ?? input, "task");
+    if (plan.sections[section] === "disabled") {
+        throw new Error(`section "${section}" is disabled; enable it before adding tasks`);
+    }
+    const existingKeys = ["development", "audit", "deployment"]
+        .flatMap((item) => plan.tasks[item])
+        .map((item) => item.planKey);
+    if (existingKeys.includes(task.planKey)) {
+        throw new Error(`planKey "${task.planKey}" already exists; plan keys are stable identities, not labels`);
+    }
+    const next = {
+        ...plan,
+        revision: plan.revision + 1,
+        updatedAt: new Date().toISOString(),
+        tasks: { ...plan.tasks, [section]: [...plan.tasks[section], task] },
+    };
+    const text = (0, plan_1.renderPlan)(next);
+    (0, plan_1.parsePlan)(text);
+    fs_1.default.writeFileSync(path_1.default.join(root, relative), text);
+    return { ...(0, plan_1.planSummary)(next), path: relative, section, added: task.planKey };
+};
+exports.runPlanAddCli = runPlanAddCli;
+const contractOf = (task) => JSON.stringify({
+    objective: task.objective,
+    acceptance: task.acceptance,
+    dependsOn: task.dependsOn,
+    scope: task.scope ?? null,
+    parameters: task.parameters ?? null,
+    expectedArtifacts: task.expectedArtifacts ?? null,
+    allowedChanges: task.allowedChanges ?? null,
+});
+exports.contractOf = contractOf;
+/**
+ * Status moves the protocol allows. Progress is not a contract change, so it
+ * never advances the revision -- otherwise every completed task would look
+ * like a re-plan to the other entry point.
+ */
+const STATUS_MOVES = {
+    pending: ["ready", "running", "cancelled"],
+    ready: ["running", "cancelled"],
+    running: ["completed", "failed"],
+    failed: ["ready", "running", "cancelled"],
+    completed: ["pending"],
+    cancelled: [],
+};
+/** Move one task's status: `--task <planKey> --to <status>`. */
+const runPlanStatusCli = (argv, root = process.cwd()) => {
+    const values = parseArgs(argv);
+    const relative = values.get("path") || plan_1.PLAN_FILE;
+    const planKey = values.get("task");
+    const to = values.get("to");
+    if (!planKey)
+        throw new Error("--task <planKey> is required");
+    if (!to || !(to in STATUS_MOVES))
+        throw new Error(`--to must be one of ${Object.keys(STATUS_MOVES).join(", ")}`);
+    const plan = (0, plan_1.readPlanFile)(root, relative);
+    const all = ["development", "audit", "deployment"].flatMap((section) => plan.tasks[section]);
+    const task = all.find((item) => item.planKey === planKey);
+    if (!task)
+        throw new Error(`task "${planKey}" not found`);
+    const from = task.status;
+    if (from === to)
+        return { ...(0, plan_1.planSummary)(plan), path: relative, planKey, from, to, changed: false };
+    if (!STATUS_MOVES[from].includes(to))
+        throw new Error(`task "${planKey}" cannot move from ${from} to ${to}`);
+    if (to === "running") {
+        const blocked = task.dependsOn.filter((key) => all.find((item) => item.planKey === key)?.status !== "completed");
+        if (blocked.length > 0)
+            throw new Error(`task "${planKey}" depends on unfinished task(s): ${blocked.join(", ")}`);
+    }
+    task.status = to;
+    const next = { ...plan, updatedAt: new Date().toISOString() };
+    const text = (0, plan_1.renderPlan)(next);
+    (0, plan_1.parsePlan)(text);
+    fs_1.default.writeFileSync(path_1.default.join(root, relative), text);
+    return { ...(0, plan_1.planSummary)(next), path: relative, planKey, from, to, changed: true };
+};
+exports.runPlanStatusCli = runPlanStatusCli;
+//# sourceMappingURL=planCli.js.map