agentic-orchestrator 0.1.28 → 0.2.0

package/packages/web-dashboard/src/lib/focus-detail-derivations.ts

@@ -0,0 +1,958 @@
+import type {
+  ActionableRiskItem,
+  FeatureCheckpoint,
+  FeatureDetail,
+  FeatureSpecSummary,
+  FeatureSummary,
+  FeatureVerificationBlocker,
+  FeatureVerificationItem,
+  FeatureVerificationSummary,
+  GateHistoryEntry,
+  GateRunEvidence,
+  PlanProgressSummary,
+  PlanProgressTaskSummary,
+  QaTestIndex,
+  RevisionSummaryEntry,
+  UsageBurnProjection,
+} from '@/lib/types.js';
+
+type RoleName = 'planner' | 'builder' | 'qa' | 'reconciler' | 'orchestrator';
+
+const ROLE_ORDER: RoleName[] = ['builder', 'qa', 'planner', 'reconciler', 'orchestrator'];
+const ROLE_STATUS_PRIORITY = ['running', 'blocked', 'ready', 'done', 'unknown'] as const;
+
+function isTrackedRole(value: unknown): value is Exclude<RoleName, 'orchestrator'> {
+  return value === 'planner' || value === 'builder' || value === 'qa' || value === 'reconciler';
+}
+
+function resolveExecutionRoleForPhase(
+  phase: FeatureSummary['phase'],
+): Exclude<RoleName, 'orchestrator'> | null {
+  if (phase === 'intake' || phase === 'planning') {
+    return 'planner';
+  }
+  if (phase === 'building') {
+    return 'builder';
+  }
+  if (phase === 'qa') {
+    return 'qa';
+  }
+  return null;
+}
+
+function snapshotActivityTimestamp(snapshot: {
+  updated_at?: string | null;
+  started_at?: string | null;
+  ended_at?: string | null;
+}): number {
+  const candidate = snapshot.updated_at ?? snapshot.started_at ?? snapshot.ended_at ?? null;
+  const parsed = candidate ? Date.parse(candidate) : Number.NaN;
+  return Number.isNaN(parsed) ? Number.NEGATIVE_INFINITY : parsed;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value != null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function asStringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === 'string')
+    : [];
+}
+
+function maxTimestamp(values: Array<string | null | undefined>): string | null {
+  let max: string | null = null;
+  let maxMs = Number.NEGATIVE_INFINITY;
+  for (const value of values) {
+    if (typeof value !== 'string') {
+      continue;
+    }
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed) || parsed < maxMs) {
+      continue;
+    }
+    max = value;
+    maxMs = parsed;
+  }
+  return max;
+}
+
+function normalizeTaskStatus(value: unknown): PlanProgressTaskSummary['status'] {
+  if (typeof value !== 'string') {
+    return 'pending';
+  }
+  const normalized = value.toLowerCase();
+  if (normalized === 'done' || normalized === 'complete' || normalized === 'completed') {
+    return 'completed';
+  }
+  if (normalized === 'running' || normalized === 'active' || normalized === 'in_progress') {
+    return 'in_progress';
+  }
+  if (normalized === 'blocked') {
+    return 'blocked';
+  }
+  return 'pending';
+}
+
+function normalizeOwnerRole(value: unknown): RoleName | null {
+  return value === 'planner' ||
+    value === 'builder' ||
+    value === 'qa' ||
+    value === 'reconciler' ||
+    value === 'orchestrator'
+    ? value
+    : null;
+}
+
+function parseExplicitPlanTasks(plan: Record<string, unknown> | null): PlanProgressTaskSummary[] {
+  if (!plan || !Array.isArray(plan.tasks)) {
+    return [];
+  }
+
+  return plan.tasks
+    .map((entry, index): PlanProgressTaskSummary | null => {
+      if (typeof entry === 'string') {
+        return {
+          id: `task-${index + 1}`,
+          title: entry,
+          status: 'pending',
+        };
+      }
+      const record = asRecord(entry);
+      if (!record) {
+        return null;
+      }
+      const title =
+        typeof record.title === 'string'
+          ? record.title
+          : typeof record.description === 'string'
+            ? record.description
+            : typeof record.summary === 'string'
+              ? record.summary
+              : null;
+      if (!title) {
+        return null;
+      }
+      return {
+        id: typeof record.id === 'string' ? record.id : `task-${index + 1}`,
+        title,
+        status: normalizeTaskStatus(record.status),
+        owner_role: normalizeOwnerRole(record.owner_role ?? record.role),
+        started_at: typeof record.started_at === 'string' ? record.started_at : null,
+        last_updated: typeof record.last_updated === 'string' ? record.last_updated : null,
+        blocked_by: asStringArray(record.blocked_by),
+      };
+    })
+    .filter((entry): entry is PlanProgressTaskSummary => entry != null);
+}
+
+function currentImplementationStatus(
+  feature: FeatureSummary,
+  checkpoints: FeatureCheckpoint[],
+): PlanProgressTaskSummary['status'] {
+  if (feature.phase === 'merged' || feature.phase === 'ready_to_merge' || feature.phase === 'qa') {
+    return 'completed';
+  }
+  if (feature.phase === 'building') {
+    return 'in_progress';
+  }
+  if (feature.phase === 'blocked') {
+    return 'blocked';
+  }
+  return checkpoints.length > 0 ? 'in_progress' : 'pending';
+}
+
+function currentVerificationStatus(
+  feature: FeatureSummary,
+  gateEvidence: GateRunEvidence | null | undefined,
+  qaTestIndex: QaTestIndex | null | undefined,
+): PlanProgressTaskSummary['status'] {
+  if (feature.phase === 'merged') {
+    return 'completed';
+  }
+  const gateFailed =
+    feature.gates?.plan === 'fail' ||
+    feature.gates?.fast === 'fail' ||
+    feature.gates?.full === 'fail' ||
+    feature.gates?.merge === 'fail' ||
+    gateEvidence?.overall === 'fail';
+  if (gateFailed) {
+    return 'blocked';
+  }
+  const qaFailed = (qaTestIndex?.items ?? []).some((item) => item.status === 'failed');
+  if (qaFailed) {
+    return 'blocked';
+  }
+  if (feature.phase === 'ready_to_merge') {
+    return 'completed';
+  }
+  if (feature.phase === 'qa') {
+    return 'in_progress';
+  }
+  return 'pending';
+}
+
+function currentReviewStatus(feature: FeatureSummary): PlanProgressTaskSummary['status'] {
+  if (feature.phase === 'merged') {
+    return 'completed';
+  }
+  const pendingThreads = feature.pr?.pending_review_threads ?? 0;
+  if (feature.phase === 'blocked') {
+    return 'blocked';
+  }
+  if (
+    feature.phase === 'ready_to_merge' &&
+    pendingThreads === 0 &&
+    feature.pr?.has_conflicts !== true
+  ) {
+    return 'in_progress';
+  }
+  if (pendingThreads > 0 || feature.pr?.has_conflicts === true) {
+    return 'blocked';
+  }
+  return feature.phase === 'qa' ? 'pending' : 'pending';
+}
+
+function derivedPlanTasks(
+  plan: Record<string, unknown> | null,
+  feature: FeatureSummary,
+  checkpoints: FeatureCheckpoint[],
+  gateEvidence: GateRunEvidence | null | undefined,
+  qaTestIndex: QaTestIndex | null | undefined,
+): PlanProgressTaskSummary[] {
+  const planUpdatedAt = maxTimestamp([
+    feature.last_meaningful_change_at,
+    feature.last_updated,
+    feature.phase_entered_at,
+  ]);
+  return [
+    {
+      id: 'accepted-plan',
+      title: 'Accepted plan is in place',
+      status: plan ? 'completed' : 'pending',
+      owner_role: 'planner',
+      last_updated: planUpdatedAt,
+    },
+    {
+      id: 'implementation',
+      title: 'Apply planned code changes',
+      status: currentImplementationStatus(feature, checkpoints),
+      owner_role: 'builder',
+      last_updated: maxTimestamp([feature.last_meaningful_change_at, checkpoints[0]?.timestamp]),
+    },
+    {
+      id: 'verification',
+      title: 'Validate gates and QA evidence',
+      status: currentVerificationStatus(feature, gateEvidence, qaTestIndex),
+      owner_role: 'qa',
+      last_updated: maxTimestamp([
+        gateEvidence?.finished_at,
+        ...(qaTestIndex?.items ?? []).map((item) => item.last_run_at),
+      ]),
+    },
+    {
+      id: 'review',
+      title: 'Resolve review and merge blockers',
+      status: currentReviewStatus(feature),
+      owner_role: 'orchestrator',
+      last_updated: maxTimestamp([feature.last_updated, feature.last_meaningful_change_at]),
+      blocked_by:
+        feature.pr?.pending_review_threads && feature.pr.pending_review_threads > 0
+          ? [`${feature.pr.pending_review_threads} open review thread(s)`]
+          : feature.pr?.has_conflicts
+            ? ['merge conflicts']
+            : [],
+    },
+    {
+      id: 'merge',
+      title: 'Merge feature',
+      status:
+        feature.phase === 'merged'
+          ? 'completed'
+          : feature.phase === 'ready_to_merge'
+            ? 'pending'
+            : 'pending',
+      owner_role: 'orchestrator',
+      last_updated: feature.last_updated ?? null,
+    },
+  ];
+}
+
+function countTaskStatuses(
+  tasks: PlanProgressTaskSummary[],
+): Pick<
+  PlanProgressSummary,
+  'completed_tasks' | 'in_progress_tasks' | 'pending_tasks' | 'blocked_tasks'
+> {
+  return tasks.reduce(
+    (counts, task) => {
+      if (task.status === 'completed') {
+        counts.completed_tasks += 1;
+      } else if (task.status === 'in_progress') {
+        counts.in_progress_tasks += 1;
+      } else if (task.status === 'blocked') {
+        counts.blocked_tasks += 1;
+      } else {
+        counts.pending_tasks += 1;
+      }
+      return counts;
+    },
+    {
+      completed_tasks: 0,
+      in_progress_tasks: 0,
+      pending_tasks: 0,
+      blocked_tasks: 0,
+    },
+  );
+}
+
+export function buildPlanProgressSummary(input: {
+  feature: FeatureSummary;
+  plan: Record<string, unknown> | null;
+  checkpoints: FeatureCheckpoint[];
+  gateEvidence?: GateRunEvidence | null;
+  qaTestIndex?: QaTestIndex | null;
+}): PlanProgressSummary {
+  const explicitTasks = parseExplicitPlanTasks(input.plan);
+  const tasks =
+    explicitTasks.length > 0
+      ? explicitTasks
+      : derivedPlanTasks(
+          input.plan,
+          input.feature,
+          input.checkpoints,
+          input.gateEvidence,
+          input.qaTestIndex,
+        );
+  const counts = countTaskStatuses(tasks);
+  const totalTasks = tasks.length;
+  const currentTask =
+    tasks.find((task) => task.status === 'in_progress') ??
+    tasks.find((task) => task.status === 'blocked') ??
+    tasks.find((task) => task.status === 'pending') ??
+    null;
+  const currentTaskId = currentTask?.id ?? null;
+
+  const completedRecently = [...tasks]
+    .filter((task) => task.status === 'completed')
+    .sort((left, right) => {
+      const leftMs = Date.parse(left.last_updated ?? left.started_at ?? '');
+      const rightMs = Date.parse(right.last_updated ?? right.started_at ?? '');
+      return (Number.isNaN(rightMs) ? 0 : rightMs) - (Number.isNaN(leftMs) ? 0 : leftMs);
+    })
+    .slice(0, 3)
+    .map((task) => ({
+      id: task.id,
+      title: task.title,
+      completed_at: task.last_updated ?? task.started_at ?? null,
+    }));
+
+  return {
+    total_tasks: totalTasks,
+    completed_tasks: counts.completed_tasks,
+    in_progress_tasks: counts.in_progress_tasks,
+    pending_tasks: counts.pending_tasks,
+    blocked_tasks: counts.blocked_tasks,
+    percent_complete:
+      totalTasks === 0 ? 0 : Math.round((counts.completed_tasks / totalTasks) * 100),
+    current_task: currentTask,
+    next_tasks: tasks
+      .filter(
+        (task) =>
+          (task.status === 'pending' || task.status === 'blocked') &&
+          (currentTaskId == null || task.id !== currentTaskId),
+      )
+      .slice(0, 3),
+    completed_recently: completedRecently,
+    estimated: explicitTasks.length === 0,
+    source: explicitTasks.length > 0 ? 'explicit' : 'derived',
+    last_updated_at: maxTimestamp([
+      input.feature.last_meaningful_change_at,
+      input.feature.last_updated,
+      input.gateEvidence?.finished_at,
+      input.checkpoints[0]?.timestamp,
+    ]),
+  };
+}
+
+function gateStatusItem(
+  feature: FeatureSummary,
+  gateEvidence: GateRunEvidence | null | undefined,
+): FeatureVerificationItem {
+  const gateStatus = feature.gates?.merge ?? gateEvidence?.overall ?? 'unknown';
+  const failedStep = gateEvidence?.steps.find((step) => step.status === 'fail');
+  if (gateStatus === 'pass') {
+    return {
+      id: 'merge-gate',
+      label: 'Merge gate evidence',
+      status: 'verified',
+      source: 'gate',
+      detail: 'Latest merge validation passed.',
+      artifact_ref: 'latest-merge.json',
+      last_evidence_at: gateEvidence?.finished_at ?? feature.last_updated ?? null,
+    };
+  }
+  if (gateStatus === 'fail') {
+    return {
+      id: 'merge-gate',
+      label: 'Merge gate evidence',
+      status: 'at_risk',
+      source: 'gate',
+      detail:
+        failedStep?.output_tail?.at(-1) ??
+        `Latest merge validation failed${failedStep?.name ? ` at ${failedStep.name}` : ''}.`,
+      artifact_ref: 'latest-merge.json',
+      last_evidence_at: gateEvidence?.finished_at ?? feature.last_updated ?? null,
+    };
+  }
+  return {
+    id: 'merge-gate',
+    label: 'Merge gate evidence',
+    status: 'unverified',
+    source: 'gate',
+    detail: 'No evidence recorded for the merge gate yet.',
+    artifact_ref: 'latest-merge.json',
+    last_evidence_at: gateEvidence?.finished_at ?? null,
+  };
+}
+
+function qaCoverageItem(qaTestIndex: QaTestIndex | null | undefined): FeatureVerificationItem {
+  const items = qaTestIndex?.items ?? [];
+  const lastRunAt = maxTimestamp(items.map((item) => item.last_run_at));
+  if (items.length === 0) {
+    return {
+      id: 'qa-coverage',
+      label: 'QA coverage',
+      status: 'unverified',
+      source: 'qa',
+      detail: 'No QA coverage index or test evidence is recorded yet.',
+      artifact_ref: 'qa_test_index.json',
+      last_evidence_at: null,
+    };
+  }
+  const failingCount = items.filter((item) => item.status === 'failed').length;
+  const pendingCount = items.filter(
+    (item) => item.status === 'pending' || item.status === 'running',
+  ).length;
+  if (failingCount > 0) {
+    return {
+      id: 'qa-coverage',
+      label: 'QA coverage',
+      status: 'at_risk',
+      source: 'qa',
+      detail: `${failingCount} file(s) still have failing test evidence.`,
+      artifact_ref: 'qa_test_index.json',
+      last_evidence_at: lastRunAt,
+    };
+  }
+  if (pendingCount > 0) {
+    return {
+      id: 'qa-coverage',
+      label: 'QA coverage',
+      status: 'unverified',
+      source: 'qa',
+      detail: `${pendingCount} file(s) still need fresh test evidence.`,
+      artifact_ref: 'qa_test_index.json',
+      last_evidence_at: lastRunAt,
+    };
+  }
+  return {
+    id: 'qa-coverage',
+    label: 'QA coverage',
+    status: 'verified',
+    source: 'qa',
+    detail: 'All mapped QA obligations have passing or waived evidence.',
+    artifact_ref: 'qa_test_index.json',
+    last_evidence_at: lastRunAt,
+  };
+}
+
+function reviewReadinessItem(feature: FeatureSummary): FeatureVerificationItem {
+  const pendingThreads = feature.pr?.pending_review_threads ?? 0;
+  if (feature.pr?.has_conflicts === true) {
+    return {
+      id: 'review-readiness',
+      label: 'Review readiness',
+      status: 'at_risk',
+      source: 'review',
+      detail: 'Merge conflicts are still open on the PR.',
+      artifact_ref: feature.pr?.url ?? null,
+      last_evidence_at: feature.last_updated ?? null,
+    };
+  }
+  if (pendingThreads > 0) {
+    return {
+      id: 'review-readiness',
+      label: 'Review readiness',
+      status: 'at_risk',
+      source: 'review',
+      detail: `${pendingThreads} review thread(s) still need resolution.`,
+      artifact_ref: feature.pr?.url ?? null,
+      last_evidence_at: feature.last_updated ?? null,
+    };
+  }
+  if (feature.pr?.merge_ready === true || feature.phase === 'merged') {
+    return {
+      id: 'review-readiness',
+      label: 'Review readiness',
+      status: 'verified',
+      source: 'review',
+      detail:
+        feature.phase === 'merged'
+          ? 'Feature already merged.'
+          : 'Review and merge state are clear.',
+      artifact_ref: feature.pr?.url ?? null,
+      last_evidence_at: feature.last_updated ?? null,
+    };
+  }
+  return {
+    id: 'review-readiness',
+    label: 'Review readiness',
+    status: 'unverified',
+    source: 'review',
+    detail: 'No clear review or PR readiness evidence is recorded yet.',
+    artifact_ref: feature.pr?.url ?? null,
+    last_evidence_at: feature.last_updated ?? null,
+  };
+}
+
+function budgetItem(
+  usageBurn: UsageBurnProjection | null | undefined,
+): FeatureVerificationItem | null {
+  if (!usageBurn) {
+    return null;
+  }
+  if (usageBurn.will_exceed_budget) {
+    return {
+      id: 'budget',
+      label: 'Usage budget',
+      status: 'at_risk',
+      source: 'budget',
+      detail: 'Projected token burn exceeds the configured budget.',
+      artifact_ref: null,
+      last_evidence_at: usageBurn.last_updated_at,
+    };
+  }
+  return {
+    id: 'budget',
+    label: 'Usage budget',
+    status: usageBurn.current_tokens_used > 0 ? 'verified' : 'unverified',
+    source: 'budget',
+    detail:
+      usageBurn.current_tokens_used > 0
+        ? 'Current token burn is within the projected budget.'
+        : 'No token usage evidence is recorded yet.',
+    artifact_ref: null,
+    last_evidence_at: usageBurn.last_updated_at,
+  };
+}
+
+function itemToBlocker(item: FeatureVerificationItem): FeatureVerificationBlocker | null {
+  if (item.status !== 'at_risk') {
+    return null;
+  }
+  return {
+    id: item.id,
+    label: item.label,
+    severity:
+      item.source === 'gate' || item.source === 'review'
+        ? 'high'
+        : item.source === 'qa' || item.source === 'budget'
+          ? 'medium'
+          : 'low',
+    source: item.source,
+    detail: item.detail,
+    artifact_ref: item.artifact_ref ?? null,
+  };
+}
+
+export function buildVerificationSummary(input: {
+  feature: FeatureSummary;
+  gateEvidence?: GateRunEvidence | null;
+  qaTestIndex?: QaTestIndex | null;
+  usageBurn?: UsageBurnProjection | null;
+}): FeatureVerificationSummary {
+  const items = [
+    gateStatusItem(input.feature, input.gateEvidence),
+    qaCoverageItem(input.qaTestIndex),
+    reviewReadinessItem(input.feature),
+    budgetItem(input.usageBurn),
+  ].filter((item): item is FeatureVerificationItem => item != null);
+
+  const blockers = items
+    .map((item) => itemToBlocker(item))
+    .filter((item): item is FeatureVerificationBlocker => item != null);
+
+  if (input.feature.activity_state === 'waiting_input') {
+    blockers.unshift({
+      id: 'waiting-input',
+      label: 'Awaiting human input',
+      severity: 'high',
+      source: 'runtime',
+      detail:
+        input.feature.status_reason ??
+        'The feature is paused until an operator answers the outstanding question.',
+      artifact_ref: null,
+    });
+  }
+
+  let readiness: FeatureVerificationSummary['readiness'] = 'unknown';
+  const mergeItem = items.find((item) => item.id === 'merge-gate');
+  const qaItem = items.find((item) => item.id === 'qa-coverage');
+  const reviewItem = items.find((item) => item.id === 'review-readiness');
+  if (input.feature.phase === 'merged') {
+    readiness = 'ready';
+  } else if (
+    input.feature.phase === 'blocked' ||
+    input.feature.activity_state === 'waiting_input'
+  ) {
+    readiness = 'blocked';
+  } else if (blockers.length > 0) {
+    readiness = 'at_risk';
+  } else if (
+    mergeItem?.status === 'verified' &&
+    qaItem?.status !== 'at_risk' &&
+    reviewItem?.status !== 'at_risk'
+  ) {
+    readiness = 'ready';
+  }
+
+  return {
+    last_evaluated_at: maxTimestamp([
+      ...items.map((item) => item.last_evidence_at),
+      input.feature.last_updated,
+      input.feature.last_meaningful_change_at,
+    ]),
+    readiness,
+    blockers,
+    verified_requirements: items.filter((item) => item.status === 'verified').length,
+    at_risk_requirements: items.filter((item) => item.status === 'at_risk').length,
+    unverified_requirements: items.filter((item) => item.status === 'unverified').length,
+    items,
+  };
+}
+
+function summarizeCheckpointEvent(checkpoint: FeatureCheckpoint): RevisionSummaryEntry {
+  return {
+    id: checkpoint.checkpoint_id,
+    timestamp: checkpoint.timestamp,
+    type: 'checkpoint',
+    headline: `${checkpoint.checkpoint_id} touched ${checkpoint.files_changed.length} file(s)`,
+    detail:
+      checkpoint.violations[0] ??
+      (checkpoint.files_changed.length > 0
+        ? checkpoint.files_changed.slice(0, 3).join(', ')
+        : 'No file changes recorded.'),
+    file_count: checkpoint.files_changed.length,
+    artifacts: [checkpoint.checkpoint_id],
+    jump_to: 'changes',
+  };
+}
+
+function summarizeGateEvent(entry: GateHistoryEntry): RevisionSummaryEntry {
+  const failedSteps = entry.steps.filter((step) => step.status === 'fail').map((step) => step.name);
+  return {
+    id: entry.id,
+    timestamp: entry.finished_at,
+    type: 'gate_run',
+    headline: `${entry.mode} gate ${entry.overall}`,
+    detail:
+      failedSteps.length > 0
+        ? `Failed step(s): ${failedSteps.join(', ')}.`
+        : `${entry.step_count} step(s) evaluated.`,
+    file_count: null,
+    artifacts: [entry.file],
+    jump_to: 'gates_qa',
+  };
+}
+
+function summarizePlanEvent(
+  feature: FeatureSummary,
+  plan: Record<string, unknown> | null,
+): RevisionSummaryEntry | null {
+  if (!plan && feature.plan_version == null) {
+    return null;
+  }
+  const planVersion =
+    typeof plan?.plan_version === 'number'
+      ? plan.plan_version
+      : typeof plan?.plan_version === 'string'
+        ? Number.parseInt(plan.plan_version, 10)
+        : (feature.plan_version ?? null);
+  if (planVersion == null || Number.isNaN(planVersion)) {
+    return null;
+  }
+  const fileCount =
+    (Array.isArray(asRecord(plan?.files)?.create)
+      ? (asRecord(plan?.files)?.create as unknown[]).length
+      : 0) +
+    (Array.isArray(asRecord(plan?.files)?.modify)
+      ? (asRecord(plan?.files)?.modify as unknown[]).length
+      : 0) +
+    (Array.isArray(asRecord(plan?.files)?.delete)
+      ? (asRecord(plan?.files)?.delete as unknown[]).length
+      : 0);
+  return {
+    id: `plan-v${planVersion}`,
+    timestamp: maxTimestamp([
+      typeof plan?.updated_at === 'string' ? plan.updated_at : null,
+      typeof plan?.accepted_at === 'string' ? plan.accepted_at : null,
+      typeof plan?.created_at === 'string' ? plan.created_at : null,
+      feature.last_meaningful_change_at,
+    ]),
+    type: 'plan_update',
+    headline: feature.revision_reason
+      ? `Plan v${planVersion} revised after ${feature.revision_reason}`
+      : feature.revision_of && feature.revision_of < planVersion
+        ? `Plan v${planVersion} revised from v${feature.revision_of}`
+        : `Plan v${planVersion} accepted`,
+    detail:
+      feature.revision_reason ??
+      (typeof plan?.summary === 'string' ? plan.summary : 'Plan updated without summary details.'),
+    file_count: fileCount,
+    artifacts: [`plan:v${planVersion}`],
+    jump_to: 'planning',
+  };
+}
+
+function summarizeReviewEvent(feature: FeatureSummary): RevisionSummaryEntry | null {
+  if (feature.phase === 'merged') {
+    return {
+      id: 'merge-event',
+      timestamp: feature.last_updated ?? null,
+      type: 'merge_event',
+      headline: 'Feature merged',
+      detail: feature.status_reason ?? 'Merge completed successfully.',
+      file_count: null,
+      jump_to: 'history',
+    };
+  }
+  const reviewDecision = feature.pr?.review_decision?.trim();
+  const pendingThreads = feature.pr?.pending_review_threads ?? 0;
+  if (!reviewDecision && pendingThreads <= 0) {
+    return null;
+  }
+  return {
+    id: 'review-event',
+    timestamp: feature.last_meaningful_change_at ?? null,
+    type: 'review_event',
+    headline: reviewDecision
+      ? `Review state: ${reviewDecision}`
+      : `${pendingThreads} review thread(s) open`,
+    detail:
+      pendingThreads > 0
+        ? `${pendingThreads} review thread(s) still require a response before merge.`
+        : (feature.status_reason ?? 'Review metadata updated.'),
+    file_count: null,
+    artifacts: feature.pr?.url ? [feature.pr.url] : [],
+    jump_to: 'review',
+  };
+}
+
+export function buildRevisionSummary(input: {
+  feature: FeatureSummary;
+  plan: Record<string, unknown> | null;
+  checkpoints: FeatureCheckpoint[];
+  gateHistory: GateHistoryEntry[];
+}): RevisionSummaryEntry[] {
+  const events: RevisionSummaryEntry[] = [];
+  const planEvent = summarizePlanEvent(input.feature, input.plan);
+  if (planEvent) {
+    events.push(planEvent);
+  }
+  const reviewEvent = summarizeReviewEvent(input.feature);
+  if (reviewEvent) {
+    events.push(reviewEvent);
+  }
+  events.push(
+    ...input.checkpoints.slice(0, 3).map((checkpoint) => summarizeCheckpointEvent(checkpoint)),
+  );
+  events.push(...input.gateHistory.slice(0, 3).map((entry) => summarizeGateEvent(entry)));
+
+  return events
+    .sort((left, right) => {
+      const leftMs = Date.parse(left.timestamp ?? '');
+      const rightMs = Date.parse(right.timestamp ?? '');
+      return (Number.isNaN(rightMs) ? 0 : rightMs) - (Number.isNaN(leftMs) ? 0 : leftMs);
+    })
+    .slice(0, 5);
+}
+
+function inferRiskSeverity(statement: string): ActionableRiskItem['severity'] {
+  const normalized = statement.toLowerCase();
+  if (
+    normalized.includes('merge') ||
+    normalized.includes('fail') ||
+    normalized.includes('block') ||
+    normalized.includes('conflict')
+  ) {
+    return 'high';
+  }
+  if (
+    normalized.includes('budget') ||
+    normalized.includes('coverage') ||
+    normalized.includes('retry') ||
+    normalized.includes('stale')
+  ) {
+    return 'medium';
+  }
+  return 'low';
+}
+
+function inferRiskOwner(statement: string): ActionableRiskItem['owner_role'] {
+  const normalized = statement.toLowerCase();
+  if (normalized.includes('review') || normalized.includes('merge')) {
+    return 'orchestrator';
+  }
+  if (
+    normalized.includes('test') ||
+    normalized.includes('gate') ||
+    normalized.includes('coverage')
+  ) {
+    return 'qa';
+  }
+  if (normalized.includes('plan')) {
+    return 'planner';
+  }
+  return 'builder';
+}
+
+export function buildActionableRisks(
+  plan: Record<string, unknown> | null,
+  feature: FeatureSummary,
+): ActionableRiskItem[] {
+  const risks = asStringArray(plan?.risk);
+  return risks.slice(0, 6).map((statement, index) => {
+    const severity = inferRiskSeverity(statement);
+    return {
+      id: `risk-${index + 1}`,
+      severity,
+      statement,
+      impact:
+        severity === 'high'
+          ? 'This can block merge or invalidate confidence in the feature.'
+          : severity === 'medium'
+            ? 'This can delay verification or reduce confidence.'
+            : 'This should be monitored but is unlikely to block merge directly.',
+      mitigation:
+        severity === 'high'
+          ? 'Investigate the blocker now and record fresh evidence before continuing.'
+          : severity === 'medium'
+            ? 'Plan a focused follow-up and rerun the affected verification path.'
+            : 'Keep this risk visible and confirm it does not escalate in later gates.',
+      owner_role: inferRiskOwner(statement),
+      freshness: feature.last_meaningful_change_at ? 'fresh' : 'derived',
+      derived: true,
+    };
+  });
+}
+
+export function resolveFeatureSpecTitle(markdown: string): string | null {
+  const line = markdown
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .find((entry) => entry.trim().startsWith('#'));
+  if (!line) {
+    return null;
+  }
+  return line.replace(/^#+\s*/, '').trim() || null;
+}
+
+export function summarizeFeatureSpec(
+  pathValue: string,
+  markdown: string | null,
+  lastUpdated: string | null,
+): FeatureSpecSummary {
+  return {
+    title: markdown ? resolveFeatureSpecTitle(markdown) : null,
+    path: pathValue,
+    markdown,
+    last_updated: lastUpdated,
+  };
+}
+
+export function resolveActiveRole(
+  detail: Pick<FeatureDetail, 'feature' | 'worker_summary' | 'live_output_snapshots'> | null,
+): RoleName | null {
+  if (!detail) {
+    return null;
+  }
+  const runningSnapshotRole = [...(detail.live_output_snapshots ?? [])]
+    .filter((snapshot) => snapshot.status === 'running' && isTrackedRole(snapshot.role))
+    .sort(
+      (left, right) => snapshotActivityTimestamp(right) - snapshotActivityTimestamp(left),
+    )[0]?.role;
+  if (runningSnapshotRole) {
+    return runningSnapshotRole;
+  }
+  const recoveryRole =
+    detail.feature.recovery?.state === 'retrying' ? detail.feature.recovery.role : null;
+  if (isTrackedRole(recoveryRole)) {
+    return recoveryRole;
+  }
+  const phaseRole = resolveExecutionRoleForPhase(detail.feature.phase);
+  if (phaseRole) {
+    return phaseRole;
+  }
+  const latestEventRole = detail.worker_summary?.entries?.[0]?.role;
+  if (isTrackedRole(latestEventRole)) {
+    return latestEventRole;
+  }
+  const roleStatus = detail.feature.role_status;
+  if (!roleStatus) {
+    return null;
+  }
+  const roleStatusMap = roleStatus as unknown as Record<string, string>;
+  for (const status of ROLE_STATUS_PRIORITY) {
+    for (const role of ROLE_ORDER) {
+      if (role === 'orchestrator') {
+        continue;
+      }
+      if (roleStatusMap[role] === status) {
+        return role;
+      }
+    }
+  }
+  return null;
+}
+
+export function resolveRecommendedAction(
+  detail: Pick<FeatureDetail, 'feature' | 'verification_summary' | 'plan_progress'> | null,
+): string {
+  if (!detail) {
+    return 'Wait for feature detail to load.';
+  }
+  if (detail.feature.activity_state === 'waiting_input') {
+    return 'Answer the pending human-input request.';
+  }
+  if (detail.feature.phase === 'ready_to_merge') {
+    return 'Review the final evidence and make the merge decision.';
+  }
+  if (detail.feature.phase === 'merged') {
+    return 'No operator action is required.';
+  }
+  if (detail.feature.recovery?.state === 'retrying') {
+    const role = detail.feature.recovery.role?.trim();
+    return role
+      ? `Resume the ${role} workflow to continue recovery.`
+      : 'Resume the feature to continue recovery.';
+  }
+  if (detail.feature.phase === 'blocked') {
+    return 'Investigate the blocking condition before continuing execution.';
+  }
+  const blocker = detail.verification_summary?.blockers[0];
+  if (blocker) {
+    return blocker.source === 'review'
+      ? 'Resolve the open review blocker and refresh merge readiness.'
+      : blocker.source === 'gate'
+        ? 'Inspect the failing verification evidence and rerun the blocked gate.'
+        : blocker.detail;
+  }
+  const currentTask = detail.plan_progress?.current_task;
+  if (currentTask?.status === 'in_progress') {
+    return `Continue ${currentTask.title.toLowerCase()}.`;
+  }
+  return 'Monitor progress and open the active work tab for more detail.';
+}