@loomhelm/multi-task-flow 0.2.1 → 0.2.7

package/toolkit/skills/multi-task-flow/dist/index.html

@@ -37,15 +37,17 @@
       <section class="overview" aria-label="任务概览">
         <div id="summary" class="summary" aria-live="polite"></div>
       </section>
-      <section class="workspace" aria-label="编排视图">
+      <section id="workspace" class="workspace" aria-label="编排视图">
         <div class="workspace-main">
           <div class="workspace-view">
             <div class="view-header">
             <div class="view-heading"><span class="view-meta">observability</span><span id="view-context" class="view-context">运行视图</span><span id="view-count" class="view-count"></span></div>
             <div class="tabs" role="tablist" aria-label="视图">
-              <button id="tab-graph" type="button" role="tab" aria-selected="true" aria-controls="graph-view" data-tab="graph">依赖图</button>
+              <button id="tab-graph" type="button" role="tab" aria-selected="true" aria-controls="graph-view" data-tab="graph">任务与交付单元依赖</button>
+              <button id="tab-atomic" type="button" role="tab" aria-selected="false" aria-controls="graph-view" data-tab="atomic">原子任务依赖</button>
               <button id="tab-planned" type="button" role="tab" aria-selected="false" aria-controls="planned-view" data-tab="planned">理论安排</button>
               <button id="tab-actual" type="button" role="tab" aria-selected="false" aria-controls="actual-view" data-tab="actual">实际进度</button>
+              <button id="tab-tasks" type="button" role="tab" aria-selected="false" aria-controls="tasks-view" data-tab="tasks">任务</button>
             </div>
             <label class="search input"><i data-lucide="search" aria-hidden="true"></i><span class="sr-only">搜索任务</span><input id="search" type="search" placeholder="搜索任务"></label>
             </div>
@@ -71,11 +73,11 @@
             <div id="plan-state" class="notice plan-state" aria-label="计划与运行状态" hidden></div>
             <div id="plan-warning" class="notice notice-warning" role="status" hidden></div>
             <div id="load-error" class="notice notice-error" role="alert" hidden></div>
-            <div id="graph-view" class="canvas-view" role="tabpanel" aria-labelledby="tab-graph"><div id="graph-projection-warning" class="notice notice-warning" role="status" hidden></div><div id="graph" aria-label="任务依赖图"></div><div id="graph-a11y" class="graph-a11y" role="list" aria-label="依赖图节点列表"></div><div id="graph-empty" class="empty" hidden>暂无任务</div></div>
+            <div id="graph-view" class="canvas-view" role="tabpanel" aria-labelledby="tab-graph"><div id="graph-projection-warning" class="notice notice-warning" role="status" hidden></div><div id="graph" aria-label="任务依赖图"></div><div id="atomic-graph" aria-label="原子任务依赖图" hidden></div><div id="graph-a11y" class="graph-a11y" role="list" aria-label="依赖图节点列表"></div><div id="graph-empty" class="empty" hidden>暂无任务</div></div>
             <div id="planned-view" class="timeline-view" role="tabpanel" aria-labelledby="tab-planned" hidden><div id="planned-timeline"></div><div class="axis-timezone"></div><div id="planned-unknown" class="unknown"></div></div>
             <div id="actual-view" class="timeline-view" role="tabpanel" aria-labelledby="tab-actual" hidden><div id="actual-timeline"></div><div class="axis-timezone"></div><div id="actual-unknown" class="unknown"></div></div>
           </div>
