@loomhelm/multi-task-flow 0.0.0-stage → 0.2.6

package/toolkit/skills/multi-task-flow/tests/output-events.test.ts

@@ -0,0 +1,36 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync, realpathSync, mkdirSync, rmSync, writeFileSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRunDashboard } from "../lib/server";
+import { LedgerStore } from "../lib/store";
+import { createDemoLedger } from "../examples/orchestration-viewer/ledger";
+import type { JsonRecord } from "../lib/codex-agent-api";
+
+test("SSE output and API snapshots update with an unchanged ledger; cancellation closes the observer", async () => {
+  const root = mkdtempSync(join(realpathSync(tmpdir()), "output-events-"));
+  const assets = join(root, "assets"); mkdirSync(assets); writeFileSync(join(assets, "index.html"), "demo");
+  const ledger = createDemoLedger(1_767_200_000_000); ledger.orchestration_id = "run";
+  const store = new LedgerStore(root, "run"); store.create(ledger);
+  const before = readFileSync(store.ledgerPath, "utf8");
+  let notify!: (event: JsonRecord) => void; let closes = 0;
+  const run = createRunDashboard({ root, runId: "run", assetsDir: assets, port: 0, connectObserver: async callback => { notify = callback; return { request: async () => ({ data: [] }), close: () => { closes++; } }; } });
+  const request = (path: string) => run.handle(new Request("http://127.0.0.1" + path), { timeout() {} }, path);
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  try {
+    const response = await request("/api/events"); reader = response.body!.getReader();
+    await reader.read(); await new Promise(resolve => setTimeout(resolve, 0));
+    const initial = await (await request("/api/view")).json();
+    const task = ledger.tasks.find(t => t.thread_id)!;
+    notify({ method: "item/completed", params: { threadId: task.thread_id, turnId: "turn", item: { id: "final", type: "agentMessage", phase: "final_answer", text: "native final" } } });
+    const after = await (await request("/api/view")).json();
+    expect(after.revision).toBe(initial.revision);
+    expect(after.output_revision).toBeGreaterThan(initial.output_revision);
+    expect(after.view.tasks.find((t: any) => t.id === task.id).latest_agent_output.text).toBe("native final");
+    let payload = "";
+    while (!payload.includes("native final")) { const part = await reader.read(); if (part.done) break; payload += new TextDecoder().decode(part.value); }
+    expect(payload).toContain("event: agent-output");
+    expect(readFileSync(store.ledgerPath, "utf8")).toBe(before);
+    await reader.cancel(); expect(closes).toBe(1); expect(run.subscriberCount).toBe(0);
+  } finally { await reader?.cancel(); run.stop(); rmSync(root, { recursive: true, force: true }); }
+}, 5000);

package/toolkit/skills/multi-task-flow/tests/phase.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, test } from "bun:test";
+import { defaultTabForPhase, derivePhase } from "../web/phase";
+
+describe("dashboard display phase", () => {
+  test("stays in planning until a real task start fact exists", () => {
+    expect(derivePhase([{ started_at: null }, { started_at: null }])).toBe("planning");
+    expect(defaultTabForPhase("planning")).toBe("graph");
+  });
+
+  test("becomes execution monotonically when any task has started", () => {
+    expect(derivePhase([{ started_at: null }, { started_at: "2026-01-01T00:00:00.000Z" }])).toBe("execution");
+    expect(defaultTabForPhase("execution")).toBe("actual");
+  });
+});

package/toolkit/skills/multi-task-flow/tests/pr-details.test.ts

