@xenonbyte/da-vinci-workflow 0.2.7 → 0.2.9

package/lib/workflow-task-groups.js

@@ -0,0 +1,881 @@
+const { parseTasksArtifact } = require("./planning-parsers");
+const { STATUS, CHECKPOINT_LABELS } = require("./workflow-contract");
+const { dedupeMessages, pathExists, readTextIfExists } = require("./utils");
+const {
+  resolveWorkflowStatePath,
+  resolveTaskGroupMetadataPath,
+  readTaskGroupMetadata,
+  digestForPath
+} = require("./workflow-persisted-state");
+const { formatPathRef } = require("./workflow-decision-trace");
+
+const TRACEABLE_TASK_GROUP_FOCUS_REASONS = new Set([
+  "implementer_block",
+  "implementer_warn",
+  "spec_review_missing",
+  "spec_review_block",
+  "spec_review_warn",
+  "quality_review_missing",
+  "quality_review_block",
+  "quality_review_warn"
+]);
+const TASK_GROUP_SEED_TRACE_KEYS = Object.freeze({
+  missing: "seed_missing",
+  unreadable: "seed_unreadable",
+  "digest-mismatch": "seed_digest_mismatch",
+  legacy: "seed_legacy_embedded"
+});
+
+/**
+ * @typedef {Object} TaskGroupPlan
+ * @property {string} taskGroupId
+ * @property {string} title
+ * @property {string} status
+ * @property {number} completion
+ * @property {string} checkpointOutcome
+ * @property {string[]} evidence
+ * @property {string} nextAction
+ * @property {string[]} [targetFiles]
+ * @property {string[]} [fileReferences]
+ * @property {string[]} [verificationActions]
+ * @property {string[]} [verificationCommands]
+ * @property {string[]} [executionIntent]
+ * @property {boolean} [reviewIntent]
+ * @property {boolean} [testingIntent]
+ * @property {boolean} [codeChangeLikely]
+ * @property {{ groupIndex: number | null, nextUncheckedItem: string | null }} [resumeCursor]
+ */
+
+/**
+ * @typedef {Object} TaskGroupRuntimeEnvelope
+ * @property {boolean} present
+ * @property {string | null} [signalStatus]
+ * @property {string | null} [implementerStatus]
+ * @property {string | null} [summary]
+ * @property {string[]} [changedFiles]
+ * @property {string[]} [testEvidence]
+ * @property {string[]} [concerns]
+ * @property {string[]} [blockers]
+ * @property {string[]} [outOfScopeWrites]
+ * @property {string | null} [recordedAt]
+ */
+
+/**
+ * @typedef {Object} TaskGroupRuntimeState
+ * @property {string} taskGroupId
+ * @property {string} title
+ * @property {string} status
+ * @property {number} completion
+ * @property {string} checkpointOutcome
+ * @property {string[]} evidence
+ * @property {string} nextAction
+ * @property {string[]} targetFiles
+ * @property {string[]} fileReferences
+ * @property {string[]} verificationActions
+ * @property {string[]} verificationCommands
+ * @property {string[]} executionIntent
+ * @property {boolean} reviewIntent
+ * @property {boolean} testingIntent
+ * @property {boolean} codeChangeLikely
+ * @property {{ groupIndex: number | null, nextUncheckedItem: string | null, liveFocus?: string | null }} resumeCursor
+ * @property {object} planned
+ * @property {TaskGroupRuntimeEnvelope} implementer
+ * @property {object} review
+ * @property {object} effective
+ */
+
+/**
+ * @typedef {Object} TaskGroupSeedResolution
+ * @property {Array<object>} taskGroups
+ * @property {string[]} notes
+ */
+
+function recordDecision(callback, records, record) {
+  if (typeof callback === "function") {
+    callback(records, record);
+  }
+}
+
+function buildTaskGroupFocusEvidenceRefs(taskGroupId, reason) {
+  if (reason === "implementer_block" || reason === "implementer_warn") {
+    return [`signal:task-execution.${taskGroupId}`];
+  }
+  if (reason === "spec_review_block" || reason === "spec_review_warn") {
+    return [`signal:task-review.${taskGroupId}.spec`];
+  }
+  if (reason === "quality_review_block" || reason === "quality_review_warn") {
+    return [`signal:task-review.${taskGroupId}.quality`];
+  }
+  return [];
+}
+
+function buildTaskGroupFocusReasonSummary(taskGroupId, reason) {
+  switch (reason) {
+    case "implementer_block":
+      return `Implementer BLOCK overrides planned checklist focus for task group ${taskGroupId}.`;
+    case "implementer_warn":
+      return `Implementer WARN overrides planned checklist focus for task group ${taskGroupId}.`;
+    case "spec_review_missing":
+      return `Missing spec review takes focus over planned checklist work for task group ${taskGroupId}.`;
+    case "spec_review_block":
+      return `Spec review BLOCK takes focus over planned checklist work for task group ${taskGroupId}.`;
+    case "spec_review_warn":
+      return `Spec review WARN follow-up takes focus over planned checklist work for task group ${taskGroupId}.`;
+    case "quality_review_missing":
+      return `Missing quality review takes focus over planned checklist work for task group ${taskGroupId}.`;
+    case "quality_review_block":
+      return `Quality review BLOCK takes focus over planned checklist work for task group ${taskGroupId}.`;
+    case "quality_review_warn":
+      return `Quality review WARN follow-up takes focus over planned checklist work for task group ${taskGroupId}.`;
+    default:
+      return "";
+  }
+}
+
+/**
+ * Parse `tasks.md` into canonical task-group plan metadata.
+ *
+ * @param {string} tasksMarkdownText
+ * @param {Object.<string, string>} checkpointStatuses
+ * @returns {TaskGroupPlan[]}
+ */
+function deriveTaskGroupMetadata(tasksMarkdownText, checkpointStatuses) {
+  if (!tasksMarkdownText) {
+    return [];
+  }
+
+  const taskArtifact = parseTasksArtifact(tasksMarkdownText);
+  const lines = String(tasksMarkdownText || "").replace(/\r\n?/g, "\n").split("\n");
+  const sections = [];
+  let current = null;
+  for (const line of lines) {
+    const headingMatch = line.match(/^\s{0,3}##\s+(\d+(?:\.\d+)*)\.\s+(.+)$/);
+    if (headingMatch) {
+      if (current) {
+        sections.push(current);
+      }
+      current = {
+        id: headingMatch[1],
+        title: String(headingMatch[2] || "").trim(),
+        checklistItems: []
+      };
+      continue;
+    }
+    if (!current) {
+      continue;
+    }
+    const checklistMatch = line.match(/^\s*-\s*\[([ xX])\]\s+(.+)$/);
+    if (checklistMatch) {
+      current.checklistItems.push({
+        checked: String(checklistMatch[1] || "").toLowerCase() === "x",
+        text: String(checklistMatch[2] || "").trim()
+      });
+    }
+  }
+  if (current) {
+    sections.push(current);
+  }
+
+  const normalizedTaskCheckpoint = checkpointStatuses[CHECKPOINT_LABELS.TASK] || STATUS.WARN;
+  const groupMetadataById = new Map(
+    (taskArtifact.taskGroups || []).map((group) => [
+      group.id,
+      {
+        targetFiles: Array.isArray(group.targetFiles) ? group.targetFiles : [],
+        fileReferences: Array.isArray(group.fileReferences) ? group.fileReferences : [],
+        verificationActions: Array.isArray(group.verificationActions) ? group.verificationActions : [],
+        verificationCommands: Array.isArray(group.verificationCommands) ? group.verificationCommands : [],
+        executionIntent: Array.isArray(group.executionIntent) ? group.executionIntent : [],
+        reviewIntent: group.reviewIntent === true,
+        testingIntent: group.testingIntent === true,
+        codeChangeLikely: group.codeChangeLikely === true
+      }
+    ])
+  );
+  const metadata = sections.map((section, index) => {
+    const total = section.checklistItems.length;
+    const done = section.checklistItems.filter((item) => item.checked).length;
+    const completion = total > 0 ? Math.round((done / total) * 100) : 0;
+    const sectionStatus =
+      total === 0 ? "pending" : done === 0 ? "pending" : done < total ? "in_progress" : "completed";
+    const nextAction =
+      sectionStatus === "completed"
+        ? "advance to next task group"
+        : section.checklistItems.find((item) => !item.checked)?.text || "continue group work";
+    const groupMetadata = groupMetadataById.get(section.id) || {};
+
+    return {
+      taskGroupId: section.id,
+      title: section.title,
+      status: sectionStatus,
+      completion,
+      checkpointOutcome: normalizedTaskCheckpoint,
+      evidence: section.checklistItems.filter((item) => item.checked).map((item) => item.text),
+      nextAction,
+      targetFiles: groupMetadata.targetFiles || [],
+      fileReferences: groupMetadata.fileReferences || [],
+      verificationActions: groupMetadata.verificationActions || [],
+      verificationCommands: groupMetadata.verificationCommands || [],
+      executionIntent: groupMetadata.executionIntent || [],
+      reviewIntent: groupMetadata.reviewIntent === true,
+      testingIntent: groupMetadata.testingIntent === true,
+      codeChangeLikely: groupMetadata.codeChangeLikely === true,
+      resumeCursor: {
+        groupIndex: index,
+        nextUncheckedItem:
+          section.checklistItems.find((item) => !item.checked)?.text ||
+          section.checklistItems[section.checklistItems.length - 1]?.text ||
+          null
+      }
+    };
+  });
+
+  if (metadata.length === 0 && taskArtifact.taskGroups.length > 0) {
+    return taskArtifact.taskGroups.map((group, index) => {
+      const groupMetadata = groupMetadataById.get(group.id) || {};
+      return {
+        taskGroupId: group.id,
+        title: group.title,
+        status: "pending",
+        completion: 0,
+        checkpointOutcome: normalizedTaskCheckpoint,
+        evidence: [],
+        nextAction: "start task group",
+        targetFiles: groupMetadata.targetFiles || [],
+        fileReferences: groupMetadata.fileReferences || [],
+        verificationActions: groupMetadata.verificationActions || [],
+        verificationCommands: groupMetadata.verificationCommands || [],
+        executionIntent: groupMetadata.executionIntent || [],
+        reviewIntent: groupMetadata.reviewIntent === true,
+        testingIntent: groupMetadata.testingIntent === true,
+        codeChangeLikely: groupMetadata.codeChangeLikely === true,
+        resumeCursor: {
+          groupIndex: index,
+          nextUncheckedItem: null
+        }
+      };
+    });
+  }
+
+  return metadata;
+}
+
+function normalizeTaskGroupId(value) {
+  return String(value || "").trim();
+}
+
+function normalizeResumeCursor(cursor, fallbackGroupIndex = null) {
+  const groupIndex =
+    cursor && Number.isInteger(cursor.groupIndex)
+      ? cursor.groupIndex
+      : Number.isInteger(fallbackGroupIndex)
+      ? fallbackGroupIndex
+      : null;
+  return {
+    groupIndex,
+    nextUncheckedItem:
+      cursor && Object.prototype.hasOwnProperty.call(cursor, "nextUncheckedItem")
+        ? cursor.nextUncheckedItem
+        : null
+  };
+}
+
+function normalizeTaskGroupSeedMap(taskGroups) {
+  const byId = new Map();
+  for (const group of Array.isArray(taskGroups) ? taskGroups : []) {
+    const taskGroupId = normalizeTaskGroupId(group && (group.taskGroupId || group.id));
+    if (!taskGroupId || byId.has(taskGroupId)) {
+      continue;
+    }
+    byId.set(taskGroupId, group);
+  }
+  return byId;
+}
+
+function findLatestSignalBySurface(signals, surface) {
+  const normalizedSurface = String(surface || "").trim();
+  if (!normalizedSurface) {
+    return null;
+  }
+  return (signals || []).find((signal) => String(signal.surface || "").trim() === normalizedSurface) || null;
+}
+
+function summarizeSignalIssues(signal, envelopeItems) {
+  if (!signal) {
+    return [];
+  }
+  const fromEnvelope = Array.isArray(envelopeItems) ? envelopeItems : [];
+  const fromSignal = [
+    ...(Array.isArray(signal.failures) ? signal.failures : []),
+    ...(Array.isArray(signal.warnings) ? signal.warnings : [])
+  ];
+  return dedupeMessages([...fromEnvelope, ...fromSignal].map((item) => String(item || "").trim()).filter(Boolean));
+}
+
+function buildTaskGroupImplementerState(taskGroupId, signals, fallbackState) {
+  const fallback = fallbackState && typeof fallbackState === "object" ? fallbackState : {};
+  const signal = findLatestSignalBySurface(signals, `task-execution.${taskGroupId}`);
+  const envelope = signal && signal.details && signal.details.envelope ? signal.details.envelope : null;
+  if (!signal) {
+    return {
+      present: false,
+      signalStatus: null,
+      implementerStatus: fallback.implementerStatus || null,
+      summary: fallback.summary || null,
+      changedFiles: Array.isArray(fallback.changedFiles) ? fallback.changedFiles : [],
+      testEvidence: Array.isArray(fallback.testEvidence) ? fallback.testEvidence : [],
+      concerns: Array.isArray(fallback.concerns) ? fallback.concerns : [],
+      blockers: Array.isArray(fallback.blockers) ? fallback.blockers : [],
+      outOfScopeWrites: Array.isArray(fallback.outOfScopeWrites) ? fallback.outOfScopeWrites : [],
+      recordedAt: fallback.recordedAt || null
+    };
+  }
+
+  return {
+    present: true,
+    signalStatus: signal.status || null,
+    implementerStatus: envelope && envelope.status ? envelope.status : fallback.implementerStatus || null,
+    summary: envelope && envelope.summary ? envelope.summary : fallback.summary || null,
+    changedFiles:
+      envelope && Array.isArray(envelope.changedFiles)
+        ? envelope.changedFiles
+        : Array.isArray(fallback.changedFiles)
+        ? fallback.changedFiles
+        : [],
+    testEvidence:
+      envelope && Array.isArray(envelope.testEvidence)
+        ? envelope.testEvidence
+        : Array.isArray(fallback.testEvidence)
+        ? fallback.testEvidence
+        : [],
+    concerns: summarizeSignalIssues(signal, envelope && envelope.concerns),
+    blockers: summarizeSignalIssues(signal, envelope && envelope.blockers),
+    outOfScopeWrites:
+      signal.details && Array.isArray(signal.details.outOfScopeWrites)
+        ? dedupeMessages(signal.details.outOfScopeWrites.map((item) => String(item || "").trim()).filter(Boolean))
+        : Array.isArray(fallback.outOfScopeWrites)
+        ? fallback.outOfScopeWrites
+        : [],
+    recordedAt: (envelope && envelope.recordedAt) || signal.timestamp || fallback.recordedAt || null
+  };
+}
+
+function buildTaskGroupReviewStageState(taskGroupId, stage, signals, fallbackState) {
+  const fallback = fallbackState && typeof fallbackState === "object" ? fallbackState : {};
+  const signal = findLatestSignalBySurface(signals, `task-review.${taskGroupId}.${stage}`);
+  const envelope = signal && signal.details && signal.details.envelope ? signal.details.envelope : null;
+  if (!signal) {
+    return {
+      present: false,
+      status: fallback.status || "missing",
+      summary: fallback.summary || null,
+      reviewer: fallback.reviewer || null,
+      issues: Array.isArray(fallback.issues) ? fallback.issues : [],
+      recordedAt: fallback.recordedAt || null
+    };
+  }
+
+  return {
+    present: true,
+    status: signal.status || "missing",
+    summary: envelope && envelope.summary ? envelope.summary : fallback.summary || null,
+    reviewer: envelope && envelope.reviewer ? envelope.reviewer : fallback.reviewer || null,
+    issues: summarizeSignalIssues(signal, envelope && envelope.issues),
+    recordedAt: (envelope && envelope.recordedAt) || signal.timestamp || fallback.recordedAt || null
+  };
+}
+
+function buildTaskGroupReviewState(taskGroup, signals, fallbackState) {
+  const fallback = fallbackState && typeof fallbackState === "object" ? fallbackState : {};
+  const taskGroupId = normalizeTaskGroupId(taskGroup.taskGroupId || taskGroup.id);
+  const required = taskGroup.reviewIntent === true;
+  const spec = buildTaskGroupReviewStageState(taskGroupId, "spec", signals, fallback.spec);
+  const quality = buildTaskGroupReviewStageState(taskGroupId, "quality", signals, fallback.quality);
+
+  return {
+    required,
+    ordering: required ? "spec_then_quality" : "none",
+    spec,
+    quality
+  };
+}
+
+function buildEffectiveTaskGroupState(group, planned, implementer, review) {
+  const fallbackCursor = normalizeResumeCursor(planned.resumeCursor, null);
+  const effective = {
+    status: planned.status,
+    nextAction: planned.nextAction,
+    resumeCursor: fallbackCursor,
+    source: "planned",
+    reason: "planned_checklist"
+  };
+
+  if (implementer.present && implementer.outOfScopeWrites.length > 0) {
+    return {
+      status: "blocked",
+      nextAction:
+        `resolve out-of-scope writes for task group ${group.taskGroupId}: ${implementer.outOfScopeWrites.join(", ")}`,
+      resumeCursor: {
+        groupIndex: fallbackCursor.groupIndex,
+        nextUncheckedItem: null,
+        liveFocus: "out_of_scope_write"
+      },
+      source: "implementer",
+      reason: "out_of_scope_write"
+    };
+  }
+
+  if (implementer.present && implementer.signalStatus === STATUS.BLOCK) {
+    return {
+      status: "blocked",
+      nextAction:
+        implementer.blockers[0] ||
+        implementer.summary ||
+        `resolve implementer blocker for task group ${group.taskGroupId}`,
+      resumeCursor: {
+        groupIndex: fallbackCursor.groupIndex,
+        nextUncheckedItem: null,
+        liveFocus: "implementer_block"
+      },
+      source: "implementer",
+      reason: "implementer_block"
+    };
+  }
+
+  const reviewSignalsPresent = review.spec.present || review.quality.present;
+  const plannedCompletion = Number.isFinite(Number(planned.completion))
+    ? Number(planned.completion)
+    : 0;
+  const reviewNearComplete = planned.status !== "completed" && plannedCompletion >= 75;
+  const reviewHardDue = planned.status === "completed" || reviewNearComplete;
+  const reviewContextReady = review.required && (reviewSignalsPresent || reviewHardDue || implementer.present);
+
+  if (reviewContextReady) {
+    if (
+      review.quality.present &&
+      (!review.spec.present || review.spec.status === "missing" || review.spec.status === STATUS.WARN)
+    ) {
+      return {
+        status: "blocked",
+        nextAction:
+          `remove or rerun out-of-order quality review for task group ${group.taskGroupId} after spec review PASS`,
+        resumeCursor: {
+          groupIndex: fallbackCursor.groupIndex,
+          nextUncheckedItem: null,
+          liveFocus: "review_ordering_violation"
+        },
+        source: "review",
+        reason: "review_ordering_violation"
+      };
+    }
+    if (review.spec.status === STATUS.BLOCK) {
+      return {
+        status: "blocked",
+        nextAction:
+          review.spec.issues[0] || review.spec.summary || `resolve spec review BLOCK for task group ${group.taskGroupId}`,
+        resumeCursor: {
+          groupIndex: fallbackCursor.groupIndex,
+          nextUncheckedItem: null,
+          liveFocus: "spec_review_block"
+        },
+        source: "review",
+        reason: "spec_review_block"
+      };
+    }
+    if (!review.spec.present || review.spec.status === "missing") {
+      if (reviewHardDue || reviewSignalsPresent) {
+        return {
+          status: "review_pending",
+          nextAction: `record spec review PASS or WARN for task group ${group.taskGroupId} before quality review`,
+          resumeCursor: {
+            groupIndex: fallbackCursor.groupIndex,
+            nextUncheckedItem: null,
+            liveFocus: "spec_review_missing"
+          },
+          source: "review",
+          reason: "spec_review_missing"
+        };
+      }
+    } else {
+      const specWarn = review.spec.status === STATUS.WARN;
+      if (review.quality.status === STATUS.BLOCK) {
+        return {
+          status: "blocked",
+          nextAction:
+            review.quality.issues[0] ||
+            review.quality.summary ||
+            `resolve quality review BLOCK for task group ${group.taskGroupId}`,
+          resumeCursor: {
+            groupIndex: fallbackCursor.groupIndex,
+            nextUncheckedItem: null,
+            liveFocus: "quality_review_block"
+          },
+          source: "review",
+          reason: "quality_review_block"
+        };
+      }
+      if (!review.quality.present || review.quality.status === "missing") {
+        if (reviewHardDue) {
+          return {
+            status: "review_pending",
+            nextAction: `record quality review PASS or WARN for task group ${group.taskGroupId}`,
+            resumeCursor: {
+              groupIndex: fallbackCursor.groupIndex,
+              nextUncheckedItem: null,
+              liveFocus: "quality_review_missing"
+            },
+            source: "review",
+            reason: "quality_review_missing"
+          };
+        }
+        if (specWarn) {
+          return {
+            status: "in_progress",
+            nextAction:
+              review.spec.issues[0] ||
+              review.spec.summary ||
+              `resolve spec review follow-up for task group ${group.taskGroupId}`,
+            resumeCursor: {
+              groupIndex: fallbackCursor.groupIndex,
+              nextUncheckedItem: null,
+              liveFocus: "spec_review_warn"
+            },
+            source: "review",
+            reason: "spec_review_warn"
+          };
+        }
+      } else if (review.quality.status === STATUS.WARN) {
+        return {
+          status: "in_progress",
+          nextAction:
+            review.quality.issues[0] ||
+            review.quality.summary ||
+            `resolve quality review follow-up for task group ${group.taskGroupId}`,
+          resumeCursor: {
+            groupIndex: fallbackCursor.groupIndex,
+            nextUncheckedItem: null,
+            liveFocus: "quality_review_warn"
+          },
+          source: "review",
+          reason: "quality_review_warn"
+        };
+      } else if (specWarn) {
+        return {
+          status: "in_progress",
+          nextAction:
+            review.spec.issues[0] ||
+            review.spec.summary ||
+            `resolve spec review follow-up for task group ${group.taskGroupId}`,
+          resumeCursor: {
+            groupIndex: fallbackCursor.groupIndex,
+            nextUncheckedItem: null,
+            liveFocus: "spec_review_warn"
+          },
+          source: "review",
+          reason: "spec_review_warn"
+        };
+      }
+    }
+  }
+
+  if (implementer.present && implementer.signalStatus === STATUS.WARN) {
+    return {
+      status: "in_progress",
+      nextAction:
+        implementer.concerns[0] ||
+        implementer.summary ||
+        `resolve implementer concerns for task group ${group.taskGroupId}`,
+      resumeCursor: {
+        groupIndex: fallbackCursor.groupIndex,
+        nextUncheckedItem: null,
+        liveFocus: "implementer_warn"
+      },
+      source: "implementer",
+      reason: "implementer_warn"
+    };
+  }
+
+  return effective;
+}
+
+/**
+ * Overlay runtime implementer/review signals on top of planned task groups.
+ *
+ * @param {TaskGroupPlan[]} plannedTaskGroups
+ * @param {Array<object>} signals
+ * @param {Array<object>} seedTaskGroups
+ * @param {Array<object> | null} decisionTraceRecords
+ * @param {Function | null} recordWorkflowDecision
+ * @returns {TaskGroupRuntimeState[]}
+ */
+function deriveTaskGroupRuntimeState(
+  plannedTaskGroups,
+  signals,
+  seedTaskGroups,
+  decisionTraceRecords,
+  recordWorkflowDecision
+) {
+  const plannedGroups = Array.isArray(plannedTaskGroups) ? plannedTaskGroups : [];
+  const seedMap = normalizeTaskGroupSeedMap(seedTaskGroups);
+
+  return plannedGroups.map((plannedGroup, index) => {
+    const taskGroupId = normalizeTaskGroupId(plannedGroup.taskGroupId || plannedGroup.id);
+    const seed = seedMap.get(taskGroupId) || {};
+    const planned = {
+      status: plannedGroup.status,
+      completion: plannedGroup.completion,
+      checkpointOutcome: plannedGroup.checkpointOutcome,
+      evidence: Array.isArray(plannedGroup.evidence) ? plannedGroup.evidence : [],
+      nextAction: plannedGroup.nextAction,
+      resumeCursor: normalizeResumeCursor(plannedGroup.resumeCursor, index)
+    };
+    const implementer = buildTaskGroupImplementerState(taskGroupId, signals, seed.implementer);
+    const review = buildTaskGroupReviewState(plannedGroup, signals, seed.review);
+    const effective = buildEffectiveTaskGroupState(plannedGroup, planned, implementer, review);
+    if (TRACEABLE_TASK_GROUP_FOCUS_REASONS.has(effective.reason)) {
+      recordDecision(recordWorkflowDecision, decisionTraceRecords, {
+        decisionFamily: "task_group_focus_resolution",
+        decisionKey: effective.reason,
+        outcome: "selected_focus",
+        reasonSummary: buildTaskGroupFocusReasonSummary(taskGroupId, effective.reason),
+        context: {
+          taskGroupId,
+          plannedStatus: planned.status || null,
+          effectiveStatus: effective.status || null,
+          liveFocus: effective.resumeCursor ? effective.resumeCursor.liveFocus || null : null,
+          nextAction: effective.nextAction || null
+        },
+        evidenceRefs: buildTaskGroupFocusEvidenceRefs(taskGroupId, effective.reason)
+      });
+    }
+
+    return {
+      taskGroupId,
+      title: plannedGroup.title,
+      status: effective.status,
+      completion: planned.completion,
+      checkpointOutcome: planned.checkpointOutcome,
+      evidence: planned.evidence,
+      nextAction: effective.nextAction,
+      targetFiles: Array.isArray(plannedGroup.targetFiles) ? plannedGroup.targetFiles : [],
+      fileReferences: Array.isArray(plannedGroup.fileReferences) ? plannedGroup.fileReferences : [],
+      verificationActions: Array.isArray(plannedGroup.verificationActions)
+        ? plannedGroup.verificationActions
+        : [],
+      verificationCommands: Array.isArray(plannedGroup.verificationCommands)
+        ? plannedGroup.verificationCommands
+        : [],
+      executionIntent: Array.isArray(plannedGroup.executionIntent) ? plannedGroup.executionIntent : [],
+      reviewIntent: plannedGroup.reviewIntent === true,
+      testingIntent: plannedGroup.testingIntent === true,
+      codeChangeLikely: plannedGroup.codeChangeLikely === true,
+      resumeCursor: effective.resumeCursor,
+      planned,
+      implementer,
+      review,
+      effective
+    };
+  });
+}
+
+/**
+ * Build the canonical persisted task-group metadata payload written next to workflow snapshots.
+ *
+ * @param {string} changeId
+ * @param {Object.<string, string>} checkpointStatuses
+ * @param {Array<object>} taskGroups
+ * @returns {{ version: number, changeId: string, checkpointOutcome: string, taskGroups: Array<object>, updatedAt: string }}
+ */
+function buildTaskGroupMetadataPayload(changeId, checkpointStatuses, taskGroups) {
+  return {
+    version: 2,
+    changeId,
+    checkpointOutcome: checkpointStatuses[CHECKPOINT_LABELS.TASK] || STATUS.WARN,
+    taskGroups: Array.isArray(taskGroups) ? taskGroups : [],
+    updatedAt: new Date().toISOString()
+  };
+}
+
+function loadTaskGroupMetadataFromPath(targetPath) {
+  if (!targetPath || !pathExists(targetPath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readTextIfExists(targetPath));
+  } catch (_error) {
+    return null;
+  }
+}
+
+/**
+ * Resolve the task-group seed used when starting from a trusted persisted workflow snapshot.
+ *
+ * @param {string} projectRoot
+ * @param {string} changeId
+ * @param {object} persistedRecord
+ * @param {TaskGroupPlan[]} plannedTaskGroups
+ * @param {Array<object> | null} decisionTraceRecords
+ * @param {Function | null} recordWorkflowDecision
+ * @returns {TaskGroupSeedResolution}
+ */
+function resolvePersistedTaskGroupSeed(
+  projectRoot,
+  changeId,
+  persistedRecord,
+  plannedTaskGroups,
+  decisionTraceRecords,
+  recordWorkflowDecision
+) {
+  const metadataRefs =
+    persistedRecord && persistedRecord.metadataRefs && typeof persistedRecord.metadataRefs === "object"
+      ? persistedRecord.metadataRefs
+      : {};
+  const canonicalPath =
+    metadataRefs.taskGroupsPath || resolveTaskGroupMetadataPath(projectRoot, changeId);
+  const notes = [];
+
+  if (canonicalPath && pathExists(canonicalPath)) {
+    const actualDigest = digestForPath(canonicalPath);
+    const expectedDigest = metadataRefs.taskGroupsDigest || null;
+    if (expectedDigest && actualDigest && expectedDigest !== actualDigest) {
+      const message =
+        "Canonical task-group runtime state digest mismatch; rebuilding task-group state from artifacts.";
+      notes.push(message);
+      recordDecision(recordWorkflowDecision, decisionTraceRecords, {
+        decisionFamily: "task_group_seed_fallback",
+        decisionKey: TASK_GROUP_SEED_TRACE_KEYS["digest-mismatch"],
+        outcome: "fallback",
+        reasonSummary: message,
+        context: {
+          metadataPath: formatPathRef(projectRoot, canonicalPath),
+          taskGroupCount: Array.isArray(plannedTaskGroups) ? plannedTaskGroups.length : 0,
+          expectedDigestPresent: true
+        },
+        evidenceRefs: [`state:${formatPathRef(projectRoot, canonicalPath)}`]
+      });
+      return {
+        taskGroups: plannedTaskGroups,
+        notes
+      };
+    }
+
+    const loaded =
+      canonicalPath === resolveTaskGroupMetadataPath(projectRoot, changeId)
+        ? readTaskGroupMetadata(projectRoot, changeId)
+        : loadTaskGroupMetadataFromPath(canonicalPath);
+    if (loaded && Array.isArray(loaded.taskGroups)) {
+      return {
+        taskGroups: loaded.taskGroups,
+        notes
+      };
+    }
+    {
+      const message =
+        "Canonical task-group runtime state is unreadable; rebuilding task-group state from artifacts.";
+      notes.push(message);
+      recordDecision(recordWorkflowDecision, decisionTraceRecords, {
+        decisionFamily: "task_group_seed_fallback",
+        decisionKey: TASK_GROUP_SEED_TRACE_KEYS.unreadable,
+        outcome: "fallback",
+        reasonSummary: message,
+        context: {
+          metadataPath: formatPathRef(projectRoot, canonicalPath),
+          taskGroupCount: Array.isArray(plannedTaskGroups) ? plannedTaskGroups.length : 0
+        },
+        evidenceRefs: [`state:${formatPathRef(projectRoot, canonicalPath)}`]
+      });
+    }
+    return {
+      taskGroups: plannedTaskGroups,
+      notes
+    };
+  }
+
+  if (Array.isArray(persistedRecord && persistedRecord.taskGroups) && persistedRecord.taskGroups.length > 0) {
+    {
+      const message = "Using legacy embedded task-group state as migration fallback.";
+      notes.push(message);
+      recordDecision(recordWorkflowDecision, decisionTraceRecords, {
+        decisionFamily: "task_group_seed_fallback",
+        decisionKey: TASK_GROUP_SEED_TRACE_KEYS.legacy,
+        outcome: "fallback",
+        reasonSummary: message,
+        context: {
+          metadataPath: canonicalPath ? formatPathRef(projectRoot, canonicalPath) : null,
+          taskGroupCount: persistedRecord.taskGroups.length
+        },
+        evidenceRefs: [`state:${formatPathRef(projectRoot, resolveWorkflowStatePath(projectRoot))}`]
+      });
+    }
+    return {
+      taskGroups: persistedRecord.taskGroups,
+      notes
+    };
+  }
+
+  {
+    const message = "Canonical task-group runtime state is missing; rebuilding task-group state from artifacts.";
+    notes.push(message);
+    recordDecision(recordWorkflowDecision, decisionTraceRecords, {
+      decisionFamily: "task_group_seed_fallback",
+      decisionKey: TASK_GROUP_SEED_TRACE_KEYS.missing,
+      outcome: "fallback",
+      reasonSummary: message,
+      context: {
+        metadataPath: canonicalPath ? formatPathRef(projectRoot, canonicalPath) : null,
+        taskGroupCount: Array.isArray(plannedTaskGroups) ? plannedTaskGroups.length : 0
+      },
+      evidenceRefs:
+        canonicalPath && String(canonicalPath).trim()
+          ? [`state:${formatPathRef(projectRoot, canonicalPath)}`]
+          : []
+    });
+  }
+  return {
+    taskGroups: plannedTaskGroups,
+    notes
+  };
+}
+
+/**
+ * Select the highest-priority task-group focus for next-step reporting.
+ *
+ * @param {Array<{ status?: string, resumeCursor?: { groupIndex?: number } }>} taskGroups
+ * @returns {TaskGroupRuntimeState | object | null}
+ */
+function selectFocusedTaskGroup(taskGroups) {
+  const priority = {
+    blocked: 0,
+    review_pending: 1,
+    in_progress: 2,
+    pending: 3,
+    completed: 4
+  };
+  const groups = Array.isArray(taskGroups) ? taskGroups : [];
+  return groups
+    .slice()
+    .sort((left, right) => {
+      const leftRank = Object.prototype.hasOwnProperty.call(priority, left.status) ? priority[left.status] : 5;
+      const rightRank = Object.prototype.hasOwnProperty.call(priority, right.status) ? priority[right.status] : 5;
+      if (leftRank !== rightRank) {
+        return leftRank - rightRank;
+      }
+      const leftIndex =
+        left && left.resumeCursor && Number.isInteger(left.resumeCursor.groupIndex)
+          ? left.resumeCursor.groupIndex
+          : Number.MAX_SAFE_INTEGER;
+      const rightIndex =
+        right && right.resumeCursor && Number.isInteger(right.resumeCursor.groupIndex)
+          ? right.resumeCursor.groupIndex
+          : Number.MAX_SAFE_INTEGER;
+      return leftIndex - rightIndex;
+    })[0] || null;
+}
+
+module.exports = {
+  deriveTaskGroupMetadata,
+  deriveTaskGroupRuntimeState,
+  buildTaskGroupMetadataPayload,
+  resolvePersistedTaskGroupSeed,
+  selectFocusedTaskGroup
+};