-          <div class="workspace-tasks">
+          <div id="tasks-view" class="workspace-tasks" role="tabpanel" aria-labelledby="tab-tasks" hidden>
             <section id="group-section" class="task-list-section" aria-labelledby="group-heading"><div class="section-heading"><h2 id="group-heading">交付单元</h2></div><div id="group-list" class="task-list" role="list"></div></section>
             <section id="task-section" class="task-list-section" aria-labelledby="task-heading"><div class="section-heading"><h2 id="task-heading">任务</h2><div class="section-heading-actions"><span id="task-count" class="section-count"></span><div id="task-layout-switch" class="layout-switch" role="group" aria-label="对象布局"><button id="task-layout-board" type="button" class="icon-button layout-option" aria-label="看板布局" aria-describedby="task-layout-board-tooltip" aria-pressed="true"><i data-lucide="columns-3"></i><span id="task-layout-board-tooltip" class="layout-tooltip" role="tooltip">看板布局：按交付单元分列展示任务</span></button><button id="task-layout-grid" type="button" class="icon-button layout-option" aria-label="网格布局" aria-describedby="task-layout-grid-tooltip" aria-pressed="false"><i data-lucide="layout-grid"></i><span id="task-layout-grid-tooltip" class="layout-tooltip" role="tooltip">网格布局：平铺展示任务</span></button></div></div></div><div id="task-list" class="task-list" role="list"></div></section>
           </div>

package/toolkit/skills/multi-task-flow/examples/orchestration-viewer/index.ts

@@ -21,6 +21,60 @@ export function createViewerValidationLedger(referenceTime = Date.now()) {
   run.schema_version = 2;
   run.contract_version = 2;
   run.source_schema_version = null;
+  const plan = run.plans[0];
+  const at = run.updated_at;
+  const contributionTasks = run.tasks.filter((task: { kind: string }) => task.kind === "contribution");
+  plan.actions = run.groups.flatMap((group: { id: string }) => [
+    { id: `${group.id}-publish-branch`, kind: "publish_branch", task_id: null, group_id: group.id, target_identity: `branch:${group.id}` },
+    { id: `${group.id}-publish-pr`, kind: "publish_pr", task_id: null, group_id: group.id, target_identity: `pr:${group.id}` },
+  ]).concat(contributionTasks.flatMap((task: { id: string; group_id: string }) => [
+    { id: `${task.id}-publish-branch`, kind: "publish_branch", task_id: task.id, group_id: null, target_identity: `branch:${task.id}` },
+    { id: `${task.id}-publish-pr`, kind: "publish_pr", task_id: task.id, group_id: null, target_identity: `pr:${task.id}` },
+  ]));
+  for (const group of run.groups) {
+    group.lifecycle.workspace_ready = "passed";
+    run.events.push({
+      id: `preview-${group.id}-workspace-ready`,
+      type: "lifecycle_recorded",
+      subject_id: group.id,
+      actor_id: run.control.owner_thread_id,
+      occurred_at: at,
+      recorded_at: at,
+      data: { target_type: "group", stage: "workspace_ready", resource_ids: [`${group.id}-worktree`, `${group.id}-branch`] },
+    });
+    run.resources.push(
+      { id: `${group.id}-worktree`, kind: "worktree", target: group.id, status: "active", evidence_ref: `preview:${group.id}:worktree` },
+      { id: `${group.id}-branch`, kind: "branch", target: group.parent_branch, status: "active", evidence_ref: `preview:${group.id}:branch` },
+    );
+    run.facts.push({
+      id: `preview-${group.id}-branch-published`,
+      kind: "branch_published",
+      subject_id: group.id,
+      status: "passed",
+      source: "sample",
+      observed_at: at,
+      sha: group.current_sha,
+      evidence_ref: `preview:${group.id}:branch-published`,
+      receipt: {
+        provider: run.repository.provider,
+        repository: `${run.repository.owner}/${run.repository.name}`,
+        resource_type: "branch",
+        resource_id: group.parent_branch,
+        branch: group.parent_branch,
+        target_branch: null,
+        base_sha: null,
+        head_sha: group.current_sha,
+        pr: null,
+        state: "exists",
+        evidence_ref: `preview:${group.id}:branch-published`,
+      },
+    });
+    for (const event of run.events) {
+      if (event.data && typeof event.data === "object" && "group_snapshot" in event.data && event.data.group_snapshot?.id === group.id) {
+        event.data.group_snapshot = structuredClone(group);
+      }
+    }
+  }
   return validateLedger(run);
 }
 