@@ -0,0 +1,30 @@
+import { expect, test } from "bun:test";
+import { PRDetailsCache, summarizeChecks } from "../lib/pr-details";
+const repo = { host: "github.com", owner: "owner", name: "repo" };
+const url = "https://github.com/owner/repo/pull/42";
+test("PR cache deduplicates flights, throttles manual refresh and preserves stale success", async () => {
+  let now = 100_000, calls = 0, fail = false;
+  const cache = new PRDetailsCache(async args => {
+    calls++; expect(args).toEqual(["pr", "view", "42", "--repo", "github.com/owner/repo", "--json", "number,title,url,state,mergedAt,mergeable,statusCheckRollup"]);
+    await Promise.resolve();
+    if (fail) throw new Error("private failure text");
+    return JSON.stringify({ number: 42, title: "PR title", url, state: "MERGED", mergedAt: "2026-11-07T00:00:00Z", mergeable: "UNKNOWN", statusCheckRollup: [{ name: "checks", conclusion: "SUCCESS" }] });
+  }, () => now);
+  const [a, b] = await Promise.all([cache.read(repo, url), cache.read(repo, url)]);
+  expect(calls).toBe(1); expect(a).toEqual(b); expect(a.data?.state).toBe("MERGED");
+  await cache.read(repo, url, true); expect(calls).toBe(1);
+  now += 31_000; fail = true;
+  const stale = await cache.read(repo, url, true); expect(stale.data?.title).toBe("PR title"); expect(stale.stale).toBe(true); expect(stale.error).not.toContain("private");
+});
+test("PR identity rejects foreign repositories and URL syntax before spawning", async () => {
+  let calls = 0; const cache = new PRDetailsCache(async () => { calls++; return "{}"; });
+  for (const bad of ["https://github.com/other/repo/pull/42", "https://evil.test/owner/repo/pull/42", url + "?repo=other", "https://user:pass@github.com/owner/repo/pull/42", "http://github.com/owner/repo/pull/42", "https://github.com/owner/repo/pull/-1"]) await expect(cache.read(repo, bad)).rejects.toThrow();
+  expect(calls).toBe(0);
+});
+test("CI summary distinguishes absence, uncertainty, pending and non-success terminal checks", () => {
+  expect(summarizeChecks(null)).toBe("未知"); expect(summarizeChecks([])).toBe("未配置");
+  for (const state of ["CANCELLED", "TIMED_OUT", "ACTION_REQUIRED", "FAILURE"]) expect(summarizeChecks([{ conclusion: state }])).toBe("失败");
+  expect(summarizeChecks([{ state: "PENDING" }])).toBe("运行中");
+  expect(summarizeChecks([{ conclusion: "SKIPPED" }, { conclusion: "NEUTRAL" }])).toBe("成功");
+  expect(summarizeChecks([{ conclusion: "NEW_STATE" }])).toBe("未知");
+});

package/toolkit/skills/multi-task-flow/tests/preferences.test.ts

@@ -0,0 +1,60 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { GlobalPreferencesStore } from "../lib/preferences";
+
+const roots: string[] = [];
+afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
+
+describe("global UI preferences", () => {
+  test("falls back to system without creating a preference file", () => {
+    const root = realpathSync(mkdtempSync(join(realpathSync(tmpdir()), "orchestration-preferences-"))); roots.push(root);
+    const store = new GlobalPreferencesStore(root);
+    expect(store.read()).toEqual({ schema_version: 1, theme: "system" });
+    expect(existsSync(store.path)).toBe(false);
+  });
+
+  test("recovers from corrupt data and writes an atomic 0600 schema-1 value", () => {
+    const root = realpathSync(mkdtempSync(join(realpathSync(tmpdir()), "orchestration-preferences-"))); roots.push(root);
+    const store = new GlobalPreferencesStore(root);
+    writeFileSync(store.path, "not-json\n", { mode: 0o600 });
+    expect(store.read().theme).toBe("system");
+    expect(store.write("dark")).toEqual({ schema_version: 1, theme: "dark" });
+    expect(JSON.parse(readFileSync(store.path, "utf8"))).toEqual({ schema_version: 1, theme: "dark" });
+    expect(statSync(store.path).mode & 0o777).toBe(0o600);
+    expect([...new Bun.Glob(".ledger-*.tmp").scanSync(root)].length).toBe(0);
+  });
+
+  test("does not accept unsupported themes", () => {
+    const root = realpathSync(mkdtempSync(join(realpathSync(tmpdir()), "orchestration-preferences-"))); roots.push(root);
+    const store = new GlobalPreferencesStore(root);
+    expect(() => store.write("blue" as never)).toThrow();
+  });
+
+  test("accepts a lock created by a concurrent initializer", () => {
+    const root = realpathSync(mkdtempSync(join(realpathSync(tmpdir()), "orchestration-preferences-"))); roots.push(root);
+    const first = new GlobalPreferencesStore(root);
+    const second = new GlobalPreferencesStore(root);
+    expect(first.lockPath).toBe(second.lockPath);
+    expect(second.read().theme).toBe("system");
+  });
+
+  test("tightens an existing preference lock to 0600", () => {
+    const root = realpathSync(mkdtempSync(join(realpathSync(tmpdir()), "orchestration-preferences-"))); roots.push(root);
+    const first = new GlobalPreferencesStore(root);
+    chmodSync(first.lockPath, 0o666);
+    new GlobalPreferencesStore(root);
+    expect(statSync(first.lockPath).mode & 0o777).toBe(0o600);
+  });
+
+  test("falls back for a special preference path and rejects a special lock path", () => {
+    const root = realpathSync(mkdtempSync(join(realpathSync(tmpdir()), "orchestration-preferences-"))); roots.push(root);
+    const store = new GlobalPreferencesStore(root);
+    mkdirSync(store.path);
+    expect(store.read().theme).toBe("system");
+    rmSync(store.lockPath);
+    mkdirSync(store.lockPath);
+    expect(() => store.read()).toThrow();
+  });
+});

