agentic-orchestrator 0.1.28 → 0.2.0

package/packages/web-dashboard/src/lib/planner-workspace.ts

@@ -0,0 +1,1285 @@
+import type {
+  FeatureIntakeReviewSummary,
+  FeatureIntakeSummary,
+  FeatureIntakeWorkspace,
+  FeaturePlanningWorkspace,
+  FeatureQuestion,
+  FeatureSummary,
+  ManifestArtifactSummary,
+  PlannerArtifactView,
+  PlannerLifecycleSummary,
+  PlanLifecycleStep,
+  PlanProgressTaskSummary,
+} from '@/lib/types.js';
+
+type ManifestConfidence = 'high' | 'medium' | 'low';
+
+interface ManifestObligation {
+  obligation_id: string;
+  confidence: ManifestConfidence;
+  verification_hint?: string;
+}
+
+interface IntakeAmbiguityRecord {
+  id: string;
+  summary: string;
+  status: 'open' | 'resolved';
+  obligation_ids: string[];
+}
+
+interface BootstrapManifestRecord {
+  manifest_version: number | null;
+  generated_at: string | null;
+  obligations: ManifestObligation[];
+  ambiguities: IntakeAmbiguityRecord[];
+}
+
+interface VerifiedManifestRecord {
+  manifest_version: number | null;
+  verified_at: string | null;
+  verification_basis: string | null;
+  obligations: ManifestObligation[];
+}
+
+interface IntakeReviewRecord {
+  version: number | null;
+  status: string | null;
+  questions_open: number;
+  questions_resolved: number;
+  ambiguities: IntakeAmbiguityRecord[];
+  bootstrap_manifest_version: number | null;
+  verified_manifest_version: number | null;
+  promotion_basis: string | null;
+  last_updated_at: string | null;
+}
+
+interface PlanTraceEntry {
+  obligation_id: string;
+  disposition: 'in_scope' | 'deferred' | 'out_of_scope' | string;
+  planned_paths: string[];
+  planned_test_paths: string[];
+  planned_verification: string[];
+  notes: string;
+}
+
+interface AcceptedPlanRecord {
+  plan_version: number | null;
+  summary: string | null;
+  gate_profile: string | null;
+  accepted_at: string | null;
+  updated_at: string | null;
+  created_at: string | null;
+  source_verified_manifest_version: number | null;
+  source_verified_at: string | null;
+  tasks: PlanProgressTaskSummary[];
+  files: {
+    create: string[];
+    modify: string[];
+    delete: string[];
+  };
+  acceptance_criteria: string[];
+  risks: string[];
+  owners: string[];
+  plan_trace: PlanTraceEntry[];
+}
+
+interface BuildIntakeWorkspaceInput {
+  feature: FeatureSummary;
+  intakeSummary: FeatureIntakeSummary | null;
+  intakeReviewSummary: FeatureIntakeReviewSummary | null;
+  bootstrapManifest: BootstrapManifestRecord | null;
+  verifiedManifest: VerifiedManifestRecord | null;
+  intakeReview: IntakeReviewRecord | null;
+  questions: FeatureQuestion[];
+  artifacts: PlannerArtifactView[];
+}
+
+interface BuildPlanningWorkspaceInput {
+  feature: FeatureSummary;
+  intakeSummary: FeatureIntakeSummary | null;
+  verifiedManifest: VerifiedManifestRecord | null;
+  acceptedPlan: AcceptedPlanRecord | null;
+  plannerQuestions: FeatureQuestion[];
+  artifacts: PlannerArtifactView[];
+}
+
+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 asWholeNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? Math.trunc(value) : null;
+}
+
+function maxTimestamp(values: Array<string | null | undefined>): string | null {
+  let latest: string | null = null;
+  let latestMs = Number.NEGATIVE_INFINITY;
+  for (const value of values) {
+    if (typeof value !== 'string') {
+      continue;
+    }
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed) || parsed < latestMs) {
+      continue;
+    }
+    latestMs = parsed;
+    latest = value;
+  }
+  return latest;
+}
+
+function countConfidence(obligations: ManifestObligation[]): ManifestArtifactSummary['confidence'] {
+  return obligations.reduce(
+    (counts, obligation) => {
+      if (obligation.confidence === 'high') {
+        counts.high += 1;
+      } else if (obligation.confidence === 'medium') {
+        counts.medium += 1;
+      } else if (obligation.confidence === 'low') {
+        counts.low += 1;
+      }
+      return counts;
+    },
+    {
+      high: 0,
+      medium: 0,
+      low: 0,
+    },
+  );
+}
+
+function confidenceRank(value: ManifestConfidence): number {
+  if (value === 'high') {
+    return 3;
+  }
+  if (value === 'medium') {
+    return 2;
+  }
+  return 1;
+}
+
+function roleFromFeature(
+  feature: FeatureSummary,
+  currentSubphase: PlannerLifecycleSummary['current_subphase'],
+  stale: boolean,
+  hasBlockingQuestion: boolean,
+): PlannerLifecycleSummary['current_owner'] {
+  if (hasBlockingQuestion || feature.activity_state === 'waiting_input') {
+    return 'operator';
+  }
+  if (currentSubphase === 'post_planning' && !stale) {
+    return 'system';
+  }
+  return 'planner';
+}
+
+function parseObligations(value: unknown): ManifestObligation[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((entry) => {
+      const record = asRecord(entry);
+      if (!record || typeof record.obligation_id !== 'string') {
+        return null;
+      }
+      const confidence =
+        record.confidence === 'high' ||
+        record.confidence === 'medium' ||
+        record.confidence === 'low'
+          ? record.confidence
+          : 'medium';
+      return {
+        obligation_id: record.obligation_id,
+        confidence,
+        verification_hint:
+          typeof record.verification_hint === 'string' ? record.verification_hint : undefined,
+      } satisfies ManifestObligation;
+    })
+    .filter((entry) => entry !== null) as ManifestObligation[];
+}
+
+function parseAmbiguities(value: unknown): IntakeAmbiguityRecord[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((entry) => {
+      const record = asRecord(entry);
+      if (!record || typeof record.id !== 'string' || typeof record.summary !== 'string') {
+        return null;
+      }
+      return {
+        id: record.id,
+        summary: record.summary,
+        status: record.status === 'resolved' ? 'resolved' : 'open',
+        obligation_ids: asStringArray(record.obligation_ids),
+      } satisfies IntakeAmbiguityRecord;
+    })
+    .filter((entry): entry is IntakeAmbiguityRecord => entry !== null);
+}
+
+export function normalizeBootstrapManifestRecord(value: unknown): BootstrapManifestRecord | null {
+  const record = asRecord(value);
+  if (!record) {
+    return null;
+  }
+  return {
+    manifest_version: asWholeNumber(record.manifest_version),
+    generated_at: typeof record.generated_at === 'string' ? record.generated_at : null,
+    obligations: parseObligations(record.obligations),
+    ambiguities: parseAmbiguities(record.ambiguities),
+  };
+}
+
+export function normalizeVerifiedManifestRecord(value: unknown): VerifiedManifestRecord | null {
+  const record = asRecord(value);
+  if (!record) {
+    return null;
+  }
+  return {
+    manifest_version: asWholeNumber(record.manifest_version),
+    verified_at: typeof record.verified_at === 'string' ? record.verified_at : null,
+    verification_basis:
+      typeof record.verification_basis === 'string' ? record.verification_basis : null,
+    obligations: parseObligations(record.obligations),
+  };
+}
+
+export function normalizeIntakeReviewRecord(value: unknown): IntakeReviewRecord | null {
+  const record = asRecord(value);
+  if (!record) {
+    return null;
+  }
+  return {
+    version: asWholeNumber(record.version),
+    status: typeof record.status === 'string' ? record.status : null,
+    questions_open: asWholeNumber(record.questions_open) ?? 0,
+    questions_resolved: asWholeNumber(record.questions_resolved) ?? 0,
+    ambiguities: parseAmbiguities(record.ambiguities),
+    bootstrap_manifest_version: asWholeNumber(record.bootstrap_manifest_version),
+    verified_manifest_version: asWholeNumber(record.verified_manifest_version),
+    promotion_basis: typeof record.promotion_basis === 'string' ? record.promotion_basis : null,
+    last_updated_at: typeof record.last_updated_at === 'string' ? record.last_updated_at : null,
+  };
+}
+
+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): PlanProgressTaskSummary['owner_role'] {
+  return value === 'planner' || value === 'builder' || value === 'qa' || value === 'orchestrator'
+    ? value
+    : null;
+}
+
+function parsePlanTasks(value: unknown): PlanProgressTaskSummary[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((entry, index) => {
+      if (typeof entry === 'string') {
+        return {
+          id: `task-${index + 1}`,
+          title: entry,
+          status: 'pending',
+          owner_role: null,
+        } satisfies PlanProgressTaskSummary;
+      }
+      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),
+      } satisfies PlanProgressTaskSummary;
+    })
+    .filter((entry) => entry !== null) as PlanProgressTaskSummary[];
+}
+
+function parsePlanTrace(value: unknown): PlanTraceEntry[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((entry) => {
+      const record = asRecord(entry);
+      if (
+        !record ||
+        typeof record.obligation_id !== 'string' ||
+        typeof record.disposition !== 'string'
+      ) {
+        return null;
+      }
+      return {
+        obligation_id: record.obligation_id,
+        disposition: record.disposition,
+        planned_paths: asStringArray(record.planned_paths),
+        planned_test_paths: asStringArray(record.planned_test_paths),
+        planned_verification: asStringArray(record.planned_verification),
+        notes: typeof record.notes === 'string' ? record.notes : '',
+      } satisfies PlanTraceEntry;
+    })
+    .filter((entry): entry is PlanTraceEntry => entry !== null);
+}
+
+function parsePlanOwners(
+  tasks: PlanProgressTaskSummary[],
+  plan: Record<string, unknown>,
+): string[] {
+  const explicitOwners = Array.isArray(plan.owners)
+    ? plan.owners.filter((entry): entry is string => typeof entry === 'string')
+    : [];
+  const taskOwners = tasks
+    .map((task) => task.owner_role)
+    .filter((entry): entry is NonNullable<typeof entry> => typeof entry === 'string');
+  return Array.from(new Set([...explicitOwners, ...taskOwners])).sort((left, right) =>
+    left.localeCompare(right),
+  );
+}
+
+export function normalizeAcceptedPlanRecord(value: unknown): AcceptedPlanRecord | null {
+  const record = asRecord(value);
+  if (!record) {
+    return null;
+  }
+  const filesRecord = asRecord(record.files);
+  const tasks = parsePlanTasks(record.tasks);
+  return {
+    plan_version: asWholeNumber(record.plan_version),
+    summary: typeof record.summary === 'string' ? record.summary : null,
+    gate_profile: typeof record.gate_profile === 'string' ? record.gate_profile : null,
+    accepted_at: typeof record.accepted_at === 'string' ? record.accepted_at : null,
+    updated_at: typeof record.updated_at === 'string' ? record.updated_at : null,
+    created_at: typeof record.created_at === 'string' ? record.created_at : null,
+    source_verified_manifest_version: asWholeNumber(record.source_verified_manifest_version),
+    source_verified_at:
+      typeof record.source_verified_at === 'string' ? record.source_verified_at : null,
+    tasks,
+    files: {
+      create: asStringArray(filesRecord?.create),
+      modify: asStringArray(filesRecord?.modify),
+      delete: asStringArray(filesRecord?.delete),
+    },
+    acceptance_criteria: asStringArray(record.acceptance_criteria),
+    risks: asStringArray(record.risk ?? record.risks),
+    owners: parsePlanOwners(tasks, record),
+    plan_trace: parsePlanTrace(record.plan_trace),
+  };
+}
+
+function summarizeManifest(
+  record: BootstrapManifestRecord | VerifiedManifestRecord | null,
+): ManifestArtifactSummary | null {
+  if (!record) {
+    return null;
+  }
+  return {
+    version: record.manifest_version,
+    generated_at: 'generated_at' in record ? record.generated_at : record.verified_at,
+    obligation_count: record.obligations.length,
+    ambiguity_count: 'ambiguities' in record ? record.ambiguities.length : undefined,
+    verification_basis: 'verification_basis' in record ? record.verification_basis : null,
+    confidence: countConfidence(record.obligations),
+  };
+}
+
+function isIntakeQuestion(question: FeatureQuestion): boolean {
+  return (
+    question.resume_status === 'intake' ||
+    question.resume_phase === 'intake' ||
+    question.phase === 'intake'
+  );
+}
+
+function isPlanningQuestion(question: FeatureQuestion): boolean {
+  return (
+    question.resume_status === 'planning' ||
+    question.resume_phase === 'planning' ||
+    question.phase === 'planning'
+  );
+}
+
+function buildPlanFreshness(
+  feature: FeatureSummary,
+  verifiedManifest: VerifiedManifestRecord | null,
+  acceptedPlan: AcceptedPlanRecord | null,
+): FeaturePlanningWorkspace['freshness'] {
+  const currentVerifiedVersion = verifiedManifest?.manifest_version ?? null;
+  const planVerifiedVersion = acceptedPlan?.source_verified_manifest_version ?? null;
+  if (!acceptedPlan) {
+    return {
+      source_verified_manifest_version: planVerifiedVersion,
+      current_verified_manifest_version: currentVerifiedVersion,
+      stale: false,
+      reason: null,
+    };
+  }
+  if (currentVerifiedVersion == null) {
+    return {
+      source_verified_manifest_version: planVerifiedVersion,
+      current_verified_manifest_version: currentVerifiedVersion,
+      stale: false,
+      reason: null,
+    };
+  }
+  if (planVerifiedVersion != null && planVerifiedVersion !== currentVerifiedVersion) {
+    return {
+      source_verified_manifest_version: planVerifiedVersion,
+      current_verified_manifest_version: currentVerifiedVersion,
+      stale: true,
+      reason: `Plan v${acceptedPlan.plan_version ?? '?'} is still bound to verified manifest v${planVerifiedVersion}, but intake has verified v${currentVerifiedVersion}.`,
+    };
+  }
+  const acceptedAt = maxTimestamp([
+    acceptedPlan.accepted_at,
+    acceptedPlan.updated_at,
+    acceptedPlan.created_at,
+  ]);
+  const verifiedAt = maxTimestamp([
+    verifiedManifest?.verified_at ?? null,
+    feature.last_verified_at,
+  ]);
+  if (planVerifiedVersion == null && acceptedAt && verifiedAt) {
+    const acceptedAtMs = Date.parse(acceptedAt);
+    const verifiedAtMs = Date.parse(verifiedAt);
+    if (!Number.isNaN(acceptedAtMs) && !Number.isNaN(verifiedAtMs) && verifiedAtMs > acceptedAtMs) {
+      return {
+        source_verified_manifest_version: planVerifiedVersion,
+        current_verified_manifest_version: currentVerifiedVersion,
+        stale: true,
+        reason:
+          'The verified manifest was updated after the last accepted plan timestamp, so the plan needs reconciliation.',
+      };
+    }
+  }
+  return {
+    source_verified_manifest_version: planVerifiedVersion,
+    current_verified_manifest_version: currentVerifiedVersion,
+    stale: false,
+    reason:
+      currentVerifiedVersion != null
+        ? `Accepted plan is aligned with verified manifest v${currentVerifiedVersion}.`
+        : null,
+  };
+}
+
+function buildLifecycleSteps(input: {
+  feature: FeatureSummary;
+  hasSpec: boolean;
+  bootstrapManifest: BootstrapManifestRecord | null;
+  verifiedManifest: VerifiedManifestRecord | null;
+  acceptedPlan: AcceptedPlanRecord | null;
+  hasBlockingQuestion: boolean;
+  currentSubphase: PlannerLifecycleSummary['current_subphase'];
+  planIsStale: boolean;
+}): PlanLifecycleStep[] {
+  const executionActive =
+    input.feature.phase === 'building' ||
+    input.feature.phase === 'qa' ||
+    input.feature.phase === 'ready_to_merge';
+  return [
+    {
+      id: 'source_spec',
+      label: 'Source Spec',
+      status: input.hasSpec ? 'complete' : 'pending',
+      detail: input.hasSpec ? 'Original launch spec is available.' : 'No source spec was captured.',
+    },
+    {
+      id: 'bootstrap_manifest',
+      label: 'Bootstrap Manifest',
+      status: input.bootstrapManifest
+        ? input.verifiedManifest
+          ? 'complete'
+          : input.currentSubphase === 'intake'
+            ? 'current'
+            : 'complete'
+        : input.currentSubphase === 'intake'
+          ? 'current'
+          : 'pending',
+      detail: input.bootstrapManifest
+        ? `Bootstrap manifest v${input.bootstrapManifest.manifest_version ?? '?'} normalized the source spec.`
+        : 'Bootstrap manifest has not been generated yet.',
+    },
+    {
+      id: 'verified_manifest',
+      label: 'Verified Manifest',
+      status: input.verifiedManifest
+        ? 'complete'
+        : input.hasBlockingQuestion
+          ? 'blocked'
+          : input.currentSubphase === 'intake'
+            ? 'current'
+            : 'pending',
+      detail: input.verifiedManifest
+        ? `Verified manifest v${input.verifiedManifest.manifest_version ?? '?'} is the requirements contract of record.`
+        : input.hasBlockingQuestion
+          ? 'Operator clarification is still required before intake can verify the contract.'
+          : 'Requirements verification is still in progress.',
+    },
+    {
+      id: 'accepted_plan',
+      label: 'Accepted Plan',
+      status: input.acceptedPlan
+        ? input.planIsStale
+          ? 'blocked'
+          : input.currentSubphase === 'planning'
+            ? 'current'
+            : 'complete'
+        : input.verifiedManifest
+          ? input.currentSubphase === 'planning'
+            ? 'current'
+            : 'pending'
+          : 'pending',
+      detail: input.acceptedPlan
+        ? input.planIsStale
+          ? 'Accepted plan exists but must be reconciled to the current verified manifest.'
+          : `Accepted plan v${input.acceptedPlan.plan_version ?? '?'} is available.`
+        : input.verifiedManifest
+          ? 'Planning can now turn the verified contract into an accepted execution plan.'
+          : 'Planning cannot begin until intake verifies the requirements contract.',
+    },
+    {
+      id: 'execution',
+      label: 'Execution',
+      status:
+        input.feature.phase === 'merged'
+          ? 'complete'
+          : executionActive
+            ? 'current'
+            : input.currentSubphase === 'post_planning'
+              ? 'current'
+              : 'pending',
+      detail:
+        input.feature.phase === 'merged'
+          ? 'Feature has already merged.'
+          : executionActive
+            ? `Execution is active in ${input.feature.phase}.`
+            : 'Execution begins after the accepted plan is ready.',
+    },
+  ];
+}
+
+function buildPlanningTaskFallback(
+  status: FeaturePlanningWorkspace['status'],
+  verifiedManifest: VerifiedManifestRecord | null,
+  freshness: FeaturePlanningWorkspace['freshness'],
+): PlanProgressTaskSummary[] {
+  if (!verifiedManifest) {
+    return [
+      {
+        id: 'await-verified-manifest',
+        title: 'Finish intake verification so planning can begin',
+        status: status === 'blocked' ? 'blocked' : 'pending',
+        owner_role: 'planner',
+      },
+    ];
+  }
+  if (freshness.stale) {
+    return [
+      {
+        id: 'reconcile-plan',
+        title: 'Reconcile the accepted plan to the current verified manifest',
+        status: 'blocked',
+        owner_role: 'planner',
+      },
+      {
+        id: 'repair-trace',
+        title: 'Repair plan trace coverage for the changed obligations',
+        status: 'pending',
+        owner_role: 'planner',
+      },
+    ];
+  }
+  return [
+    {
+      id: 'scope-implementation',
+      title: 'Map verified obligations into scoped implementation work',
+      status: status === 'in_progress' ? 'in_progress' : 'pending',
+      owner_role: 'planner',
+    },
+    {
+      id: 'bind-verification',
+      title: 'Attach explicit planned verification to the scoped work',
+      status: 'pending',
+      owner_role: 'planner',
+    },
+    {
+      id: 'submit-plan',
+      title: 'Submit the accepted execution plan',
+      status: 'pending',
+      owner_role: 'planner',
+    },
+  ];
+}
+
+export function buildPlannerLifecycleSummary(input: {
+  feature: FeatureSummary;
+  intakeSummary: FeatureIntakeSummary | null;
+  hasSpec: boolean;
+  bootstrapManifest: BootstrapManifestRecord | null;
+  verifiedManifest: VerifiedManifestRecord | null;
+  acceptedPlan: AcceptedPlanRecord | null;
+  questions: FeatureQuestion[];
+}): PlannerLifecycleSummary {
+  const intakeQuestions = input.questions.filter(
+    (question) => question.status === 'open' && question.blocking && isIntakeQuestion(question),
+  );
+  const planningQuestions = input.questions.filter(
+    (question) => question.status === 'open' && question.blocking && isPlanningQuestion(question),
+  );
+  const hasBlockingIntakeQuestion = intakeQuestions.length > 0;
+  const hasBlockingPlanningQuestion = planningQuestions.length > 0;
+  const currentSubphase =
+    input.feature.phase === 'planning' ||
+    (input.feature.phase === 'awaiting_input' && input.feature.resume_status === 'planning')
+      ? 'planning'
+      : input.feature.phase === 'building' ||
+          input.feature.phase === 'qa' ||
+          input.feature.phase === 'ready_to_merge' ||
+          input.feature.phase === 'merged'
+        ? 'post_planning'
+        : 'intake';
+  const freshness = buildPlanFreshness(input.feature, input.verifiedManifest, input.acceptedPlan);
+  const currentOwner = roleFromFeature(
+    input.feature,
+    currentSubphase,
+    freshness.stale,
+    currentSubphase === 'intake' ? hasBlockingIntakeQuestion : hasBlockingPlanningQuestion,
+  );
+
+  let bannerState: PlannerLifecycleSummary['banner_state'];
+  let primaryDetail: string;
+  let nextAction: string;
+
+  if (currentSubphase === 'intake') {
+    if (hasBlockingIntakeQuestion || input.intakeSummary?.status === 'awaiting_input') {
+      bannerState = 'waiting_on_intake_clarification';
+      primaryDetail =
+        'Intake cannot verify the requirements contract until the open clarification is answered.';
+      nextAction = 'Answer the blocking intake question so the verified manifest can be promoted.';
+    } else if (input.verifiedManifest) {
+      bannerState = 'ready_for_execution_planning';
+      primaryDetail = `Verified manifest v${input.verifiedManifest.manifest_version ?? '?'} is ready for execution planning.`;
+      nextAction = 'Review the planning workspace and submit the accepted execution plan.';
+    } else {
+      bannerState = 'intake_in_progress';
+      primaryDetail =
+        'Planner intake is normalizing the source spec into a verified requirements contract.';
+      nextAction = 'Resolve remaining ambiguities and verify the manifest contract.';
+    }
+  } else if (currentSubphase === 'planning') {
+    if (freshness.stale) {
+      bannerState = 'accepted_plan_stale';
+      primaryDetail =
+        freshness.reason ?? 'The accepted plan is stale against the verified manifest.';
+      nextAction = 'Reconcile the accepted plan and plan trace to the current verified manifest.';
+    } else if (input.acceptedPlan && input.feature.activity_state !== 'active') {
+      bannerState = 'accepted_plan_current';
+      primaryDetail = 'An accepted plan exists and is ready to drive execution.';
+      nextAction = 'Promote or resume execution against the accepted plan.';
+    } else {
+      bannerState = 'execution_planning_in_progress';
+      primaryDetail = input.acceptedPlan
+        ? 'Execution planning is still active while the planner refines the accepted plan.'
+        : 'Execution planning is turning the verified requirements into an accepted plan.';
+      nextAction = input.acceptedPlan
+        ? 'Finish the outstanding planning tasks and confirm the accepted plan is current.'
+        : 'Submit the first accepted execution plan bound to the verified manifest.';
+    }
+  } else if (freshness.stale) {
+    bannerState = 'accepted_plan_stale';
+    primaryDetail = freshness.reason ?? 'Execution is operating against a stale plan baseline.';
+    nextAction = 'Reconcile the accepted plan before trusting downstream execution decisions.';
+  } else {
+    bannerState = 'accepted_plan_current';
+    primaryDetail = 'Execution is operating against the current accepted plan.';
+    nextAction = 'Use the accepted plan as the contract of record for execution and review.';
+  }
+
+  return {
+    current_subphase: currentSubphase,
+    current_owner: currentOwner,
+    last_updated_at: maxTimestamp([
+      input.feature.last_meaningful_change_at,
+      input.feature.last_updated,
+      input.feature.phase_entered_at,
+      input.intakeSummary?.last_verified_at,
+      input.verifiedManifest?.verified_at,
+      input.acceptedPlan?.accepted_at,
+      input.acceptedPlan?.updated_at,
+    ]),
+    banner_state: bannerState,
+    lifecycle_steps: buildLifecycleSteps({
+      feature: input.feature,
+      hasSpec: input.hasSpec,
+      bootstrapManifest: input.bootstrapManifest,
+      verifiedManifest: input.verifiedManifest,
+      acceptedPlan: input.acceptedPlan,
+      hasBlockingQuestion:
+        currentSubphase === 'intake' ? hasBlockingIntakeQuestion : hasBlockingPlanningQuestion,
+      currentSubphase,
+      planIsStale: freshness.stale,
+    }),
+    next_action: nextAction,
+    primary_detail: primaryDetail,
+  };
+}
+
+function buildManifestDelta(
+  bootstrapManifest: BootstrapManifestRecord | null,
+  verifiedManifest: VerifiedManifestRecord | null,
+  intakeReview: IntakeReviewRecord | null,
+): FeatureIntakeWorkspace['manifest_delta'] {
+  const bootstrapIds = new Set(
+    (bootstrapManifest?.obligations ?? []).map((obligation) => obligation.obligation_id),
+  );
+  const verifiedIds = new Set(
+    (verifiedManifest?.obligations ?? []).map((obligation) => obligation.obligation_id),
+  );
+  const bootstrapById = new Map(
+    (bootstrapManifest?.obligations ?? []).map((obligation) => [
+      obligation.obligation_id,
+      obligation,
+    ]),
+  );
+  let confidenceUpgrades = 0;
+  let confidenceDowngrades = 0;
+  for (const obligation of verifiedManifest?.obligations ?? []) {
+    const prior = bootstrapById.get(obligation.obligation_id);
+    if (!prior) {
+      continue;
+    }
+    const before = confidenceRank(prior.confidence);
+    const after = confidenceRank(obligation.confidence);
+    if (after > before) {
+      confidenceUpgrades += 1;
+    } else if (after < before) {
+      confidenceDowngrades += 1;
+    }
+  }
+
+  return {
+    ambiguities_resolved: (intakeReview?.ambiguities ?? []).filter(
+      (ambiguity) => ambiguity.status === 'resolved',
+    ).length,
+    ambiguities_open: (intakeReview?.ambiguities ?? []).filter(
+      (ambiguity) => ambiguity.status === 'open',
+    ).length,
+    obligations_added: [...verifiedIds].filter((obligationId) => !bootstrapIds.has(obligationId))
+      .length,
+    obligations_removed: [...bootstrapIds].filter((obligationId) => !verifiedIds.has(obligationId))
+      .length,
+    confidence_upgrades: confidenceUpgrades,
+    confidence_downgrades: confidenceDowngrades,
+  };
+}
+
+function buildPromotionReadiness(input: {
+  intakeSummary: FeatureIntakeSummary | null;
+  verifiedManifest: VerifiedManifestRecord | null;
+  openQuestions: FeatureQuestion[];
+  openAmbiguities: IntakeAmbiguityRecord[];
+}): FeatureIntakeWorkspace['promotion_readiness'] {
+  const blockerReasons: string[] = [];
+  if (!input.verifiedManifest) {
+    blockerReasons.push('Verified manifest has not been promoted yet.');
+  }
+  if (input.openQuestions.length > 0) {
+    blockerReasons.push(
+      `${input.openQuestions.length} open intake question${input.openQuestions.length === 1 ? ' remains' : 's remain'}.`,
+    );
+  }
+  if (input.openAmbiguities.length > 0) {
+    blockerReasons.push(
+      `${input.openAmbiguities.length} ambiguity${input.openAmbiguities.length === 1 ? ' is' : 'ies are'} still unresolved.`,
+    );
+  }
+  if (input.intakeSummary?.status && input.intakeSummary.status !== 'verified') {
+    blockerReasons.push(`Intake status is ${input.intakeSummary.status.replace(/_/g, ' ')}.`);
+  }
+  return {
+    ready: blockerReasons.length === 0,
+    blocker_reasons: blockerReasons,
+    verified_manifest_exists: input.verifiedManifest != null,
+    open_questions_remaining: input.openQuestions.length > 0,
+    unresolved_ambiguities_remaining: input.openAmbiguities.length > 0,
+  };
+}
+
+function deriveAmbiguityQuestionMap(
+  ambiguities: IntakeAmbiguityRecord[],
+  questions: FeatureQuestion[],
+): Map<string, FeatureQuestion> {
+  const map = new Map<string, FeatureQuestion>();
+  for (const ambiguity of ambiguities) {
+    const direct = questions.find((question) => question.ambiguity_id === ambiguity.id);
+    if (direct) {
+      map.set(ambiguity.id, direct);
+      continue;
+    }
+    const inferred = questions.find((question) =>
+      question.obligation_ids?.some((obligationId) =>
+        ambiguity.obligation_ids.includes(obligationId),
+      ),
+    );
+    if (inferred) {
+      map.set(ambiguity.id, inferred);
+    }
+  }
+  return map;
+}
+
+export function buildFeatureIntakeWorkspace(
+  input: BuildIntakeWorkspaceInput,
+): FeatureIntakeWorkspace {
+  const intakeQuestions = input.questions.filter(
+    (question) => question.status === 'open' && question.blocking && isIntakeQuestion(question),
+  );
+  const ambiguityQuestionMap = deriveAmbiguityQuestionMap(
+    input.intakeReview?.ambiguities ?? [],
+    intakeQuestions,
+  );
+  const openAmbiguities = (input.intakeReview?.ambiguities ?? []).filter(
+    (ambiguity) => ambiguity.status === 'open',
+  );
+  const resolvedAmbiguities = (input.intakeReview?.ambiguities ?? []).filter(
+    (ambiguity) => ambiguity.status === 'resolved',
+  );
+  const linkedQuestionIds = new Set(
+    [...ambiguityQuestionMap.values()].map((question) => question.question_id),
+  );
+  const generalQuestions = intakeQuestions.filter(
+    (question) => !linkedQuestionIds.has(question.question_id),
+  );
+  const lifecycle = buildPlannerLifecycleSummary({
+    feature: input.feature,
+    intakeSummary: input.intakeSummary,
+    hasSpec: input.artifacts.some(
+      (artifact) => artifact.id === 'source_spec' && artifact.raw_content,
+    ),
+    bootstrapManifest: input.bootstrapManifest,
+    verifiedManifest: input.verifiedManifest,
+    acceptedPlan: null,
+    questions: input.questions,
+  });
+
+  return {
+    lifecycle,
+    summary: input.intakeSummary,
+    review: input.intakeReviewSummary,
+    bootstrap_manifest: summarizeManifest(input.bootstrapManifest),
+    verified_manifest: summarizeManifest(input.verifiedManifest),
+    open_ambiguities: openAmbiguities.map((ambiguity) => ({
+      id: ambiguity.id,
+      summary: ambiguity.summary,
+      status: ambiguity.status,
+      obligation_ids: ambiguity.obligation_ids,
+      blocking: true,
+      linked_open_question_id: ambiguityQuestionMap.get(ambiguity.id)?.question_id ?? null,
+    })),
+    resolved_ambiguities: resolvedAmbiguities.map((ambiguity) => ({
+      id: ambiguity.id,
+      summary: ambiguity.summary,
+      status: ambiguity.status,
+      obligation_ids: ambiguity.obligation_ids,
+      blocking: false,
+      linked_open_question_id: ambiguityQuestionMap.get(ambiguity.id)?.question_id ?? null,
+    })),
+    promotion_readiness: buildPromotionReadiness({
+      intakeSummary: input.intakeSummary,
+      verifiedManifest: input.verifiedManifest,
+      openQuestions: intakeQuestions,
+      openAmbiguities,
+    }),
+    manifest_delta: buildManifestDelta(
+      input.bootstrapManifest,
+      input.verifiedManifest,
+      input.intakeReview,
+    ),
+    open_questions: intakeQuestions,
+    general_questions: generalQuestions,
+    artifacts: input.artifacts,
+  };
+}
+
+function buildPlanningStatus(input: {
+  feature: FeatureSummary;
+  verifiedManifest: VerifiedManifestRecord | null;
+  acceptedPlan: AcceptedPlanRecord | null;
+  freshness: FeaturePlanningWorkspace['freshness'];
+  hasBlockingPlanningQuestion: boolean;
+}): FeaturePlanningWorkspace['status'] {
+  if (input.hasBlockingPlanningQuestion || input.feature.resume_status === 'planning') {
+    return 'blocked';
+  }
+  if (!input.verifiedManifest) {
+    return 'not_started';
+  }
+  if (!input.acceptedPlan) {
+    return input.feature.phase === 'planning' ? 'in_progress' : 'ready_to_plan';
+  }
+  if (input.freshness.stale) {
+    return 'stale';
+  }
+  if (input.feature.phase === 'planning') {
+    return input.feature.activity_state === 'active' ? 'in_progress' : 'accepted';
+  }
+  return 'accepted';
+}
+
+function buildPlanningFocus(input: {
+  feature: FeatureSummary;
+  status: FeaturePlanningWorkspace['status'];
+  acceptedPlan: AcceptedPlanRecord | null;
+  verifiedManifest: VerifiedManifestRecord | null;
+  freshness: FeaturePlanningWorkspace['freshness'];
+}): { focus: string | null; detail: string | null } {
+  if (input.status === 'not_started') {
+    return {
+      focus: 'Planning cannot start yet',
+      detail:
+        'The planner still needs a verified requirements contract before it can accept execution work.',
+    };
+  }
+  if (input.status === 'ready_to_plan') {
+    return {
+      focus: 'Planning is ready to begin',
+      detail:
+        'The verified manifest is available, but the planner has not submitted an accepted plan yet.',
+    };
+  }
+  if (input.status === 'blocked') {
+    return {
+      focus: 'Planning is blocked on input',
+      detail: 'A planning clarification must be answered before the accepted plan can progress.',
+    };
+  }
+  if (input.status === 'stale') {
+    return {
+      focus: 'Accepted plan needs reconciliation',
+      detail: input.freshness.reason,
+    };
+  }
+  const inProgressTask = input.acceptedPlan?.tasks.find((task) => task.status === 'in_progress');
+  if (input.feature.phase === 'planning') {
+    return {
+      focus: inProgressTask?.title ?? 'Planner is refining the accepted execution plan',
+      detail:
+        inProgressTask?.last_updated != null
+          ? `Last updated ${inProgressTask.last_updated}.`
+          : 'Planning is still active against the verified contract.',
+    };
+  }
+  return {
+    focus: 'Accepted plan is driving execution',
+    detail: input.verifiedManifest
+      ? `Execution is operating against verified manifest v${input.verifiedManifest.manifest_version ?? '?'}.`
+      : 'Execution is using the accepted plan as its contract of record.',
+  };
+}
+
+function buildTraceCoverage(
+  verifiedManifest: VerifiedManifestRecord | null,
+  acceptedPlan: AcceptedPlanRecord | null,
+): FeaturePlanningWorkspace['trace_coverage'] {
+  const obligations = verifiedManifest?.obligations ?? [];
+  const traceEntries = acceptedPlan?.plan_trace ?? [];
+  const entryById = new Map(traceEntries.map((entry) => [entry.obligation_id, entry]));
+  let mapped = 0;
+  let deferred = 0;
+  let outOfScope = 0;
+  let missingVerificationIntent = 0;
+  const unmappedIds: string[] = [];
+
+  for (const obligation of obligations) {
+    const entry = entryById.get(obligation.obligation_id);
+    if (!entry) {
+      unmappedIds.push(obligation.obligation_id);
+      continue;
+    }
+    if (entry.disposition === 'in_scope') {
+      mapped += 1;
+    } else if (entry.disposition === 'deferred') {
+      deferred += 1;
+    } else if (entry.disposition === 'out_of_scope') {
+      outOfScope += 1;
+    }
+    if (
+      obligation.verification_hint === 'required' &&
+      entry.disposition === 'in_scope' &&
+      entry.planned_verification.length === 0
+    ) {
+      missingVerificationIntent += 1;
+    }
+  }
+
+  return {
+    total_obligations: obligations.length,
+    mapped,
+    unmapped: unmappedIds.length,
+    deferred,
+    out_of_scope: outOfScope,
+    missing_verification_intent: missingVerificationIntent,
+    unmapped_ids: unmappedIds,
+  };
+}
+
+function normalizeUniqueStrings(values: string[]): string[] {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function buildTraceContract(
+  verifiedManifest: VerifiedManifestRecord | null,
+  acceptedPlan: AcceptedPlanRecord | null,
+): FeaturePlanningWorkspace['trace_contract'] {
+  if (!verifiedManifest || !acceptedPlan) {
+    return null;
+  }
+
+  const obligationIds = normalizeUniqueStrings(
+    verifiedManifest.obligations.map((obligation) => obligation.obligation_id),
+  );
+  const obligationIdSet = new Set(obligationIds);
+  const seen = new Set<string>();
+  const missing: string[] = [];
+  const unknown: string[] = [];
+  const duplicates: string[] = [];
+  const invalidMappings: string[] = [];
+  const invalidMappingDetails = new Map<
+    string,
+    NonNullable<FeaturePlanningWorkspace['trace_contract']>['invalid_mapping_details'][number]
+  >();
+  const plannedPathSet = new Set([
+    ...acceptedPlan.files.create,
+    ...acceptedPlan.files.modify,
+    ...acceptedPlan.files.delete,
+  ]);
+
+  for (const entry of acceptedPlan.plan_trace) {
+    if (!obligationIdSet.has(entry.obligation_id)) {
+      unknown.push(entry.obligation_id);
+    }
+    if (seen.has(entry.obligation_id)) {
+      duplicates.push(entry.obligation_id);
+    }
+    seen.add(entry.obligation_id);
+    if (entry.disposition !== 'in_scope') {
+      continue;
+    }
+    if (entry.planned_paths.length === 0) {
+      invalidMappings.push(entry.obligation_id);
+      if (!invalidMappingDetails.has(entry.obligation_id)) {
+        invalidMappingDetails.set(entry.obligation_id, {
+          obligation_id: entry.obligation_id,
+          reason: 'missing_planned_paths',
+          planned_paths: [],
+        });
+      }
+      continue;
+    }
+    if (!entry.planned_paths.some((plannedPath) => plannedPathSet.has(plannedPath))) {
+      invalidMappings.push(entry.obligation_id);
+      if (!invalidMappingDetails.has(entry.obligation_id)) {
+        invalidMappingDetails.set(entry.obligation_id, {
+          obligation_id: entry.obligation_id,
+          reason: 'planned_paths_outside_plan_files',
+          planned_paths: [...entry.planned_paths],
+        });
+      }
+    }
+  }
+
+  for (const obligationId of obligationIds) {
+    if (!seen.has(obligationId)) {
+      missing.push(obligationId);
+    }
+  }
+
+  const normalizedMissing = normalizeUniqueStrings(missing);
+  const normalizedUnknown = normalizeUniqueStrings(unknown);
+  const normalizedDuplicates = normalizeUniqueStrings(duplicates);
+  const normalizedInvalidMappings = normalizeUniqueStrings(invalidMappings);
+  const normalizedInvalidMappingDetails = normalizedInvalidMappings
+    .map((obligationId) => invalidMappingDetails.get(obligationId) ?? null)
+    .filter(
+      (
+        detail,
+      ): detail is NonNullable<
+        FeaturePlanningWorkspace['trace_contract']
+      >['invalid_mapping_details'][number] => detail !== null,
+    );
+
+  return {
+    valid:
+      normalizedMissing.length === 0 &&
+      normalizedUnknown.length === 0 &&
+      normalizedDuplicates.length === 0 &&
+      normalizedInvalidMappings.length === 0,
+    missing_obligation_ids: normalizedMissing,
+    unknown_obligation_ids: normalizedUnknown,
+    duplicate_obligation_ids: normalizedDuplicates,
+    invalid_mappings: normalizedInvalidMappings,
+    invalid_mapping_details: normalizedInvalidMappingDetails,
+  };
+}
+
+function planAcceptedAt(plan: AcceptedPlanRecord | null): string | null {
+  return maxTimestamp([plan?.accepted_at, plan?.updated_at, plan?.created_at]);
+}
+
+export function buildFeaturePlanningWorkspace(
+  input: BuildPlanningWorkspaceInput,
+): FeaturePlanningWorkspace {
+  const freshness = buildPlanFreshness(input.feature, input.verifiedManifest, input.acceptedPlan);
+  const planningQuestions = input.plannerQuestions.filter(
+    (question) => question.status === 'open' && question.blocking && isPlanningQuestion(question),
+  );
+  const lifecycle = buildPlannerLifecycleSummary({
+    feature: input.feature,
+    intakeSummary: input.intakeSummary,
+    hasSpec: input.artifacts.some(
+      (artifact) => artifact.id === 'plan_markdown' && artifact.raw_content != null,
+    ),
+    bootstrapManifest: null,
+    verifiedManifest: input.verifiedManifest,
+    acceptedPlan: input.acceptedPlan,
+    questions: input.plannerQuestions,
+  });
+  const status = buildPlanningStatus({
+    feature: input.feature,
+    verifiedManifest: input.verifiedManifest,
+    acceptedPlan: input.acceptedPlan,
+    freshness,
+    hasBlockingPlanningQuestion: planningQuestions.length > 0,
+  });
+  const focus = buildPlanningFocus({
+    feature: input.feature,
+    status,
+    acceptedPlan: input.acceptedPlan,
+    verifiedManifest: input.verifiedManifest,
+    freshness,
+  });
+  const explicitNextTasks =
+    input.acceptedPlan?.tasks.filter(
+      (task) => task.status === 'in_progress' || task.status === 'pending',
+    ) ?? [];
+  const blockedTasks = input.acceptedPlan?.tasks.filter((task) => task.status === 'blocked') ?? [];
+  const nextTasks =
+    explicitNextTasks.length > 0
+      ? explicitNextTasks.slice(0, 3)
+      : buildPlanningTaskFallback(status, input.verifiedManifest, freshness).slice(0, 3);
+  const fileScope = {
+    create: input.acceptedPlan?.files.create.length ?? 0,
+    modify: input.acceptedPlan?.files.modify.length ?? 0,
+    delete: input.acceptedPlan?.files.delete.length ?? 0,
+    sample_paths: [
+      ...(input.acceptedPlan?.files.create ?? []),
+      ...(input.acceptedPlan?.files.modify ?? []),
+      ...(input.acceptedPlan?.files.delete ?? []),
+    ].slice(0, 8),
+  };
+  const traceCoverage = buildTraceCoverage(input.verifiedManifest, input.acceptedPlan);
+  const traceContract = buildTraceContract(input.verifiedManifest, input.acceptedPlan);
+
+  let emptyPlanReason: string | null = null;
+  if (!input.acceptedPlan) {
+    if (!input.verifiedManifest) {
+      emptyPlanReason =
+        'Planning cannot begin because intake has not verified the requirements contract yet.';
+    } else if (status === 'blocked') {
+      emptyPlanReason =
+        'Planning is blocked on a clarification and no accepted plan has been submitted yet.';
+    } else if (input.feature.phase === 'planning') {
+      emptyPlanReason =
+        'Planning is in progress, but the planner has not submitted an accepted execution plan yet.';
+    } else {
+      emptyPlanReason =
+        'Planning has not started yet, even though the verified manifest is available.';
+    }
+  }
+
+  return {
+    lifecycle,
+    intake_handoff:
+      input.intakeSummary != null
+        ? {
+            verified_manifest_version: input.intakeSummary.verified_manifest_version,
+            promotion_basis: input.intakeSummary.promotion_basis,
+            last_verified_at: input.intakeSummary.last_verified_at,
+            open_ambiguity_count: input.intakeSummary.open_ambiguity_count,
+          }
+        : null,
+    status,
+    accepted_plan_version: input.acceptedPlan?.plan_version ?? null,
+    accepted_at: planAcceptedAt(input.acceptedPlan),
+    gate_profile: input.acceptedPlan?.gate_profile ?? input.feature.gate_profile ?? null,
+    task_count: input.acceptedPlan?.tasks.length ?? 0,
+    risk_count: input.acceptedPlan?.risks.length ?? 0,
+    current_focus: focus.focus,
+    current_focus_detail: focus.detail,
+    next_tasks: nextTasks,
+    blocked_tasks: blockedTasks,
+    file_scope: fileScope,
+    trace_coverage: traceCoverage,
+    trace_contract: traceContract,
+    freshness,
+    accepted_plan_summary:
+      input.acceptedPlan != null
+        ? {
+            summary: input.acceptedPlan.summary,
+            acceptance_criteria: input.acceptedPlan.acceptance_criteria,
+            scoped_files: [
+              ...input.acceptedPlan.files.create,
+              ...input.acceptedPlan.files.modify,
+              ...input.acceptedPlan.files.delete,
+            ],
+            risks: input.acceptedPlan.risks,
+            owners: input.acceptedPlan.owners,
+            tasks: input.acceptedPlan.tasks,
+          }
+        : null,
+    empty_plan_reason: emptyPlanReason,
+    artifacts: input.artifacts,
+  };
+}