package/toolkit/skills/multi-task-flow/examples/orchestration-viewer/requirements/group-core.md

@@ -1,11 +1,11 @@
-# 账本与依赖调度
+# 交付单元与依赖调度（账本与依赖调度）
 
 ## 目标
 
-交付任务模型、持久账本和依赖驱动的调度能力，并在父 PR 合入后完成版本发布与验证。
+交付单元模型、原子账本和依赖驱动的调度能力，并在集成 PR 合入后完成版本发布与验证。
 
 ## 验收
 
-- 子 PR 由交付协调者（Delivery coordinator） 在主 Agent（main Agent） 的委派范围内按当前基线验收，所有纳入切割的贡献任务已合入父分支。
+- 贡献 Task 负责自己的 child PR；交付单元只通过 AtomicEdge、集成 milestone 和外部事实表达集成验收。
 - 切割点 SHA 和任务归属可追溯；未完成的贡献任务转入下一交付单元。
-- 父 PR 合并后的 CI、发布、部署、验证和已知 follow PR 均完成后，交付单元才能收口。
+- 集成 PR 合并后的 CI、发布、部署、验证和已知 follow PR 均由显式 work 原子或 milestone 完成后，交付单元才能收口。

package/toolkit/skills/multi-task-flow/examples/orchestration-viewer/requirements/group-dashboard.md

@@ -2,10 +2,10 @@
 
 ## 目标
 
-基于账本与依赖调度父 PR 合并后的主干基线，完成本机只读服务、编排页面和端到端验证。
+基于原子账本与交付单元集成 PR 合并后的主干基线，完成本机只读服务、编排页面和端到端验证。
 
 ## 验收
 
 - 接入从账本与依赖调度转来的未完成任务，保留原会话及切割前后的归属历史。
 - 图、理论和实际时间线反映账本事实；未知数据不显示为已完成。
-- 子 PR、父 PR、合并后 CI 和交付单元内后续验证按各自的事实完成。
+- 子 PR、交付单元集成 PR、合并后 CI 和交付单元内后续验证按各自的外部事实与 milestone 完成。

package/toolkit/skills/multi-task-flow/examples/orchestration-viewer/requirements/task-acceptance.md

@@ -2,7 +2,7 @@
 
 ## 目标
 
-在编排展示与交互验收父 PR 合并后核对页面、关联文档和发布结果。
+在编排展示与交互验收交付单元集成 PR 合并后核对页面、关联文档和发布结果。
 
 ## 验收
 

package/toolkit/skills/multi-task-flow/examples/orchestration-viewer/requirements/task-deploy.md

@@ -6,5 +6,5 @@
 
 ## 验收
 
-- 部署身份可追溯至账本与依赖调度父 PR 的合并结果。
+- 部署身份可追溯至原子账本中对应 DeliveryUnit 集成 PR 的合并结果。
 - 记录实际部署状态；失败或结果未知不标记为完成。

package/toolkit/skills/multi-task-flow/examples/orchestration-viewer/requirements/task-model.md

@@ -2,9 +2,9 @@
 
 ## 目标
 
-定义原子任务、子任务、交付单元和里程碑的稳定身份与依赖关系。
+定义 AtomicNode、AtomicEdge、Task、DeliveryUnit 和 milestone 的稳定身份与依赖关系。
 
 ## 验收
 
-- 原子任务图和映射后的子任务图均无环。
-- 跨贡献任务的依赖以子 PR 已合入为交接事实。
+- AtomicNode 与 AtomicEdge 是唯一的依赖真相，图必须无环。
+- Task 与 DeliveryUnit 是平级读取投影，不拥有原子副本；跨贡献任务的依赖以显式 edge requirement 和 PR/milestone evidence 表达。