package/toolkit/skills/multi-task-flow/tests/revisions.test.ts

@@ -0,0 +1,333 @@
+import { describe, expect, test } from "bun:test";
+import { apply, ready, type Request } from "../lib/engine";
+import { contractJsonSchema, localSemanticProjection } from "../lib/contract";
+import {
+  buildPlanRevision,
+  deriveExecutionPhase,
+  diffPlan,
+  validateRevisionInput,
+} from "../lib/revisions";
+import { validateLedger } from "../lib/schema";
+
+const base = "a".repeat(40);
+const at = "2026-01-01T00:00:00.000Z";
+const main = { role: "main", thread_id: "main-thread" } as const;
+
+function fixture() {
+  const group = {
+    id: "g",
+    title: "Group",
+    agent_thread_id: "group-thread",
+    state: "active",
+    parent_branch: "parent",
+    parent_pr: null,
+    cut_sha: null,
+    current_sha: base,
+    merge_sha: null,
+    requirements_path: null,
+  };
+  const tasks = ["a", "b", "c"].map((id) => ({
+    id,
+    title: id,
+    kind: "contribution",
+    group_id: "g",
+    thread_id: null,
+    state: "planned",
+    atoms: [],
+    owned_surfaces: [`src/${id}`],
+    base_sha: base,
+    pr: null,
+    requirements_path: null,
+    started_at: null,
+    finished_at: null,
+    blocker: null,
+    assignment_history: [],
+  }));
+  const nodes = ["a", "b", "c"].map((id) => ({
+    id: `node-${id}`,
+    kind: "task",
+    ref_id: id,
+    group_id: "g",
+    label: id,
+    estimate_minutes: null,
+    estimate_basis: null,
+    estimate_confidence: null,
+  }));
+  const plan = {
+    id: "plan",
+    supersedes_id: null,
+    approval_id: null,
+    created_at: at,
+    start_at: null,
+    atoms: [],
+    atomic_edges: [],
+    nodes,
+    edges: [{ id: "a-c", from_node_id: "node-a", to_node_id: "node-c", requires: "integrated" }],
+    cut_rules: [],
+    actions: [],
+  };
+  return validateLedger({
+    schema_version: 1,
+    orchestration_id: "run",
+    revision: 0,
+    repository: { provider: "github", host: "github.com", owner: "example", name: "repo", target_branch: "main" },
+    control: { owner_thread_id: "main-thread", ownership: "bound", approval_id: null },
+    config: { execution_profile: { model: "gpt-6.1-sol", thinking: "medium" }, max_running_tasks: 3, display_timezone: "Asia/Shanghai" },
+    plans: [plan],
+    active_plan_id: "plan",
+    groups: [group],
+    tasks,
+    follow_prs: [],
+    facts: [],
+    operations: [],
+    events: [],
+    requests: [],
+    notifications: [],
+    resources: [],
+    updated_at: at,
+  });
+}
+
+function request(ledger: ReturnType<typeof fixture>, requestId: string, payload: Record<string, unknown>, actor: Request["actor"] = main): Request {
+  if (payload.outcome === "succeeded" && (payload.native_evidence as any)?.source === "create_thread") {
+    const operation = ledger.operations.find((item) => item.id === payload.operation_id)!;
+    const nativeId = `native-${operation.id}`;
+    if (!operation.request.native_request_id) apply(ledger, "dispatch-bind-request", { run_id: "run", actor: main, request_id: `bind-${operation.id}`, expected_revision: ledger.revision, payload: { operation_id: operation.id, native_request_id: nativeId } });
+    payload.native_evidence = { source: "multi-task-flow-cli", native_tool_name: "thread/start", operation_id: operation.id, native_request_id: nativeId, ...(operation.request.execution_profile as object), evidence_ref: "fixture://app-server", created_at: at };
+  }
+  return { run_id: ledger.orchestration_id, actor, request_id: requestId, expected_revision: ledger.revision, payload };
+}
+
+function approve(ledger: ReturnType<typeof fixture>, planId = ledger.active_plan_id, requestId = `approve-${planId}`): void {
+  apply(ledger, "plan-approve", request(ledger, requestId, {
+    plan_id: planId,
+    approval_id: `approval-${planId}`,
+    authorized_actions: ["dispatch"],
+    authorized_action_ids: [],
+  }));
+}
+
+function proposedPlan(ledger: ReturnType<typeof fixture>, id: string) {
+  const proposed = structuredClone(ledger.plans.find((item) => item.id === ledger.execution_plan_id)!);
+  proposed.id = id;
+  proposed.supersedes_id = ledger.execution_plan_id;
+  proposed.approval_id = null;
+  proposed.lifecycle = "proposed";
+  proposed.revision = null;
+  return proposed;
+}
+
+function startTask(ledger: ReturnType<typeof fixture>, taskId = "a"): void {
+  apply(ledger, "plan-approve", request(ledger, "initial-approval", {
+    plan_id: "plan",
+    approval_id: "approval-plan",
+    authorized_actions: ["dispatch"],
+    authorized_action_ids: [],
+  }));
+  apply(ledger, "dispatch-claim", request(ledger, "dispatch-a", { task_id: taskId, operation_id: "dispatch-a" }));
+  apply(ledger, "dispatch-resolve", request(ledger, "bind-a", {
+    operation_id: "dispatch-a",
+    outcome: "succeeded",
+    thread_id: `task-${taskId}`,
+    native_evidence: { source: "create_thread" },
+  }));
+  apply(ledger, "task-update", request(ledger, "start-a", { task_id: taskId, state: "running", occurred_at: at }, { role: "task", thread_id: `task-${taskId}` }));
+}
+
+const dependencyReason = {
+  category: "dependency_correction",
+  summary: "Remove a dependency invalidated by the implementation boundary.",
+  evidence_refs: ["evidence://loomhelm/v3/dependency-review"],
+  impact: "The successor must be recalculated under the replacement graph.",
+};
+
+describe("phase-aware plan revisions", () => {
+  test("enters implementation only after a real task_started event", () => {
+    const ledger = fixture();
+    expect(deriveExecutionPhase(ledger)).toBe("planning");
+    ledger.tasks[0]!.state = "starting";
+    expect(deriveExecutionPhase(ledger)).toBe("planning");
+    ledger.events.push({ id: "started", type: "task_started", subject_id: "a", actor_id: "task-a", occurred_at: at, recorded_at: at, data: { task_id: "a" } });
+    expect(deriveExecutionPhase(ledger)).toBe("implementation");
+  });
+
+  test("classifies a Loomhelm v2 to v3 dependency deletion as planning_revision", () => {
+    const ledger = fixture();
+    const previous = structuredClone(ledger.plans[0]!);
+    previous.nodes = ["session-resume", "query-layer", "server-read-path", "ui-regression", "docs"].map((id) => ({ id, kind: "task", ref_id: null, group_id: null, label: id, estimate_minutes: null, estimate_basis: null, estimate_confidence: null }));
+    const dependencyPairs: [string, string][] = [
+      ["session-resume", "query-layer"],
+      ["server-read-path", "query-layer"],
+      ["query-layer", "ui-regression"],
+      ["ui-regression", "docs"],
+    ];
+    previous.edges = dependencyPairs.map(([from, to]) => ({ id: `${from}-${to}`, from_node_id: from, to_node_id: to, requires: "completed" as const }));
+    const proposed = structuredClone(previous);
+    proposed.edges = [];
+    const revision = buildPlanRevision(ledger, previous, proposed, ledger.tasks, ledger.groups);
+    expect(revision.change_class).toBe("planning_revision");
+    expect(revision.reason).toBeNull();
+    expect(revision.change_set.removed.map((entry) => entry.path)).toEqual([
+      "plan.edges[query-layer-ui-regression]",
+      "plan.edges[server-read-path-query-layer]",
+      "plan.edges[session-resume-query-layer]",
+      "plan.edges[ui-regression-docs]",
+    ]);
+  });
+
+  test("planning revisions require a diff and a fresh approval", () => {
+    const ledger = fixture();
+    const proposed = proposedPlan(ledger, "plan-v2");
+    proposed.nodes[0]!.label = "Renamed during planning";
+    const result = apply(ledger, "plan-propose", request(ledger, "propose-planning", {
+      plan: proposed,
+      groups: structuredClone(ledger.groups),
+      tasks: structuredClone(ledger.tasks),
+    })) as any;
+    expect(result.result).toMatchObject({ plan_id: "plan-v2", change_class: "planning_revision", approval_required: true });
+    expect(ledger.active_plan_id).toBe("plan-v2");
+    expect(ledger.execution_plan_id).toBe("plan-v2");
+    expect(ledger.control.approval_id).toBeNull();
+    expect(ready(ledger, "a")).toBe(false);
+    approve(ledger, "plan-v2", "approve-planning");
+    expect(ledger.plans.find((item) => item.id === "plan")!.lifecycle).toBe("superseded");
+    expect(ledger.execution_plan_id).toBe("plan-v2");
+  });
+
+  test("implementation low-impact revisions auto-approve with a required reason", () => {
+    const ledger = fixture();
+    startTask(ledger);
+    const proposed = proposedPlan(ledger, "plan-low");
+    proposed.nodes[0]!.label = "Renamed without changing execution boundaries";
+    const result = apply(ledger, "plan-propose", request(ledger, "propose-low", {
+      plan: proposed,
+      groups: structuredClone(ledger.groups),
+      tasks: structuredClone(ledger.tasks),
+      revision: { reason: { ...dependencyReason, category: "owner_direction", evidence_refs: [] } },
+    })) as any;
+    expect(result.result).toMatchObject({ change_class: "implementation_low_impact", approval_required: false });
+    expect(ledger.active_plan_id).toBe("plan-low");
+    expect(ledger.execution_plan_id).toBe("plan-low");
+    expect(ledger.plans.find((item) => item.id === "plan-low")!.lifecycle).toBe("approved");
+    expect(ledger.events.map((event) => event.type)).toContain("plan_revision_approved");
+  });
+
+  test("implementation high-impact revisions keep the old execution pointer and hold successors", () => {
+    const ledger = fixture();
+    startTask(ledger);
+    const proposed = proposedPlan(ledger, "plan-high");
+    proposed.edges = [];
+    const result = apply(ledger, "plan-propose", request(ledger, "propose-high", {
+      plan: proposed,
+      groups: structuredClone(ledger.groups),
+      tasks: structuredClone(ledger.tasks),
+      revision: { reason: dependencyReason },
+    })) as any;
+    expect(result.result).toMatchObject({ change_class: "implementation_high_impact", approval_required: true });
+    expect(ledger.active_plan_id).toBe("plan-high");
+    expect(ledger.execution_plan_id).toBe("plan");
+    expect(ledger.plans.find((item) => item.id === "plan")!.lifecycle).toBe("approved");
+    expect(ready(ledger, "b")).toBe(true);
+    expect(ready(ledger, "c")).toBe(false);
+    approve(ledger, "plan-high", "approve-high");
+    expect(ledger.execution_plan_id).toBe("plan-high");
+    expect(ledger.plans.find((item) => item.id === "plan")!.lifecycle).toBe("superseded");
+    expect(ready(ledger, "c")).toBe(true);
+  });
+
+  test("rejects a high-impact revision without reason before mutating the ledger", () => {
+    const ledger = fixture();
+    startTask(ledger);
+    const proposed = proposedPlan(ledger, "plan-invalid");
+    proposed.edges = [];
+    const before = JSON.stringify(ledger);
+    expect(() => apply(ledger, "plan-propose", request(ledger, "propose-invalid", {
+      plan: proposed,
+      groups: structuredClone(ledger.groups),
+      tasks: structuredClone(ledger.tasks),
+    }))).toThrow("structured reason");
+    expect(JSON.stringify(ledger)).toBe(before);
+  });
+
+  test("abandoning a candidate restores the prior execution plan", () => {
+    const ledger = fixture();
+    startTask(ledger);
+    const proposed = proposedPlan(ledger, "plan-abandoned");
+    proposed.edges = [];
+    apply(ledger, "plan-propose", request(ledger, "propose-abandoned", {
+      plan: proposed,
+      groups: structuredClone(ledger.groups),
+      tasks: structuredClone(ledger.tasks),
+      revision: { reason: dependencyReason },
+    }));
+    apply(ledger, "plan-abandon", request(ledger, "abandon", { plan_id: "plan-abandoned" }));
+    expect(ledger.active_plan_id).toBe("plan");
+    expect(ledger.execution_plan_id).toBe("plan");
+    expect(ledger.plans.find((item) => item.id === "plan-abandoned")!.lifecycle).toBe("abandoned");
+    expect(ledger.events.at(-1)?.type).toBe("plan_revision_abandoned");
+  });
+
+  test("requires a revision association when migrating a started task", () => {
+    const ledger = fixture();
+    startTask(ledger);
+    const proposed = proposedPlan(ledger, "plan-migration");
+    proposed.nodes = proposed.nodes.filter((node) => node.ref_id !== "a");
+    proposed.nodes.push({ ...structuredClone(proposed.nodes[0]!), id: "node-a-replacement", ref_id: "a-replacement", label: "a replacement" });
+    proposed.edges = [];
+    const replacement = { ...structuredClone(ledger.tasks[0]!), id: "a-replacement", title: "a replacement", thread_id: null, state: "planned", owned_surfaces: ["src/a-replacement"], started_at: null, finished_at: null, blocker: null, assignment_history: [], execution_owner: "task_agent", conversation_policy: "task_agent", delivery_policy: "child_pr" };
+    const tasks = [...structuredClone(ledger.tasks), replacement];
+    apply(ledger, "plan-propose", request(ledger, "propose-migration", {
+      plan: proposed,
+      groups: structuredClone(ledger.groups),
+      tasks,
+      revision: { reason: dependencyReason },
+    }));
+    apply(ledger, "task-migrate", request(ledger, "migrate-a", {
+      old_task_id: "a",
+      new_task_id: "a-replacement",
+      reason: dependencyReason,
+      inherited_outputs: ["validated source facts"],
+      uninherited_outputs: ["old thread binding"],
+    }));
+    expect(ledger.tasks.find((task) => task.id === "a")!.disposition).toBe("superseded");
+    expect(ledger.tasks.find((task) => task.id === "a")!.superseded_by_task_id).toBe("a-replacement");
+    expect(ledger.events.at(-1)?.type).toBe("task_migration_recorded");
+    expect((ledger.events.at(-1)?.data.plan_revision as Record<string, unknown>).change_class).toBe("implementation_high_impact");
+    validateLedger(ledger);
+  });
+
+  test("exposes one contract schema and a local semantic projection", () => {
+    const schema = contractJsonSchema() as { properties?: Record<string, unknown>; [key: string]: unknown };
+    expect(schema.properties).toHaveProperty("execution_plan_id");
+    expect(schema.properties).toHaveProperty("contract_version");
+    expect(schema["x-contract-version"]).toBe(3);
+    expect(schema["x-field-metadata"]).toHaveProperty("plan_revision");
+    const projection = localSemanticProjection(fixture(), "plan-propose");
+    expect(projection).toMatchObject({ contract_version: 1, operation: "plan-propose", phase: { value: "planning" }, plans: { approval_pending: false } });
+    expect((projection.examples as { negative: string[] }).negative).toContain("active_plan_id alone is not execution completion.");
+  });
+
+  test("rejects malformed empty revisions and reports the four replayed dependency deletions", () => {
+    const ledger = fixture();
+    const previous = structuredClone(ledger.plans[0]!);
+    const empty = structuredClone(previous);
+    expect(() => validateRevisionInput(buildPlanRevision(ledger, previous, empty, ledger.tasks, ledger.groups))).toThrow();
+    expect(diffPlan(previous, previous, ledger.tasks, ledger.tasks, ledger.groups, ledger.groups)).toEqual({ added: [], removed: [], modified: [] });
+  });
+});
+
+test("group atom revisions are audited, require approval and restore on abandon", () => {
+  const ledger = fixture();
+  const atom = { id: "group-prepare", title: "Prepare", purpose: "Prepare", output: "Ready", lifecycle_stage: null };
+  ledger.plans[0]!.group_atoms = [{ ...atom, group_id: "g" }];
+  ledger.groups[0]!.atoms = [{ ...atom, status: "planned" }];
+  const proposed = proposedPlan(ledger, "group-revision");
+  proposed.group_atoms[0]!.title = "Prepare revised";
+  const groups = structuredClone(ledger.groups);
+  groups[0]!.atoms[0]!.title = "Prepare revised";
+  apply(ledger, "plan-propose", request(ledger, "propose-atoms", { plan: proposed, groups, tasks: structuredClone(ledger.tasks) }));
+  expect(ledger.plans.at(-1)!.revision!.change_set.modified.some((change) => change.path.includes("group_atoms"))).toBe(true);
+  expect(() => apply(ledger, "group-atom-update", request(ledger, "unapproved-atom", { group_id: "g", atom_id: atom.id, state: "running" }))).toThrow("not approved");
+  apply(ledger, "plan-abandon", request(ledger, "abandon-atoms", { plan_id: proposed.id }));
+  expect(validateLedger(ledger).groups[0]!.atoms[0]!.title).toBe("Prepare");
+});

