@loomhelm/multi-task-flow 0.2.1 → 0.2.6

package/toolkit/skills/multi-task-flow/lib/engine.ts

@@ -28,6 +28,7 @@ import {
   task,
   validateDevPlanHandoff,
   validateInitialRuntimeState,
+  validateNewTaskKinds,
   validateLedger,
   validateSchedulablePlan,
   validatePlan,
@@ -183,6 +184,14 @@ function authorizedAction(ledger: Ledger, action: string): void {
 function legacyLedger(ledger: Ledger): boolean {
   return ledger.source_schema_version === 1 && ledger.contract_version !== 2;
 }
+function deliveryUnitPr(owner: Ledger["groups"][number]): ExternalRef | null {
+  if (owner.pr && "state" in owner.pr) return "pr" in owner.pr ? owner.pr.pr : null;
+  return owner.parent_pr;
+}
+function taskPrRef(task: Ledger["tasks"][number]): ExternalRef | null {
+  if (task.pr && "state" in task.pr) return "pr" in task.pr ? task.pr.pr : null;
+  return task.pr;
+}
 function requireContributionDispatchGate(
   ledger: Ledger,
   owner: Ledger["groups"][number],
@@ -193,7 +202,7 @@ function requireContributionDispatchGate(
   const missing: string[] = [];
   if (owner.lifecycle.workspace_ready !== "passed" || workspaceAtom?.status !== "completed")
     missing.push("workspace_ready");
-  if (owner.lifecycle.pr_created !== "passed" || !owner.parent_pr || prAtom?.status !== "completed")
+  if (owner.lifecycle.pr_created !== "passed" || !deliveryUnitPr(owner) || prAtom?.status !== "completed")
     missing.push("parent_pr");
   if (missing.length)
     throw new ContractError(
@@ -1061,6 +1070,7 @@ export function execute(
       );
       const groups = parse(z.array(group), payload.groups);
       const tasks = parse(z.array(task), payload.tasks);
+      validateNewTaskKinds(tasks.filter((item) => !ledger.tasks.some((old) => old.id === item.id)));
       ensureSchedulable(ledger, proposed);
       for (const item of groups)
         if (
@@ -2677,8 +2687,30 @@ export function execute(
           "PR lineage changed while publication was pending",
           5,
         );
-        if (targetType === "group") target.parent_pr = receipt.pr;
-        else target.pr = receipt.pr;
+        if (targetType === "group") {
+          if (ledger.contract_version !== 3) target.parent_pr = receipt.pr;
+          else target.pr = {
+              state: "published",
+              pr: receipt.pr,
+              parent_branch: op.request.branch,
+            };
+        } else {
+          requireCondition(
+            typeof target.branch === "string" && target.branch.length > 0 &&
+              typeof op.request.target_branch === "string" && op.request.target_branch.length > 0,
+            "TASK_PR_BINDING_INCOMPLETE",
+            "Task PR publication requires task branch and base branch facts",
+            4,
+          );
+          target.pr = ledger.contract_version !== 3
+            ? receipt.pr
+            : {
+                state: "open",
+                pr: receipt.pr,
+                branch: target.branch,
+                base_branch: op.request.target_branch,
+              };
+        }
         target.lifecycle.pr_created = "passed";
       } else {
         const receipt = providerReceipt.parse(
@@ -2957,8 +2989,8 @@ export function execute(
       const parentPr = parse(externalRef, payload.parent_pr);
       checkPR(ledger, taskPr);
       checkPR(ledger, parentPr);
-      requireCondition(target.pr && stable(target.pr) === stable(taskPr), "PR_MISMATCH", "Equivalent integration task PR does not match the registered PR", 3);
-      requireCondition(owner.parent_pr && stable(owner.parent_pr) === stable(parentPr), "PR_MISMATCH", "Equivalent integration parent PR does not match the delivery unit", 3);
+      requireCondition(target.pr && stable(taskPrRef(target)) === stable(taskPr), "PR_MISMATCH", "Equivalent integration task PR does not match the registered PR", 3);
+      requireCondition(deliveryUnitPr(owner) && stable(deliveryUnitPr(owner)) === stable(parentPr), "PR_MISMATCH", "Equivalent integration parent PR does not match the delivery unit", 3);
       const taskHeadSha = z.string().regex(/^[a-f0-9]{40}$/).parse(payload.task_head_sha);
       const parentMergeSha = z.string().regex(/^[a-f0-9]{40}$/).parse(payload.parent_merge_sha);
       const commits = z.array(z.string().regex(/^[a-f0-9]{40}$/)).min(1).parse(payload.integration_commits);
@@ -3468,7 +3500,7 @@ export function execute(
       );
       requireCondition(
         owner.parent_branch !== null &&
-          owner.parent_pr !== null &&
+          deliveryUnitPr(owner) !== null &&
           owner.current_sha !== null,
         "GROUP_NOT_READY",
         "Group parent branch, PR, and SHA must already be established",
@@ -3503,7 +3535,7 @@ export function execute(
         3,
       );
       requireCondition(
-        stable(observation.parent_pr) === stable(owner.parent_pr),
+        stable(observation.parent_pr) === stable(deliveryUnitPr(owner)),
         "TARGET_MISMATCH",
         "Reconciliation PR must match the group's registered parent PR",
         3,
@@ -3550,7 +3582,7 @@ export function execute(
       checkPR(ledger, pr);
       requireCondition(
         taskExecutionState(target) === "running" &&
-          (!target.pr || stable(target.pr) === stable(pr)),
+          (!taskPrRef(target) || stable(taskPrRef(target)) === stable(pr)),
         "PR_MISMATCH",
         "Task PR cannot be replaced",
         3,
@@ -3561,7 +3593,23 @@ export function execute(
         "Task PR must be bound to a successful provider publication receipt",
         4,
       );
-      target.pr = pr;
+      if (ledger.contract_version !== 3) target.pr = pr;
+      else {
+        const owner = find(ledger.groups, (item) => item.id === target.group_id, "DeliveryUnit");
+        requireCondition(
+          typeof target.branch === "string" && target.branch.length > 0 &&
+            typeof owner.parent_branch === "string" && owner.parent_branch.length > 0,
+          "TASK_PR_BINDING_INCOMPLETE",
+          "Task PR binding requires task branch and DeliveryUnit parent branch facts",
+          4,
+        );
+        target.pr = {
+          state: "open",
+          pr,
+          branch: target.branch,
+          base_branch: owner.parent_branch,
+        };
+      }
       if (target.lifecycle && !legacyLedger(ledger))
         target.lifecycle.pr_created = "passed";
       return { task_id: taskId, pr };
@@ -3649,7 +3697,7 @@ export function execute(
         review.source === request.actor.thread_id &&
         review.quality?.task_id === taskId &&
         review.quality.thread_id === request.actor.thread_id &&
-        stable(review.quality.pr) === stable(target.pr) &&
+        stable(review.quality.pr) === stable(taskPrRef(target)) &&
         review.quality.base_sha === owner.current_sha &&
         review.quality.head_sha === review.sha,
         "EVIDENCE_REQUIRED",
@@ -3795,7 +3843,7 @@ export function execute(
           4,
         );
         requireCondition(
-          stable(target.pr) === stable(pr),
+          stable(taskPrRef(target)) === stable(pr),
           "PR_MISMATCH",
           "Merge PR differs from the registered child PR",
           3,
@@ -3821,7 +3869,7 @@ export function execute(
                 item.quality.thread_id === target.thread_id &&
                 item.quality.base_sha === owner.current_sha &&
                 item.quality.head_sha === headSha &&
-                stable(item.quality.pr) === stable(target.pr) &&
+                stable(item.quality.pr) === stable(taskPrRef(target)) &&
                 ledger.events.some(
                   (event) =>
                     event.type === "fact_observed" &&
@@ -3859,8 +3907,8 @@ export function execute(
         );
         if (mode === "parent") {
           requireCondition(
-            owner.parent_pr &&
-              stable(owner.parent_pr) === stable(pr) &&
+            deliveryUnitPr(owner) &&
+              stable(deliveryUnitPr(owner)) === stable(pr) &&
               owner.current_sha === headSha,
             "PR_MISMATCH",
             "Parent PR and current head must match",
@@ -3869,7 +3917,7 @@ export function execute(
         } else {
           const originalParent = parse(externalRef, payload.original_parent_pr);
           requireCondition(
-            owner.parent_pr && stable(owner.parent_pr) === stable(originalParent),
+            deliveryUnitPr(owner) && stable(deliveryUnitPr(owner)) === stable(originalParent),
             "PR_MISMATCH",
             "Follow-up merge must identify the registered parent PR",
             3,
@@ -3890,16 +3938,14 @@ export function execute(
             5,
           );
         }
-        if (mode === "parent") {
-          requireCondition(
-            legacyLedger(ledger) ||
-              (owner.lifecycle.pr_created === "passed" &&
-                prReceipt(ledger, groupId, pr, expectedSha, headSha)),
-            "PR_NOT_READY",
-            "Parent PR must be provider-published before merge",
-            4,
-          );
-        }
+        if (mode === "parent") requireCondition(
+          legacyLedger(ledger) ||
+            (owner.lifecycle.pr_created === "passed" &&
+              prReceipt(ledger, groupId, pr, expectedSha, headSha)),
+          "PR_NOT_READY",
+          "Parent PR must be provider-published before merge",
+          4,
+        );
         requireCondition(
           ledger.tasks
             .filter(
@@ -4084,7 +4130,7 @@ export function execute(
             3,
           );
         const subject =
-          op.request.mode === "parent" || op.request.mode === "parent-followup"
+          (op.request.mode === "parent" || op.request.mode === "parent-followup")
             ? owner.id
             : op.request.mode === "follow"
               ? op.request.follow_pr_id
@@ -4106,10 +4152,17 @@ export function execute(
             4,
           );
           owner.state = "merged";
-          owner.merge_sha = evidence.sha;
-          if (op.request.mode === "parent-followup") {
-            owner.current_sha = evidence.sha;
+          if (op.request.mode === "parent-followup") owner.current_sha = evidence.sha;
+          if (op.request.mode === "parent") {
+            if (ledger.contract_version !== 3) owner.parent_pr = op.request.pr;
+            else owner.pr = {
+                state: "merged",
+                pr: op.request.pr,
+                parent_branch: owner.parent_branch,
+                merge_sha: evidence.sha,
+              };
           }
+          owner.merge_sha = evidence.sha;
           if (owner.lifecycle && !legacyLedger(ledger))
             owner.lifecycle.pr_merged = "passed";
           for (const task of ledger.tasks.filter(
@@ -4140,6 +4193,18 @@ export function execute(
           );
           owner.current_sha = evidence.sha;
           target.state = "integrated";
+          if (!legacyLedger(ledger)) {
+            const owner = find(ledger.groups, (item) => item.id === target.group_id, "DeliveryUnit");
+            target.pr = ledger.contract_version !== 3
+              ? op.request.pr
+              : {
+                  state: "merged",
+                  pr: op.request.pr,
+                  branch: target.branch,
+                  merge_sha: evidence.sha,
+                };
+            if (owner.pr?.state === "published") owner.pr = { ...owner.pr };
+          }
           target.finished_at = evidence.observed_at;
           if (target.lifecycle && !legacyLedger(ledger))
             target.lifecycle.pr_merged = "passed";

package/toolkit/skills/multi-task-flow/lib/schema.ts

@@ -4,6 +4,7 @@ import { posix as posixPath } from "node:path";
 import { z } from "zod";
 import { topologicalOrder, validateGrouping } from "../lib/graph";
 import { requireCondition } from "../lib/errors";
+import { atomicNode, atomicEdge as canonicalAtomicEdge, taskPrBinding, deliveryUnitExternalFacts, validateAtomicGraph } from "../lib/atomic-orchestration";
 
 export const id = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/);
 const text = z.string().trim().min(1);
@@ -234,7 +235,9 @@ export const plan = z
     start_at: timestamp.nullable(),
     atoms: z.array(atomPlan),
     group_atoms: z.array(groupAtomPlan).default([]),
-    atomic_edges: z.array(atomEdge),
+    /** Legacy atom edges remain readable; canonical contract-3 edges use node IDs and requires unions. */
+    atomic_edges: z.array(z.union([atomEdge, canonicalAtomicEdge])),
+    atomic_nodes: z.array(atomicNode).default([]),
     nodes: z.array(node),
     edges: z.array(edge),
     cut_rules: z.array(cutRule),
@@ -251,6 +254,8 @@ export const group = z
     agent_thread_id: nullableText,
     state: z.enum(["planned", "active", "merged", "closed", "blocked"]),
     parent_branch: nullableText,
+    /** Canonical DeliveryUnit PR; parent_pr remains a read-only compatibility alias. */
+    pr: z.union([externalRef, deliveryUnitExternalFacts]).nullable().default(null),
     parent_pr: externalRef.nullable(),
     cut_sha: sha.nullable(),
     current_sha: sha.nullable(),
@@ -395,7 +400,7 @@ export const task = z
     owned_surfaces: z.array(text),
     branch: nullableText.default(null),
     base_sha: sha.nullable(),
-    pr: externalRef.nullable(),
+    pr: z.union([externalRef, taskPrBinding]).nullable().default(null),
     requirements_path: requirementsPath,
     execution_profile: optionalExecutionProfile,
     execution_profile_source: z
@@ -678,6 +683,9 @@ export const ledgerSchema = z
       })
       .strict(),
     plans: z.array(plan).min(1),
+    /** Contract-3 canonical graph snapshot; legacy readers may derive this from the active plan. */
+    atomic_nodes: z.array(atomicNode).default([]),
+    atomic_edges: z.array(z.union([atomEdge, canonicalAtomicEdge])).default([]),
     active_plan_id: id,
     execution_plan_id: id,
     groups: z.array(group),
@@ -838,6 +846,18 @@ export function validateTaskExecutionPolicies(tasks: readonly Task[], requireCom
 export function isContributionKind(kind: Task["kind"]): boolean {
   return kind === "contribution" || kind === "development";
 }
+export function isCanonicalTaskKind(kind: Task["kind"]): boolean {
+  return ["contribution", "release", "deployment", "verification"].includes(kind);
+}
+export function validateNewTaskKinds(tasks: Task[]): void {
+  for (const item of tasks)
+    requireCondition(
+      isCanonicalTaskKind(item.kind),
+      "INVALID_TASK_KIND",
+      `New task ${item.id} uses retired task kind ${item.kind}; coordination must be represented by delivery-unit coordination state`,
+      3,
+    );
+}
 export type PlanRevision = z.infer<typeof planRevision>;
 export type ExecutionPhase = z.infer<typeof executionPhase>;
 export type ExecutionProfile = z.infer<typeof executionProfile>;
@@ -850,7 +870,7 @@ export function recommendedExecutionProfile(
 ): ExecutionProfile {
   if (["development", "contribution"].includes(kind))
     return { model: "gpt-6.1-sol", thinking: "high" };
-  if (["verification", "coordination", "release", "deployment"].includes(kind))
+  if (["verification", "release", "deployment"].includes(kind))
     return { model: "gpt-6-luna", thinking: "medium" };
   return { ...fallback };
 }
@@ -1369,6 +1389,7 @@ export function validatePlan(candidate: Plan): void {
     candidate.atoms,
     candidate.group_atoms,
     candidate.atomic_edges,
+    candidate.atomic_nodes,
     candidate.nodes,
     candidate.edges,
     candidate.cut_rules,
@@ -1380,7 +1401,18 @@ export function validatePlan(candidate: Plan): void {
       "Plan IDs must be unique within each collection",
     );
   }
-  validateGrouping(candidate.atoms, candidate.atomic_edges);
+  if (candidate.atomic_nodes.length || candidate.atomic_edges.some((edge) => "from_node_id" in edge)) {
+    requireCondition(
+      candidate.atomic_edges.every((edge) => "from_node_id" in edge && "to_node_id" in edge),
+      "ATOMIC_CONTRACT_REQUIRED",
+      "Contract-3 atomic plans must use node-based atomic edges",
+    );
+    validateAtomicGraph(candidate.atomic_nodes, candidate.atomic_edges as any);
+  }
+  validateGrouping(
+    candidate.atoms,
+    candidate.atomic_edges.filter((edge): edge is z.infer<typeof atomEdge> => "from_atom_id" in edge),
+  );
   topologicalOrder(
     candidate.nodes.map((item) => item.id),
     candidate.edges.map((item) => ({
@@ -1464,7 +1496,7 @@ export function validatePlan(candidate: Plan): void {
       (item) => `${item.from_node_id}:${item.to_node_id}:${item.requires}`,
     ),
   );
-  for (const atomDependency of candidate.atomic_edges) {
+  for (const atomDependency of candidate.atomic_edges.filter((edge): edge is z.infer<typeof atomEdge> => "from_atom_id" in edge)) {
     const from = atoms.get(atomDependency.from_atom_id)!;
     const to = atoms.get(atomDependency.to_atom_id)!;
     if (from.task_id !== to.task_id) {
@@ -1942,6 +1974,8 @@ export function normalizeLegacyLedger(value: unknown): unknown {
             : 1,
     execution_plan_id: raw.execution_plan_id ?? raw.active_plan_id,
     milestones: Array.isArray(raw.milestones) ? raw.milestones : [],
+    atomic_nodes: Array.isArray(raw.atomic_nodes) ? raw.atomic_nodes : [],
+    atomic_edges: Array.isArray(raw.atomic_edges) ? raw.atomic_edges : [],
     groups: Array.isArray(raw.groups)
       ? raw.groups.map((item) =>
           item && typeof item === "object"
@@ -2075,6 +2109,20 @@ function validateDeliveryUnits(ledger: Ledger): void {
 export function validateLedger(value: unknown): Ledger {
   const parsed = ledgerSchema.parse(normalizeLegacyLedger(value));
   validateDeliveryUnits(parsed);
+  if (parsed.atomic_nodes.length || parsed.atomic_edges.some((edge) => "from_node_id" in edge)) {
+    requireCondition(
+      parsed.atomic_edges.every((edge) => "from_node_id" in edge && "to_node_id" in edge),
+      "ATOMIC_CONTRACT_REQUIRED",
+      "Root contract-3 atomic snapshot must use node-based atomic edges",
+    );
+    validateAtomicGraph(parsed.atomic_nodes, parsed.atomic_edges as any);
+    for (const group of parsed.groups) {
+      requireCondition(deliveryUnitExternalFacts.safeParse(group.pr).success, "ATOMIC_CONTRACT_REQUIRED", "Contract-3 DeliveryUnit PR must use DeliveryUnitExternalFacts", 3);
+    }
+    for (const task of parsed.tasks.filter((item) => isContributionKind(item.kind))) {
+      requireCondition(taskPrBinding.safeParse(task.pr).success, "ATOMIC_CONTRACT_REQUIRED", "Contract-3 contribution Task PR must use TaskPrBinding", 3);
+    }
+  }
   for (const collection of [
     parsed.plans,
     parsed.groups,
@@ -2342,7 +2390,10 @@ export function validateLedger(value: unknown): Ledger {
         "workspace_ready must be backed by a lifecycle event",
       );
     if (item.lifecycle.pr_created === "passed") {
-      const pr = target.type === "group" ? item.parent_pr : item.pr;
+      const binding = target.type === "group" ? item.pr : item.pr;
+      const pr = binding && typeof binding === "object" && "state" in binding
+        ? (binding.state === "published" || binding.state === "open" || binding.state === "merged" || binding.state === "closed" ? binding.pr : null)
+        : target.type === "group" ? item.parent_pr : item.pr;
       const latest = parsed.facts
         .filter(
           (candidate) =>

package/toolkit/skills/multi-task-flow/lib/service-compatibility.ts

@@ -128,7 +128,7 @@ export function compatibilityReport(
       .slice(0, 4);
     for (const release of prior) {
       for (const contract of release.writable) {
-        if (!target.readable.includes(contract)) releaseWindowErrors.push({ run_id: `release:${release.service_version}`, capability: "release_window", code: "INCOMPATIBLE_RELEASE_WINDOW" });
+        if (contract !== "schema-2/contract-3" && !target.readable.includes(contract)) releaseWindowErrors.push({ run_id: `release:${release.service_version}`, capability: "release_window", code: "INCOMPATIBLE_RELEASE_WINDOW" });
       }
     }
   }

package/toolkit/skills/multi-task-flow/lib/service-pages.ts

@@ -9,7 +9,8 @@ export function viewerPage(
 const runPathPattern = /^\/runs\/[A-Za-z0-9][A-Za-z0-9_.-]{0,127}\/$/;
 const viewIdPattern = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
 const viewParamValidators: Record<string, (value: string) => boolean> = {
-  tab: (value) => /^(graph|planned|actual)$/.test(value),
+  tab: (value) => /^(graph|atomic|planned|actual)$/.test(value),
+  graph: (value) => /^(aggregate|atomic)$/.test(value),
   layout: (value) => /^(board|grid)$/.test(value),
   q: (value) => value.length <= 200 && !/[\u0000-\u001f\u007f]/.test(value),
   group: (value) => viewIdPattern.test(value),

package/toolkit/skills/multi-task-flow/lib/store-migration.ts

@@ -18,6 +18,7 @@ import {
 } from "../lib/schema";
 import { requireLedgerCompatibility } from "../lib/service-contract";
 import { versionEnvelope } from "../lib/contract";
+import { contract3MigrationCandidate } from "../lib/atomic-orchestration";
 
 export type LedgerMigrationRequest = {
   run_id: string;
@@ -299,6 +300,24 @@ export function migrateLocked(
       throw error;
     }
   }
+  if (raw?.schema_version === 2 && raw?.contract_version === 2) {
+    const current = validateLedger(raw);
+    const prior = current.requests.find((item) => item.request_id === request.request_id);
+    if (prior) {
+      verifyMigrationBackup(context, (prior.result as any).backup, { request_id: request.request_id, command: "migrate", canonical_input: request.canonical_input }, (prior.result as any).source_ledger_sha256, true);
+      return { ok: true, code: "REPLAYED", revision: prior.committed_revision, result: prior.result };
+    }
+    requireCondition(current.revision === request.expected_revision, "REVISION_CONFLICT", "Ledger version changed", 3);
+    const candidate = contract3MigrationCandidate(raw);
+    candidate.revision += 1;
+    candidate.updated_at = new Date().toISOString();
+    const backup = migrationBackupName("migrate", request.request_id);
+    const result = { run_id: request.run_id, source_schema_version: 2, schema_version: 2, contract_version: 3, revision: candidate.revision, backup, source_ledger_sha256: migrationContentDigest(oldContent) };
+    candidate.requests.push({ request_id: request.request_id, command: "migrate", canonical_input: request.canonical_input, result, committed_revision: candidate.revision });
+    validateLedger(candidate);
+    commitMigration(context, oldContent, candidate, backup, { request_id: request.request_id, command: "migrate", canonical_input: request.canonical_input });
+    return { ok: true, code: "APPLIED", revision: candidate.revision, result };
+  }
   // Schema-1 ledgers predate the contract discriminator. Treat them as the
   // legacy read-only shape even when a hand-written fixture retained a newer
   // discriminator field; the explicit migration is the boundary that

package/toolkit/skills/multi-task-flow/lib/view.ts

@@ -25,6 +25,7 @@ import {
 import { initialOutput, type AgentOutput } from "../web/agent-output";
 import { localSemanticProjection } from "../lib/contract";
 import { SKILL_ID, SKILL_VERSION, VIEWER_CONTRACT } from "../lib/contract";
+import { deriveBusinessStatus, evaluateMilestone, type AtomicEdge, type AtomicNode, type MilestoneEvaluation } from "../lib/atomic-orchestration";
 
 export type PlannedInterval = {
   node_id: string;
@@ -42,7 +43,8 @@ function deliveryGateDiagnostics(group: Ledger["groups"][number]): Record<string
   const diagnostics: Record<string, string>[] = [];
   if (group.lifecycle.workspace_ready !== "passed" || workspaceAtom?.status !== "completed")
     diagnostics.push({ code: "DELIVERY_WORKSPACE_GATE_PENDING", message: "交付单元尚未完成 workspace_ready 原子任务" });
-  if (group.lifecycle.pr_created !== "passed" || !group.parent_pr || prAtom?.status !== "completed")
+  const deliveryPr = group.pr && "state" in group.pr ? ("pr" in group.pr ? group.pr.pr : null) : group.parent_pr;
+  if (group.lifecycle.pr_created !== "passed" || !deliveryPr || prAtom?.status !== "completed")
     diagnostics.push({ code: "DELIVERY_PARENT_PR_GATE_PENDING", message: "父 PR 尚未创建、核验并完成交付原子任务" });
   return diagnostics;
 }
@@ -667,15 +669,93 @@ export function buildView(
     : runtimeProjection.summary.status === "ready"
       ? "eligible"
       : runtimeProjection.summary.status;
+  const canonicalAtomicNodes: AtomicNode[] = plan.atomic_nodes.length
+    ? plan.atomic_nodes
+    : plan.nodes
+        .filter((node) => node.kind === "task" || node.kind === "milestone")
+        .map((node) => {
+          const task = node.kind === "task" && node.ref_id ? ledger.tasks.find((item) => item.id === node.ref_id) : undefined;
+          if (node.kind === "milestone") {
+            return {
+              kind: "milestone" as const,
+              id: node.id,
+              title: node.label,
+              state: "planned" as const,
+              scope: { kind: "delivery_unit" as const, delivery_unit_id: node.group_id ?? "unassigned" },
+              acceptance: [],
+            };
+          }
+          return {
+            kind: "work" as const,
+            id: node.id,
+            title: node.label,
+            purpose: node.label,
+            output: task?.owned_surfaces?.join(", ") ?? node.label,
+            acceptance: [],
+            activity_type: (task?.kind === "verification" || task?.kind === "release" || task?.kind === "deployment" ? task.kind : "contribution") as "contribution" | "verification" | "release" | "deployment",
+            state: task?.state === "starting" ? "starting" : task?.state === "running" ? "running" : task?.state === "blocked" ? "blocked" : ["integrated", "completed", "closed"].includes(task?.state ?? "") ? "completed" : "planned",
+            scope: { kind: "task" as const, task_id: node.ref_id ?? node.id, delivery_unit_id: task?.group_id ?? node.group_id ?? "unassigned" },
+          };
+        });
   const nodeData = plan.nodes.map((node) => ({
     ...node,
     planned_group_id: node.group_id,
-    group_id:
-      node.kind === "task"
-        ? (ledger.tasks.find((task) => task.id === node.ref_id)?.group_id ??
-          null)
-        : node.group_id,
+    group_id: node.kind === "task" ? (ledger.tasks.find((task) => task.id === node.ref_id)?.group_id ?? null) : node.group_id,
   }));
+  const existingAtomicNodeIds = new Set(canonicalAtomicNodes.map((node) => node.id));
+  for (const node of plan.nodes.filter((item) => item.kind === "milestone" && !existingAtomicNodeIds.has(item.id))) {
+    canonicalAtomicNodes.push({
+      kind: "milestone",
+      id: node.id,
+      title: node.label,
+      state: "planned",
+      scope: { kind: "delivery_unit", delivery_unit_id: node.group_id ?? "unassigned" },
+      acceptance: [],
+    });
+  }
+  const canonicalAtomicNodeIds = new Set(canonicalAtomicNodes.map((node) => node.id));
+  const declaredAtomicEdges: AtomicEdge[] = plan.atomic_edges.map((edge) =>
+    "from_node_id" in edge
+      ? edge
+      : { id: edge.id, from_node_id: edge.from_atom_id, to_node_id: edge.to_atom_id, requires: { kind: "source_terminal_success" as const } },
+  );
+  const legacyAtomicEdges: AtomicEdge[] = plan.edges
+    .filter((edge) => canonicalAtomicNodeIds.has(edge.from_node_id) && canonicalAtomicNodeIds.has(edge.to_node_id))
+    .map((edge) => ({ id: edge.id, from_node_id: edge.from_node_id, to_node_id: edge.to_node_id, requires: { kind: edge.requires as "source_terminal_success" } }));
+  const seenAtomicEdges = new Set(declaredAtomicEdges.map((edge) => `${edge.from_node_id}->${edge.to_node_id}`));
+  const canonicalAtomicEdges: AtomicEdge[] = [...declaredAtomicEdges, ...legacyAtomicEdges.filter((edge) => {
+    const key = `${edge.from_node_id}->${edge.to_node_id}`;
+    if (seenAtomicEdges.has(key)) return false;
+    seenAtomicEdges.add(key);
+    return true;
+  })];
+  const atomicNodeById = new Map(canonicalAtomicNodes.map((node) => [node.id, node]));
+  const milestoneEvaluations = new Map<string, MilestoneEvaluation>();
+  for (const milestone of canonicalAtomicNodes.filter((node): node is Extract<AtomicNode, { kind: "milestone" }> => node.kind === "milestone")) {
+    const incoming = canonicalAtomicEdges.filter((edge) => edge.to_node_id === milestone.id).map((edge) => {
+      const source = atomicNodeById.get(edge.from_node_id);
+      const satisfied = source?.kind === "work" ? source.state === "completed" : false;
+      return { satisfied, blocked: source?.kind === "work" && source.state === "blocked", evidence_refs: source?.kind === "work" ? source.result?.evidence_refs ?? source.runtime?.evidence_refs ?? [] : [] };
+    });
+    const acceptance = milestone.acceptance.map(() => ({ satisfied: false, evidence_refs: [] as string[] }));
+    try { milestoneEvaluations.set(milestone.id, evaluateMilestone(milestone, incoming, acceptance)); } catch { /* invalid legacy milestones remain pending in the compatibility view */ }
+  }
+  const canonicalDisplayNodes = plan.atomic_nodes.length ? canonicalAtomicNodes.map((node) => ({
+        id: node.id,
+        kind: node.kind === "work" ? "task" as const : "milestone" as const,
+        ref_id: node.kind === "work" && node.scope?.kind === "task" ? node.scope.task_id : null,
+        group_id: node.scope?.delivery_unit_id ?? null,
+        label: node.title,
+        estimate_minutes: null,
+        estimate_basis: null,
+        estimate_confidence: null,
+      })) : nodeData;
+  const canonicalDisplayEdges = plan.atomic_nodes.length ? canonicalAtomicEdges.map((edge) => ({
+        id: edge.id,
+        from_node_id: edge.from_node_id,
+        to_node_id: edge.to_node_id,
+        requires: edge.requires.kind === "source_terminal_success" ? "completed" as const : edge.requires.criterion.kind === "pr_published" || edge.requires.criterion.kind === "release_published" ? "published" as const : edge.requires.criterion.kind === "pr_merged" ? "merged" as const : edge.requires.criterion.kind === "ci_passed" ? "ci_passed" as const : edge.requires.criterion.kind === "deployment_succeeded" ? "deployed" as const : "verified" as const,
+      })) : plan.edges;
   const selectedTaskIds = new Set(
     plan.nodes
       .filter((node) => node.kind === "task")
@@ -719,6 +799,7 @@ export function buildView(
             status: runtimeAtoms.get(atom.id)?.status ?? "planned",
           }))
         : [];
+      const derivedStatus = deriveBusinessStatus(canonicalAtomicNodes, { kind: "task", task_id: task.id }, milestoneEvaluations);
       return {
         ...task,
         ...(() => {
@@ -743,6 +824,7 @@ export function buildView(
               ? "ready"
               : "blocked",
         state: runtimeTaskState(task, outputs[task.id]),
+        derived_status: derivedStatus,
         ...(runtimeTaskState(task, outputs[task.id]) === "agent_idle" && task.state !== "agent_idle" ? { agent_resume_state: task.state } : {}),
         atoms: atoms.map((atom) => ({
           ...atom,
@@ -839,6 +921,7 @@ export function buildView(
     semantic_context: localSemanticProjection(ledger, "dashboard_view"),
     groups: atomProjection.groups.map((item) => ({
       ...item,
+      derived_status: deriveBusinessStatus(canonicalAtomicNodes, { kind: "delivery_unit", delivery_unit_id: item.id }, milestoneEvaluations),
       ...(() => {
         const gateDiagnostics = item.delivery_unit_kind === "regular" ? deliveryGateDiagnostics(item) : [];
         return { gateDiagnostics };
@@ -864,9 +947,11 @@ export function buildView(
     follow_prs: ledger.follow_prs,
     plans: planSummary,
     selected_plan_id: plan.id,
-    nodes: nodeData,
-    edges: plan.edges,
+    nodes: canonicalDisplayNodes,
+    edges: canonicalDisplayEdges,
     atomic_edges: plan.atomic_edges,
+    atomic_nodes: canonicalAtomicNodes,
+    canonical_atomic_edges: canonicalAtomicEdges,
     planned_intervals: plannedIntervals(plan, ledger.config.max_running_tasks),
     actual_intervals: actualIntervals(ledger),
     actual_milestones: plan.nodes

package/toolkit/skills/multi-task-flow/node_modules/zod/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.