package/toolkit/skills/multi-task-flow/examples/orchestration-viewer/requirements/task-release.md

@@ -2,7 +2,7 @@
 
 ## 目标
 
-账本与依赖调度父 PR 合入主干并通过必要检查后，按已批准的发布范围交付版本。
+DeliveryUnit 集成 PR 合入主干并通过必要检查后，按已批准的 release 原子和发布范围交付版本。
 
 ## 验收
 

package/toolkit/skills/multi-task-flow/examples/orchestration-viewer/requirements/task-scheduler.md

@@ -1,10 +1,11 @@
-# 调度与 PR 合并协调
+# 原子编排与 PR 合并（调度与 PR 合并协调）
 
 ## 目标
 
-依据明确前驱、并发名额和持久操作占用调度任务与 PR 合并。
+依据 AtomicEdge、里程碑条件、并发名额和持久操作占用调度原子 work 与 PR 合并。
 
 ## 验收
 
-- 只有满足前驱事实且有可用名额的任务才能派发。
-- 切割围栏阻止新合入，并等待已有合入结果明确。
+- 只有满足原子入边条件且有可用名额的 work 原子才能执行。
+- 里程碑只有所有入边条件和显式验收条件满足时才达成；等待属于派生状态，不创建等待或 coordination Task。
+- DeliveryUnit 集成 PR、子 PR、CI、发布、部署和线上验证通过外部事实与对应 milestone 表达。

package/toolkit/skills/multi-task-flow/examples/orchestration-viewer/requirements/task-verify.md

@@ -7,4 +7,4 @@
 ## 验收
 
 - 验证结果绑定实际部署身份及其来源 SHA。
-- 结果和证据记入账本与依赖调度的账本，供交付协调者（Delivery coordinator） 在主 Agent（main Agent） 的委派范围内整理收口证据。
+- 结果和证据记入原子账本，由对应 verification 原子或 milestone 消费；交付单元状态由统一评估器整理，不创建协调任务。

package/toolkit/skills/multi-task-flow/lib/atomic-orchestration.ts