package/toolkit/skills/multi-task-flow/tests/schema-validation.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import { createDemoLedger } from "../examples/orchestration-viewer/ledger";
+import { plannedAction, validateLedger } from "../lib/schema";
+
+describe("planned action schema", () => {
+  test("accepts a structured task target", () => {
+    const action = plannedAction.parse({
+      id: "publish-task-branch",
+      kind: "publish_branch",
+      task_id: "task-a",
+      group_id: null,
+      target: { type: "task", id: "task-a" },
+    });
+    expect(action.target).toEqual({ type: "task", id: "task-a" });
+    expect(action.target_identity).toBeUndefined();
+  });
+
+  test("rejects unknown action fields", () => {
+    expect(() =>
+      plannedAction.parse({
+        id: "publish-task-branch",
+        kind: "publish_branch",
+        task_id: "task-a",
+        group_id: null,
+        target: { type: "task", id: "task-a" },
+        provider_receipt: {},
+      }),
+    ).toThrow();
+  });
+
+  test("rejects an operation that points at no receipt fact", () => {
+    const ledger = createDemoLedger();
+    ledger.operations.push({
+      id: "operation-orphan",
+      kind: "dispatch",
+      actor_id: "sample-agent",
+      target_id: "other-task",
+      status: "claimed",
+      request: {},
+      expected_sha: null,
+      receipt_fact_id: "missing-fact",
+      created_at: ledger.updated_at,
+      updated_at: ledger.updated_at,
+    });
+    expect(() => validateLedger(ledger)).toThrow("Operation receipt_fact_id must reference");
+  });
+
+  test("rejects a fact whose subject is absent", () => {
+    const ledger = createDemoLedger();
+    ledger.facts.push({
+      id: "fact-orphan",
+      kind: "task_quality",
+      subject_id: "missing-task",
+      status: "passed",
+      source: "test",
+      observed_at: ledger.updated_at,
+      sha: null,
+      evidence_ref: "test",
+      quality: null,
+      receipt: null,
+    });
+    expect(() => validateLedger(ledger)).toThrow("Fact subject must reference");
+  });
+});