gate-evm-tools 1.0.28 → 1.2.0

package/runtime/workflow/lib/plan.ts

@@ -0,0 +1,334 @@
+import fs from "fs";
+import path from "path";
+import YAML from "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.
+ */
+
+export const PLAN_SCHEMA = "gateflow-plan/v1";
+export const PLAN_FILE = "handoff.md";
+export const SECTIONS = ["development", "audit", "deployment"] as const;
+export type PlanSection = (typeof SECTIONS)[number];
+
+export const TASK_STATUSES = ["pending", "ready", "running", "completed", "failed", "cancelled"] as const;
+export type TaskStatus = (typeof TASK_STATUSES)[number];
+
+/** 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",
+];
+
+export interface PlanTask {
+  planKey: string;
+  title: string;
+  objective: string;
+  acceptance: string[];
+  dependsOn: string[];
+  status: TaskStatus;
+  scope?: Record<string, unknown>;
+  parameters?: unknown[];
+  expectedArtifacts?: string[];
+  allowedChanges?: string[];
+}
+
+export interface Plan {
+  schema: string;
+  taskId: string;
+  revision: number;
+  title: string;
+  sections: Record<PlanSection, "enabled" | "disabled">;
+  updatedAt: string;
+  tasks: Record<PlanSection, PlanTask[]>;
+}
+
+const SAFE_KEY = /^[a-z0-9][a-z0-9-]{0,199}$/;
+
+function fail(message: string): never {
+  throw new Error(`handoff.md: ${message}`);
+}
+
+function normalizeFieldName(key: string): string {
+  return key.replace(/[_-]/g, "").toLowerCase();
+}
+
+/** Recursive, because a forbidden name is just as bad nested as at the top. */
+function assertNoForbiddenFields(value: unknown, where: string): void {
+  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: unknown, where: string): void {
+  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.
+ */
+export function assertPortableInput(value: unknown, where: string): void {
+  assertNoForbiddenFields(value, where);
+  assertNoSecretsOrPaths(value, where);
+}
+
+function nonEmptyString(value: unknown, where: string): string {
+  if (typeof value !== "string" || !value.trim()) fail(`${where} must be a non-empty string`);
+  return value;
+}
+
+function stringArray(value: unknown, where: string, options: { min?: number } = {}): string[] {
+  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: unknown, where: string): PlanTask {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) fail(`${where} must be an object`);
+  const value = raw as Record<string, unknown>;
+  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 (!(TASK_STATUSES as readonly string[]).includes(status)) {
+    fail(`${where}.status must be one of ${TASK_STATUSES.join(", ")}`);
+  }
+  const task: PlanTask = {
+    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 as TaskStatus,
+  };
+  if (value.scope !== undefined) task.scope = value.scope as Record<string, unknown>;
+  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: PlanTask[]): void {
+  const byKey = new Map(tasks.map((task) => [task.planKey, task]));
+  if (byKey.size !== tasks.length) {
+    const seen = new Set<string>();
+    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<string, "visiting" | "done">();
+  const visit = (key: string, trail: string[]): void => {
+    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;
+
+export function parsePlan(text: string): Plan {
+  const match = text.match(FRONTMATTER);
+  if (!match) fail("missing YAML frontmatter");
+  let meta: Record<string, unknown>;
+  try {
+    meta = YAML.parse(match[1]) as Record<string, unknown>;
+  } catch (error) {
+    fail(`frontmatter is not valid YAML: ${(error as Error).message}`);
+  }
+  if (!meta || typeof meta !== "object") fail("frontmatter must be a mapping");
+  assertNoForbiddenFields(meta, "frontmatter");
+  assertNoSecretsOrPaths(meta, "frontmatter");
+
+  if (meta.schema !== PLAN_SCHEMA) fail(`schema must be "${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 as number) < 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 !== SECTIONS.length || SECTIONS.some((section, index) => headings[index] !== section)) {
+    fail(`body must contain exactly these headings in order: ${SECTIONS.map((s) => `## ${s}`).join(", ")}`);
+  }
+
+  const tasks = {} as Record<PlanSection, PlanTask[]>;
+  const sections = {} as Record<PlanSection, "enabled" | "disabled">;
+  SECTIONS.forEach((section, index) => {
+    const start = body.indexOf(`## ${section}`) + `## ${section}`.length;
+    const end = index + 1 < SECTIONS.length ? body.indexOf(`## ${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 as Record<string, unknown>)[section]
+      : undefined;
+    const inline = chunk.match(/^\s*(enabled|disabled)\s*$/m)?.[1];
+    const state = (fromFrontmatter ?? inline) as string | undefined;
+    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: unknown;
+      try {
+        value = JSON.parse(block[1]);
+      } catch (error) {
+        fail(`section "${section}" task ${order + 1} is not valid JSON: ${(error as 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 = SECTIONS.flatMap((section) => tasks[section]);
+  if (all.length === 0) fail("plan contains no tasks in any enabled section");
+  assertDependencyGraph(all);
+
+  return {
+    schema: PLAN_SCHEMA,
+    taskId,
+    revision: revision as number,
+    title,
+    sections,
+    updatedAt: nonEmptyString(meta.updatedAt ?? new Date(0).toISOString(), "frontmatter.updatedAt"),
+    tasks,
+  };
+}
+
+export function renderPlan(plan: Plan): string {
+  const frontmatter = YAML.stringify({
+    schema: PLAN_SCHEMA,
+    taskId: plan.taskId,
+    revision: plan.revision,
+    title: plan.title,
+    sections: plan.sections,
+    updatedAt: plan.updatedAt,
+  }).trimEnd();
+  const body = 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`;
+}
+
+export function readPlanFile(root: string, relative: string = PLAN_FILE): Plan {
+  const file = path.join(root, relative);
+  if (!fs.existsSync(file)) fail(`not found at ${relative}`);
+  return parsePlan(fs.readFileSync(file, "utf8"));
+}
+
+function writeAtomic(file: string, contents: string): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, contents);
+    fs.renameSync(temporary, file);
+  } catch (error) {
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+    throw error;
+  }
+}
+
+export function writePlanFile(root: string, plan: Plan, relative: string = PLAN_FILE): string {
+  const file = path.join(root, relative);
+  writeAtomic(file, renderPlan(plan));
+  return file;
+}
+
+export const emptyPlan = (taskId: string, title: string, sections: Record<PlanSection, "enabled" | "disabled">): Plan => ({
+  schema: PLAN_SCHEMA,
+  taskId,
+  revision: 1,
+  title,
+  sections,
+  updatedAt: new Date().toISOString(),
+  tasks: { development: [], audit: [], deployment: [] },
+});
+
+/** Deterministic summary for callers that only need to report what changed. */
+export function planSummary(plan: Plan): Record<string, unknown> {
+  const all = SECTIONS.flatMap((section) => plan.tasks[section]);
+  return {
+    taskId: plan.taskId,
+    revision: plan.revision,
+    sections: plan.sections,
+    taskCount: all.length,
+    tasks: SECTIONS.flatMap((section) => plan.tasks[section].map((task) => ({
+      planKey: task.planKey,
+      section,
+      status: task.status,
+      dependsOn: task.dependsOn,
+    }))),
+  };
+}

package/runtime/workflow/lib/planCli.ts

@@ -0,0 +1,279 @@
+import fs from "fs";
+import path from "path";
+import {
+  PLAN_FILE,
+  assertPortableInput,
+  emptyPlan,
+  parsePlan,
+  planSummary,
+  readPlanFile,
+  renderPlan,
+  type Plan,
+  type PlanSection,
+  type PlanTask,
+} from "./plan";
+
+/**
+ * `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: string[]): Map<string, string> => {
+  const values = new Map<string, string>();
+  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: Map<string, string>, root: string): unknown => {
+  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.isAbsolute(file) ? file : path.join(root, file);
+    if (!fs.existsSync(absolute)) throw new Error(`--inputFile not found: ${file}`);
+    return JSON.parse(fs.readFileSync(absolute, "utf8"));
+  }
+  if (inline) return JSON.parse(inline);
+  throw new Error("--input or --inputFile is required");
+};
+
+const asRecord = (value: unknown, label: string): Record<string, unknown> => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be a JSON object`);
+  }
+  return value as Record<string, unknown>;
+};
+
+const parseSections = (value: unknown): Record<PlanSection, "enabled" | "disabled"> => {
+  const record = value === undefined ? {} : asRecord(value, "sections");
+  const read = (key: PlanSection, fallback: "enabled" | "disabled") => {
+    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: unknown, where: string): PlanTask => {
+  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") as PlanTask["status"],
+    ...(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 as unknown[]).map(String) }
+      : {}),
+    ...(record.allowedChanges !== undefined
+      ? { allowedChanges: (record.allowedChanges as unknown[]).map(String) }
+      : {}),
+  };
+};
+
+const sectionOf = (value: unknown): PlanSection => {
+  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;
+};
+
+export const runPlanReadCli = (argv: string[], root: string = process.cwd()): Record<string, unknown> => {
+  const values = parseArgs(argv);
+  const plan = readPlanFile(root, values.get("path") || PLAN_FILE);
+  return values.has("full")
+    ? { ...planSummary(plan), plan: renderPlan(plan) }
+    : planSummary(plan);
+};
+
+/**
+ * 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 const runPlanWriteCli = (argv: string[], root: string = process.cwd()): Record<string, unknown> => {
+  const values = parseArgs(argv);
+  const input = asRecord(readJsonInput(values, root), "--input");
+  assertPortableInput(input, "--input");
+  const relative = values.get("path") || PLAN_FILE;
+  const sections = parseSections(input.sections);
+  const tasksInput = input.tasks;
+  const tasks: Record<PlanSection, PlanTask[]> = { development: [], audit: [], deployment: [] };
+  if (tasksInput !== undefined) {
+    const record = asRecord(tasksInput, "tasks");
+    for (const section of ["development", "audit", "deployment"] as const) {
+      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.existsSync(path.join(root, relative)) ? readPlanFile(root, relative) : undefined;
+
+  const previousContracts = existing
+    ? new Map((["development", "audit", "deployment"] as const)
+      .flatMap((section) => existing.tasks[section])
+      .map((task) => [task.planKey, contractOf(task)]))
+    : new Map<string, string>();
+  const nextAll = (["development", "audit", "deployment"] as const).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) !== contractOf(task))
+      || JSON.stringify(existing.sections) !== JSON.stringify(sections);
+    if (changed) revision = existing.revision + 1;
+  }
+
+  const plan: 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 = renderPlan(plan);
+  const validated = parsePlan(text);
+  fs.mkdirSync(path.dirname(path.join(root, relative)), { recursive: true });
+  fs.writeFileSync(path.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 {
+    ...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.` }
+      : {}),
+  };
+};
+
+/** Append one task, advancing the revision. The common case, so it gets a verb. */
+export const runPlanAddCli = (argv: string[], root: string = process.cwd()): Record<string, unknown> => {
+  const values = parseArgs(argv);
+  const input = asRecord(readJsonInput(values, root), "--input");
+  assertPortableInput(input, "--input");
+  const relative = values.get("path") || PLAN_FILE;
+  const plan = 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"] as const)
+    .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 = {
+    ...plan,
+    revision: plan.revision + 1,
+    updatedAt: new Date().toISOString(),
+    tasks: { ...plan.tasks, [section]: [...plan.tasks[section], task] },
+  };
+  const text = renderPlan(next);
+  parsePlan(text);
+  fs.writeFileSync(path.join(root, relative), text);
+  return { ...planSummary(next), path: relative, section, added: task.planKey };
+};
+
+export const contractOf = (task: PlanTask): string => 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,
+});
+
+/**
+ * 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: Record<PlanTask["status"], readonly PlanTask["status"][]> = {
+  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>`. */
+export const runPlanStatusCli = (argv: string[], root: string = process.cwd()): Record<string, unknown> => {
+  const values = parseArgs(argv);
+  const relative = values.get("path") || PLAN_FILE;
+  const planKey = values.get("task");
+  const to = values.get("to") as PlanTask["status"] | undefined;
+  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 = readPlanFile(root, relative);
+  const all = (["development", "audit", "deployment"] as const).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 { ...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 = { ...plan, updatedAt: new Date().toISOString() };
+  const text = renderPlan(next);
+  parsePlan(text);
+  fs.writeFileSync(path.join(root, relative), text);
+  return { ...planSummary(next), path: relative, planKey, from, to, changed: true };
+};
+
+export { emptyPlan };

package/runtime/workflow/lib/preparationEvidence.ts

@@ -0,0 +1,14 @@
+import path from 'node:path';
+import type { WorkflowContext } from './context';
+import type { DeploymentChange } from './deploymentRecords';
+import type { PreparedGateToolWorkflow } from './gateTool';
+export function recordPreparedDeployment(context: WorkflowContext, change: DeploymentChange, prepared: PreparedGateToolWorkflow, derivedKeys: string[]): void {
+  if (!context.preparations) return;
+  const ref = (file: string) => path.isAbsolute(file) ? path.relative(context.root, file).split(path.sep).join('/') : file;
+  const planPath = ref(prepared.planPath);
+  // Step structs use optional undefined properties; immutable journal input is explicit JSON data.
+  const clean = Object.fromEntries(Object.entries(change).filter(([, value]) => value !== undefined));
+  clean.gateTool = { outputPath: planPath, data: prepared.plan };
+  context.preparations.prepare({ stepId: change.stepId, change: clean as unknown as DeploymentChange,
+    prepared: { ...prepared, requestPath: ref(prepared.requestPath), planPath }, derivedKeys });
+}

package/runtime/workflow/lib/proxy.ts

@@ -1,5 +1,5 @@
 import { keccak256, toUtf8Bytes } from "ethers";
-import { ethers } from "../../projectHardhat";
+import type { Provider } from "ethers";
 import {
   getERC1967Admin,
   getERC1967Implementation,
@@ -10,6 +10,7 @@ export interface ProxyOptions {
   initializer?: string | false;
   unsafeAllow?: string[];
   constructorArgs?: unknown[];
+  adminOwner?: string;
 }
 
 export interface FirstUpgradeOptions {
@@ -31,9 +32,10 @@ export const deriveImplementationSalt = (
 );
 
 export const getImplementationAddress = async (
+  provider: Pick<Provider, "getStorage">,
   proxyAddress: string,
 ): Promise<string> => {
-  const implementation = await getERC1967Implementation(ethers.provider, proxyAddress);
+  const implementation = await getERC1967Implementation(provider, proxyAddress);
   if (!implementation) {
     throw new Error(`Proxy ${proxyAddress} has no ERC-1967 implementation`);
   }
@@ -41,5 +43,6 @@ export const getImplementationAddress = async (
 };
 
 export const getProxyAdminAddress = async (
+  provider: Pick<Provider, "getStorage">,
   proxyAddress: string,
-): Promise<string | undefined> => getERC1967Admin(ethers.provider, proxyAddress);
+): Promise<string | undefined> => getERC1967Admin(provider, proxyAddress);