@@ -0,0 +1,237 @@
+import { z } from "zod";
+
+const id = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/);
+const text = z.string().trim().min(1);
+const timestamp = z.iso.datetime({ offset: false });
+
+export const atomicExternalRef = z
+  .object({ provider: text, repository: text, id: text, url: z.url().optional() })
+  .strict();
+
+export const atomicTaskScope = z
+  .object({ kind: z.literal("task"), task_id: id, delivery_unit_id: id })
+  .strict();
+export const atomicDeliveryUnitScope = z
+  .object({ kind: z.literal("delivery_unit"), delivery_unit_id: id })
+  .strict();
+export const atomicScope = z.discriminatedUnion("kind", [atomicTaskScope, atomicDeliveryUnitScope]);
+
+export const atomicBlocker = z
+  .object({ code: text, message: text, evidence_refs: z.array(text).default([]) })
+  .strict();
+export const atomicCriterion = z
+  .object({ id, statement: text, evidence_kind: z.enum(["artifact", "provider_receipt", "quality", "online_verification"]) })
+  .strict();
+export const atomicRuntime = z
+  .object({ started_at: timestamp, updated_at: timestamp, evidence_refs: z.array(text).default([]) })
+  .strict();
+export const atomicResult = z
+  .object({ completed_at: timestamp, evidence_refs: z.array(text).min(1) })
+  .strict();
+
+const workDefinition = z
+  .object({ kind: z.literal("work"), id, title: text, purpose: text, output: text, acceptance: z.array(atomicCriterion) })
+  .strict();
+const workLifecycle = <T extends z.ZodTypeAny>(scope: T) =>
+  z.discriminatedUnion("state", [
+    z.object({ state: z.literal("design") }).strict(),
+    z.object({ state: z.literal("planned"), scope }).strict(),
+    z.object({ state: z.literal("starting"), scope, runtime: atomicRuntime }).strict(),
+    z.object({ state: z.literal("running"), scope, runtime: atomicRuntime }).strict(),
+    z.object({ state: z.literal("blocked"), scope, runtime: atomicRuntime, blocker: atomicBlocker }).strict(),
+    z.object({ state: z.literal("completed"), scope, runtime: atomicRuntime, result: atomicResult }).strict(),
+  ]);
+
+export const atomicWorkNode = z.union([
+  z.intersection(workDefinition.extend({ activity_type: z.enum(["contribution", "documentation"]) }), workLifecycle(atomicTaskScope)),
+  z.intersection(workDefinition.extend({ activity_type: z.enum(["verification", "release", "deployment"]) }), workLifecycle(atomicScope)),
+]);
+
+export const milestoneCriterion = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("node_satisfied"), node_id: id }).strict(),
+  z.object({ kind: z.literal("pr_published"), pr_ref: atomicExternalRef }).strict(),
+  z.object({ kind: z.literal("pr_merged"), pr_ref: atomicExternalRef, merge_sha: text }).strict(),
+  z.object({ kind: z.literal("ci_passed"), target_ref: text, head_sha: text, checks: z.array(text).min(1) }).strict(),
+  z.object({ kind: z.literal("release_published"), release_id: text, artifact_digest: text }).strict(),
+  z.object({ kind: z.literal("deployment_succeeded"), environment: text, artifact_digest: text }).strict(),
+  z.object({ kind: z.literal("online_verification_passed"), target: text, verification_id: text }).strict(),
+]);
+
+export const milestoneNode = z.union([
+  z.object({ kind: z.literal("milestone"), id, title: text, state: z.literal("design"), acceptance: z.array(milestoneCriterion) }).strict(),
+  z.object({ kind: z.literal("milestone"), id, title: text, state: z.literal("planned"), scope: atomicScope, acceptance: z.array(milestoneCriterion) }).strict(),
+]);
+
+export const atomicNode = z.union([atomicWorkNode, milestoneNode]);
+export const atomicEdge = z
+  .object({
+    id,
+    from_node_id: id,
+    to_node_id: id,
+    requires: z.union([
+      z.object({ kind: z.literal("source_terminal_success") }).strict(),
+      z.object({ kind: z.literal("source_evidence"), criterion: milestoneCriterion }).strict(),
+    ]),
+  })
+  .strict();
+
+export const taskPrBinding = z.discriminatedUnion("state", [
+  z.object({ state: z.literal("unbound") }).strict(),
+  z.object({ state: z.literal("open"), pr: atomicExternalRef, branch: text, base_branch: text }).strict(),
+  z.object({ state: z.literal("merged"), pr: atomicExternalRef, branch: text, merge_sha: text }).strict(),
+  z.object({ state: z.literal("closed"), pr: atomicExternalRef, branch: text, closed_at: timestamp, closed_reason: z.enum(["abandoned", "superseded", "provider_closed", "replaced"]) }).strict(),
+]);
+
+export const deliveryUnitExternalFacts = z.discriminatedUnion("state", [
+  z.object({ state: z.literal("unpublished") }).strict(),
+  z.object({ state: z.literal("published"), pr: atomicExternalRef, parent_branch: text }).strict(),
+  z.object({ state: z.literal("merged"), pr: atomicExternalRef, parent_branch: text, merge_sha: text }).strict(),
+  z.object({ state: z.literal("closed"), pr: atomicExternalRef, parent_branch: text, closed_at: timestamp, closed_reason: z.enum(["abandoned", "superseded", "provider_closed", "replaced"]) }).strict(),
+]);
+
+export type AtomicNode = z.infer<typeof atomicNode>;
+export type AtomicEdge = z.infer<typeof atomicEdge>;
+export type TaskPrBinding = z.infer<typeof taskPrBinding>;
+export type DeliveryUnitExternalFacts = z.infer<typeof deliveryUnitExternalFacts>;
+
+export type DerivedBusinessStatus = "planned" | "ready" | "running" | "blocked" | "completed";
+
+export function deriveBusinessStatus(
+  nodes: readonly AtomicNode[],
+  scope: { kind: "task"; task_id: string } | { kind: "delivery_unit"; delivery_unit_id: string },
+  milestoneEvaluations: ReadonlyMap<string, MilestoneEvaluation> = new Map(),
+): DerivedBusinessStatus {
+  const scoped = nodes.filter((node) => {
+    if (node.kind !== "work" || !node.scope) return false;
+    return scope.kind === "task"
+      ? node.scope.kind === "task" && node.scope.task_id === scope.task_id
+      : node.scope.delivery_unit_id === scope.delivery_unit_id;
+  });
+  const scopedMilestones = nodes.filter((node): node is Extract<AtomicNode, { kind: "milestone" }> => {
+    if (node.kind !== "milestone" || !node.scope) return false;
+    return scope.kind === "delivery_unit"
+      ? node.scope.delivery_unit_id === scope.delivery_unit_id
+      : node.scope.kind === "task" && node.scope.task_id === scope.task_id;
+  });
+  if (!scoped.length && !scopedMilestones.length) return "planned";
+  if (scoped.some((node) => node.kind === "work" && node.state === "blocked")) return "blocked";
+  if (scopedMilestones.some((node) => {
+    const evaluation = milestoneEvaluations.get(node.id);
+    return evaluation?.status === "blocked";
+  })) return "blocked";
+  if (scoped.every((node) => node.kind === "work" && node.state === "completed") && scopedMilestones.every((node) => milestoneEvaluations.get(node.id)?.status === "satisfied")) return "completed";
+  if (scoped.some((node) => node.kind === "work" && (node.state === "running" || node.state === "starting"))) return "running";
+  if (scoped.some((node) => node.kind === "work" && node.state === "planned")) return "ready";
+  return "planned";
+}
+
+export function validateContributionStart(node: AtomicNode, deliveryUnit: { pr: DeliveryUnitExternalFacts; parent_branch?: string | null }): void {
+  if (node.kind !== "work" || node.activity_type !== "contribution" || node.state !== "starting") return;
+  if (deliveryUnit.pr.state !== "published" && deliveryUnit.pr.state !== "merged") throw new Error("Contribution work requires a published DeliveryUnit PR before starting");
+  if (!deliveryUnit.parent_branch) throw new Error("Contribution work requires a DeliveryUnit parent branch before starting");
+}
+
+export type MilestoneEvaluation =
+  | { status: "pending"; unmet: string[]; evidence_refs: string[] }
+  | { status: "satisfied"; evidence_refs: string[]; satisfied_at: string }
+  | { status: "blocked"; blockers: z.infer<typeof atomicBlocker>[]; evidence_refs: string[] };
+
+export function validateAtomicGraph(nodes: readonly AtomicNode[], edges: readonly AtomicEdge[]): void {
+  const ids = new Set<string>();
+  for (const node of nodes) {
+    if (ids.has(node.id)) throw new Error(`Duplicate atomic node: ${node.id}`);
+    ids.add(node.id);
+  }
+  const outgoing = new Map<string, string[]>();
+  for (const edge of edges) {
+    if (!ids.has(edge.from_node_id) || !ids.has(edge.to_node_id)) throw new Error(`Atomic edge references missing node: ${edge.id}`);
+    const list = outgoing.get(edge.from_node_id) ?? [];
+    list.push(edge.to_node_id);
+    outgoing.set(edge.from_node_id, list);
+  }
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const visit = (nodeId: string): void => {
+    if (visiting.has(nodeId)) throw new Error("Atomic graph must be acyclic");
+    if (visited.has(nodeId)) return;
+    visiting.add(nodeId);
+    for (const target of outgoing.get(nodeId) ?? []) visit(target);
+    visiting.delete(nodeId);
+    visited.add(nodeId);
+  };
+  for (const node of nodes) visit(node.id);
+  for (const node of nodes) {
+    if (node.kind === "milestone" && node.state === "planned") {
+      const incoming = edges.filter((edge) => edge.to_node_id === node.id);
+      if (!incoming.length && !node.acceptance.length) throw new Error(`Planned milestone ${node.id} must have conditions`);
+    }
+  }
+}
+
+export function evaluateMilestone(
+  node: Extract<AtomicNode, { kind: "milestone" }>,
+  incoming: readonly { satisfied: boolean; blocked?: boolean; evidence_refs?: string[] }[],
+  acceptance: readonly { satisfied: boolean; blocked?: boolean; evidence_refs?: string[] }[],
+  now = new Date().toISOString(),
+): MilestoneEvaluation {
+  const conditions = [...incoming, ...acceptance];
+  if (!conditions.length) throw new Error(`Milestone ${node.id} has no conditions`);
+  const evidence_refs = conditions.flatMap((condition) => condition.evidence_refs ?? []);
+  if (conditions.some((condition) => condition.blocked)) return { status: "blocked", blockers: [{ code: "MILESTONE_CONDITION_FAILED", message: `Milestone ${node.id} has a failed condition`, evidence_refs }], evidence_refs };
+  if (conditions.every((condition) => condition.satisfied)) return { status: "satisfied", evidence_refs, satisfied_at: now };
+  return { status: "pending", unmet: conditions.map((_, index) => String(index)).filter((_, index) => !conditions[index]!.satisfied), evidence_refs };
+}
+
+export function migrateLegacyTaskAtoms(raw: any): any[] {
+  const groups = Array.isArray(raw?.groups) ? raw.groups : [];
+  if (groups.some((group: any) => Array.isArray(group?.atoms) && group.atoms.length))
+    throw new Error("Legacy Group.atoms has ambiguous semantics; explicit plan revision is required");
+  const tasks = Array.isArray(raw?.tasks) ? raw.tasks : [];
+  return tasks.flatMap((task: any) =>
+    (Array.isArray(task?.atoms) ? task.atoms : []).map((atom: any) => {
+      const state = atom.status === "completed" ? "completed" : atom.status === "blocked" ? "blocked" : atom.status === "running" ? "running" : "planned";
+      const scope = { kind: "task", task_id: task.id, delivery_unit_id: task.group_id };
+      if (state === "planned") return { kind: "work", id: atom.id, title: atom.title, purpose: atom.title, output: atom.title, acceptance: [], activity_type: "contribution", state, scope };
+      const runtime = { started_at: task.started_at ?? new Date(0).toISOString(), updated_at: task.finished_at ?? task.started_at ?? new Date(0).toISOString(), evidence_refs: [] };
+      if (state === "completed") return { kind: "work", id: atom.id, title: atom.title, purpose: atom.title, output: atom.title, acceptance: [], activity_type: "contribution", state, scope, runtime, result: { completed_at: task.finished_at ?? runtime.updated_at, evidence_refs: ["legacy:task:" + task.id] } };
+      if (state === "blocked") return { kind: "work", id: atom.id, title: atom.title, purpose: atom.title, output: atom.title, acceptance: [], activity_type: "contribution", state, scope, runtime, blocker: { code: "LEGACY_BLOCKED", message: task.blocker ?? "Legacy task was blocked", evidence_refs: [] } };
+      return { kind: "work", id: atom.id, title: atom.title, purpose: atom.title, output: atom.title, acceptance: [], activity_type: "contribution", state, scope, runtime };
+    }),
+  );
+}
+
+export function contract3MigrationCandidate(raw: any): any {
+  const candidate = structuredClone(raw);
+  const legacyNodes = migrateLegacyTaskAtoms(raw);
+  const legacyEdges = Array.isArray(raw?.plans?.[0]?.atomic_edges) ? raw.plans[0].atomic_edges : [];
+  const canonicalEdges = legacyEdges
+    .filter((edge: any) => edge && typeof edge.from_atom_id === "string" && typeof edge.to_atom_id === "string")
+    .map((edge: any) => ({ id: edge.id, from_node_id: edge.from_atom_id, to_node_id: edge.to_atom_id, requires: { kind: "source_terminal_success" } }));
+  candidate.contract_version = 3;
+  candidate.groups = Array.isArray(candidate.groups) ? candidate.groups.map((group: any) => {
+    if (group.pr && typeof group.pr.state === "string") return group;
+    if (group.parent_pr) {
+      const state = group.state === "merged" ? "merged" : group.state === "closed" ? "closed" : "published";
+      return { ...group, pr: state === "merged" ? { state, pr: group.parent_pr, parent_branch: group.parent_branch ?? "main", merge_sha: group.merge_sha ?? "0000000000000000000000000000000000000000" } : state === "closed" ? { state, pr: group.parent_pr, parent_branch: group.parent_branch ?? "main", closed_at: group.finished_at ?? new Date(0).toISOString(), closed_reason: "provider_closed" } : { state, pr: group.parent_pr, parent_branch: group.parent_branch ?? "main" } };
+    }
+    return { ...group, pr: { state: "unpublished" } };
+  }) : candidate.groups;
+  candidate.tasks = Array.isArray(candidate.tasks) ? candidate.tasks.map((task: any) => {
+    if (task.pr && typeof task.pr.state === "string") return task;
+    if (task.pr && task.branch && task.base_branch) {
+      const state = task.state === "integrated" || task.state === "completed" ? "merged" : task.state === "closed" ? "closed" : "open";
+      return { ...task, pr: state === "merged" ? { state, pr: task.pr, branch: task.branch, merge_sha: task.merge_sha ?? "0000000000000000000000000000000000000000" } : state === "closed" ? { state, pr: task.pr, branch: task.branch, closed_at: task.finished_at ?? new Date(0).toISOString(), closed_reason: "provider_closed" } : { state, pr: task.pr, branch: task.branch, base_branch: task.base_branch } };
+    }
+    return { ...task, pr: { state: "unbound" } };
+  }) : candidate.tasks;
+  candidate.atomic_nodes = Array.isArray(raw?.atomic_nodes) && raw.atomic_nodes.length ? raw.atomic_nodes : legacyNodes;
+  candidate.atomic_edges = Array.isArray(raw?.atomic_edges) && raw.atomic_edges.length ? raw.atomic_edges : canonicalEdges;
+  candidate.plans = Array.isArray(candidate.plans)
+    ? candidate.plans.map((plan: any) => ({
+        ...plan,
+        atomic_nodes: Array.isArray(plan.atomic_nodes) && plan.atomic_nodes.length ? plan.atomic_nodes : candidate.atomic_nodes,
+        atomic_edges: Array.isArray(plan.atomic_edges) && plan.atomic_edges.some((edge: any) => edge?.from_node_id) ? plan.atomic_edges : candidate.atomic_edges,
+      }))
+    : candidate.plans;
+  return candidate;
+}

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

@@ -4,7 +4,7 @@ import { ledgerSchema, type Ledger, type PlanRevision } from "../lib/schema";
 
 export const CONTRACT_VERSION = 3 as const;
 export const SKILL_ID = "multi-task-flow" as const;
-export const SKILL_VERSION = "2.7.2" as const;
+export const SKILL_VERSION = "2.7.6" as const;
 export const VIEWER_CONTRACT = 5 as const;
 export const versionEnvelope = { skill_id: SKILL_ID, skill_version: SKILL_VERSION, viewer_contract: VIEWER_CONTRACT } as const;