sdd-agent-platform 0.4.1 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/workflow-state/resolve.ts

@@ -1,363 +1,967 @@
-import { WORKFLOW_STATE_RESOLVER_CONTRACT_VERSION } from '../contracts.js';
-import { recordRuntimeProjection } from '../storage/runtime-store.js';
-import type { RunState, RunStateTaskRuntime, RunSummary } from '../run-state/model.js';
-import { affectedFileConflictsForSelectedRun, type WorkflowAffectedFileConflict } from './affected-file-conflicts.js';
-import { readAllRunStates, summarizeRunState } from '../run-state/run-state.js';
-import { resolveSddContext, type ContextBranchSource, type ContextResolverContract } from '../sdd-docs/context.js';
-import { parseSddBranch, type SddTask, type SddTaskGap, type SddTaskModel } from '../sdd-docs/task-parser.js';
-import { dependencyBlockingReasonsForTask, workflowDependencyBlockers, type WorkflowDependencyBlocker } from './dependencies.js';
-import { selectLatestEligibleRunsByTask, type DocumentCompatibilityClass, type LatestEligibleRunSelection } from './latest-eligible-run.js';
-
-export interface WorkflowTaskCounts {
-  total: number;
-  pending: number;
-  inProgress: number;
-  completed: number;
-  blocked: number;
-  deferred: number;
-  unknown: number;
-  gaps: number;
-}
-
-export interface WorkflowLatestTaskRun {
-  partition: string;
-  gitBranch: string | null;
-  taskId: string;
-  runId: string;
-  runStatus: RunState['status'];
-  validationStatus: RunState['validation']['status'];
-  syncBackStatus: RunState['syncBack']['status'];
-  affectedFiles: string[];
-  updatedAt: string;
-  compatibility: DocumentCompatibilityClass;
-  eligibleForDefaultApply: boolean;
-  reasons: string[];
-}
-
-export type WorkflowCommandSemantics = 'inspection_navigation' | 'gate_execution';
-export type WorkflowHostProjectionStatus = 'active' | 'future' | 'unsupported';
-export type WorkflowNextStage = 'spec' | 'tasks' | 'do' | 'test' | 'ship';
-export type WorkflowNextIntentKind = 'start_spec' | 'resolve_task_gaps' | 'inspect_dependency' | 'ship_readiness' | 'inspect_task' | 'list_tasks' | 'continue_do' | 'run_task_validation' | 'run_batch_validation' | 'run_wave_validation';
-
-export interface WorkflowHostCommandProjection {
-  host: 'claude_code' | 'codex' | 'opencode';
-  status: WorkflowHostProjectionStatus;
-  entry: string | null;
-  projectionSurfaces: string[];
-  permissionProjection: string;
-  reason: string;
-}
-
-export interface WorkflowNextIntent {
-  stage: WorkflowNextStage;
-  intent: WorkflowNextIntentKind;
-  canonicalCommand: string;
-  commandSemantics: WorkflowCommandSemantics;
-  evidenceRequirement: string;
-  blockingReason: string | null;
-  hostProjections: WorkflowHostCommandProjection[];
-}
-
-
-export interface WorkflowStateResolution {
-  contract: typeof WORKFLOW_STATE_RESOLVER_CONTRACT_VERSION;
-  generatedAt: string;
-  branch: string;
-  workflowStatus: 'active' | 'not_started';
-  context: ContextResolverContract;
-  documents: SddTaskModel['documents'];
-  model: SddTaskModel;
-  taskCounts: WorkflowTaskCounts;
-  visibleGaps: SddTaskGap[];
-  latestRun: RunSummary | null;
-  latestRunState: RunState | null;
-  latestRunsByTask: WorkflowLatestTaskRun[];
-  latestEligibleRunsByTask: LatestEligibleRunSelection[];
-  affectedFileConflicts: WorkflowAffectedFileConflict[];
-  blockingReasons: string[];
-  dependencyBlockers: WorkflowDependencyBlocker[];
-  recommendedNextCommand: string;
-  nextIntent: WorkflowNextIntent;
-}
-
-export async function resolveWorkflowState(projectRoot: string, options: { branch?: string | null; branchSource?: ContextBranchSource; taskId?: string | null } = {}): Promise<WorkflowStateResolution> {
-  const context = await resolveSddContext(projectRoot, options);
-  const branch = context.partition;
-  const [model, states] = await Promise.all([parseSddBranch(projectRoot, branch), readAllRunStates(projectRoot)]);
-  const visibleGaps = workflowIsActive(model) ? model.gaps : [];
-  const latestEligibleRunsByTask = selectLatestEligibleRunsByTask({ states, model, partition: branch, currentGitBranch: context.currentGitBranch });
-  const latestRunsByTask = selectedLatestTaskRuns(latestEligibleRunsByTask);
-  const selectedTaskRun = options.taskId
-    ? latestRunsByTask.find((entry) => entry.taskId === options.taskId) ?? null
-    : latestRunsByTask.slice().sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt))[0] ?? null;
-  const latestRunState = selectedTaskRun ? states.find((state) => state.runId === selectedTaskRun.runId) ?? null : null;
-  const affectedFileConflicts = latestRunState ? affectedFileConflictsForSelectedRun(states, latestRunState) : [];
-  const runtimeByTask = latestRuntimeTaskStates(latestEligibleRunsByTask, states);
-  const dependencyBlockers = workflowDependencyBlockers(model, { runtimeByTask });
-  const blockingReasons = blockingWorkflowReasons(visibleGaps, affectedFileConflicts, dependencyBlockers);
-  const resolution: WorkflowStateResolution = {
-    contract: WORKFLOW_STATE_RESOLVER_CONTRACT_VERSION,
-    generatedAt: new Date().toISOString(),
-    branch,
-    workflowStatus: workflowIsActive(model) ? 'active' : 'not_started',
-    context,
-    documents: model.documents,
-    model,
-    taskCounts: taskCounts(model, visibleGaps),
-    visibleGaps,
-    latestRun: latestRunState ? summarizeRunState(latestRunState) : null,
-    latestRunState,
-    latestRunsByTask,
-    latestEligibleRunsByTask,
-    affectedFileConflicts,
-    dependencyBlockers,
-    blockingReasons,
-    nextIntent: recommendedWorkflowNextIntent(context, model, latestRunsByTask, visibleGaps, dependencyBlockers, runtimeByTask),
-    recommendedNextCommand: ''
-  };
-  resolution.recommendedNextCommand = resolution.nextIntent.canonicalCommand;
-  try {
-    await recordRuntimeProjection(projectRoot, 'workflow_state', branch, projectWorkflowStateProjection(resolution));
-  } catch {
-    // Projection writes are rebuildable and must not block workflow resolution.
-  }
-  return resolution;
-}
-
-function workflowIsActive(model: SddTaskModel): boolean {
-  return model.documents.specExists || model.documents.planExists || model.documents.tasksExists;
-}
-
-function taskCounts(model: SddTaskModel, gaps: SddTaskGap[]): WorkflowTaskCounts {
-  return {
-    total: model.tasks.length,
-    pending: model.tasks.filter((task) => task.status === 'pending').length,
-    inProgress: model.tasks.filter((task) => task.status === 'in_progress').length,
-    completed: model.tasks.filter((task) => task.status === 'completed').length,
-    blocked: model.tasks.filter((task) => task.status === 'blocked').length,
-    deferred: model.tasks.filter((task) => task.status === 'deferred').length,
-    unknown: model.tasks.filter((task) => task.status === 'unknown').length,
-    gaps: gaps.length
-  };
-}
-
-function selectedLatestTaskRuns(selections: LatestEligibleRunSelection[]): WorkflowLatestTaskRun[] {
-  return selections
-    .flatMap((selection) => selection.selected ? [selection.selected] : [])
-    .map((candidate) => ({
-      partition: candidate.partition,
-      gitBranch: candidate.gitBranch,
-      taskId: candidate.taskId,
-      runId: candidate.runId,
-      runStatus: candidate.runStatus,
-      validationStatus: candidate.validationStatus,
-      syncBackStatus: candidate.syncBackStatus,
-      affectedFiles: candidate.affectedFiles,
-      updatedAt: candidate.updatedAt,
-      compatibility: candidate.compatibility,
-      eligibleForDefaultApply: candidate.eligibleForDefaultApply,
-      reasons: candidate.reasons
-    }))
-    .sort((left, right) => left.taskId.localeCompare(right.taskId));
-}
-
-
-function blockingWorkflowReasons(gaps: SddTaskGap[], conflicts: WorkflowAffectedFileConflict[], dependencyBlockers: WorkflowDependencyBlocker[]): string[] {
-  const reasons = gaps.filter((gap) => gap.severity === 'blocking').map((gap) => `${gap.field}: ${gap.message}`);
-  for (const conflict of conflicts) {
-    reasons.push(`Affected file ${conflict.file} is active in run ${conflict.runId} for ${conflict.partition}/${conflict.taskId}.`);
-  }
-  for (const blocker of dependencyBlockers) {
-    reasons.push(blocker.reason);
-  }
-  return reasons;
-}
-
-function recommendedWorkflowNextIntent(
-  context: ContextResolverContract,
-  model: SddTaskModel,
-  latestRunsByTask: WorkflowLatestTaskRun[],
-  gaps: SddTaskGap[],
-  dependencyBlockers: WorkflowDependencyBlocker[],
-  runtimeByTask: Map<string, RunStateTaskRuntime>
-): WorkflowNextIntent {
-  if (!workflowIsActive(model)) {
-    return workflowNextIntent('spec', 'start_spec', `sdd spec --branch ${context.partition}`, 'Start the spec stage before planning or task execution.', null);
-  }
-  const blockingGap = gaps.find((gap) => gap.severity === 'blocking');
-  if (blockingGap) {
-    return workflowNextIntent('tasks', 'resolve_task_gaps', `sdd tasks gaps --branch ${context.partition}`, 'Resolve blocking task document gaps before execution evidence can be trusted.', `${blockingGap.field}: ${blockingGap.message}`);
-  }
-
-  const strictTask = model.tasks.find((task) => needsTaskValidation(task, runtimeByTask.get(task.id)));
-  if (strictTask) {
-    return workflowNextIntent('test', 'run_task_validation', `sdd test task ${strictTask.id} --branch ${context.partition}`, 'Validate this strict or task_end task before more implementation proceeds.', null);
-  }
-
-  const readyBoundary = readyValidationBoundary(model, runtimeByTask);
-  if (readyBoundary?.kind === 'batch') {
-    return workflowNextIntent('test', 'run_batch_validation', `sdd test batch ${readyBoundary.id} --branch ${context.partition}`, `Validate accumulated implementation evidence for batch ${readyBoundary.id}.`, null);
-  }
-  if (readyBoundary?.kind === 'wave') {
-    return workflowNextIntent('test', 'run_wave_validation', waveValidationCommand(context.partition, readyBoundary.wave), `Validate accumulated implementation evidence for wave ${readyBoundary.wave ?? 'all'}.`, null);
-  }
-
-  if (latestRunsByTask.some(latestEligibleRunReadyForShip)) {
-    return workflowNextIntent('ship', 'ship_readiness', `sdd ship --branch ${context.partition} --dry-run`, 'Run release readiness after validation PASS; create a decision card only if the gate requires human review.', null);
-  }
-
-  const nextTask = model.tasks.find((task) => task.status === 'pending' && !runtimeTaskImplemented(runtimeByTask.get(task.id)) && dependencyBlockingReasonsForTask(model, task.id, { runtimeByTask }).length === 0);
-  if (nextTask) {
-    return workflowNextIntent('do', 'continue_do', `sdd do task ${nextTask.id} --branch ${context.partition}`, 'Continue sequential implementation; validation can wait until the declared task or batch boundary.', null);
-  }
-
-  const dependencyBlocker = dependencyBlockers[0];
-  if (dependencyBlocker) {
-    return workflowNextIntent('tasks', 'inspect_dependency', `sdd tasks inspect ${dependencyBlocker.dependencyId} --branch ${context.partition}`, 'Inspect the dependency task before continuing this workflow.', dependencyBlocker.reason);
-  }
-
-  const pendingTask = model.tasks.find((task) => task.status === 'pending');
-  return pendingTask
-    ? workflowNextIntent('tasks', 'inspect_task', `sdd tasks inspect ${pendingTask.id} --branch ${context.partition}`, 'Inspect task boundary, acceptance, validation, and capability needs before do/test.', null)
-    : workflowNextIntent('tasks', 'list_tasks', `sdd tasks list --branch ${context.partition}`, 'Inspect task state and decide whether to continue or ship.', null);
-}
-
-function latestRuntimeTaskStates(selections: LatestEligibleRunSelection[], states: RunState[]): Map<string, RunStateTaskRuntime> {
-  const stateByRunId = new Map(states.map((state) => [state.runId, state]));
-  const result = new Map<string, RunStateTaskRuntime>();
-  for (const selection of selections) {
-    const selected = selection.selected;
-    if (!selected) {
-      continue;
-    }
-    const taskState = stateByRunId.get(selected.runId)?.tasks[selected.taskId];
-    if (taskState) {
-      result.set(selected.taskId, taskState);
-    }
-  }
-  return result;
-}
-
-function needsTaskValidation(task: SddTask, runtime: RunStateTaskRuntime | undefined): boolean {
-  return Boolean(runtimeTaskImplemented(runtime) && runtime?.verificationStatus !== 'pass' && (task.requiresVerifyBeforeNext || task.validationTiming === 'task_end'));
-}
-
-function readyValidationBoundary(model: SddTaskModel, runtimeByTask: Map<string, RunStateTaskRuntime>): { kind: 'batch'; id: string } | { kind: 'wave'; wave: number | null } | null {
-  const batchGroups = new Map<string, SddTask[]>();
-  const waveGroups = new Map<string, { wave: number | null; tasks: SddTask[] }>();
-  for (const task of model.tasks) {
-    if (task.validationTiming === 'batch_end' && task.validationBatch) {
-      batchGroups.set(task.validationBatch, [...(batchGroups.get(task.validationBatch) ?? []), task]);
-    }
-    if (task.validationTiming === 'wave_end') {
-      const key = String(task.wave ?? 'all');
-      const group = waveGroups.get(key) ?? { wave: task.wave, tasks: [] };
-      group.tasks.push(task);
-      waveGroups.set(key, group);
-    }
-  }
-  for (const [id, tasks] of batchGroups) {
-    if (validationBoundaryReady(tasks, runtimeByTask)) {
-      return { kind: 'batch', id };
-    }
-  }
-  for (const group of waveGroups.values()) {
-    if (validationBoundaryReady(group.tasks, runtimeByTask)) {
-      return { kind: 'wave', wave: group.wave };
-    }
-  }
-  return null;
-}
-
-function validationBoundaryReady(tasks: SddTask[], runtimeByTask: Map<string, RunStateTaskRuntime>): boolean {
-  return tasks.every((task) => runtimeTaskImplemented(runtimeByTask.get(task.id)))
-    && tasks.some((task) => runtimeByTask.get(task.id)?.verificationStatus !== 'pass');
-}
-
-function runtimeTaskImplemented(runtime: RunStateTaskRuntime | undefined): boolean {
-  return runtime?.implementationStatus === 'implemented' || runtime?.status === 'implemented_pending_validation' || runtime?.status === 'implemented_verified';
-}
-
-function latestEligibleRunReadyForShip(run: WorkflowLatestTaskRun): boolean {
-  return run.runStatus === 'completed' && run.validationStatus === 'pass';
-}
-
-function waveValidationCommand(branch: string, wave: number | null): string {
-  return wave === null ? `sdd test wave --branch ${branch}` : `sdd test wave --branch ${branch} --wave ${wave}`;
-}
-
-
-function workflowNextIntent(
-  stage: WorkflowNextStage,
-  intent: WorkflowNextIntentKind,
-  canonicalCommand: string,
-  evidenceRequirement: string,
-  blockingReason: string | null
-): WorkflowNextIntent {
-  return {
-    stage,
-    intent,
-    canonicalCommand,
-    commandSemantics: stage === 'do' || stage === 'test' || stage === 'ship' ? 'gate_execution' : 'inspection_navigation',
-    evidenceRequirement,
-    blockingReason,
-    hostProjections: hostCommandProjections(canonicalCommand)
-  };
-}
-
-function hostCommandProjections(canonicalCommand: string): WorkflowHostCommandProjection[] {
-  return [
-    {
-      host: 'claude_code',
-      status: 'active',
-      entry: claudeCodeSlashEntry(canonicalCommand),
-      projectionSurfaces: ['slash command', 'skill', 'settings/hooks/statusline metadata'],
-      permissionProjection: 'Claude Code permission mode/tool prompts remain host enforcement, not SDD lifecycle truth.',
-      reason: 'Claude Code supports slash/skill/statusline projections; the canonical CLI command remains the portable source of workflow intent.'
-    },
-    {
-      host: 'codex',
-      status: 'future',
-      entry: null,
-      projectionSurfaces: ['config.toml profile', 'AGENTS.md instruction surface', 'approval_policy', 'sandbox_mode'],
-      permissionProjection: 'Codex approval and sandbox controls can project execution policy; custom command/skill projection is not marked active without stronger evidence.',
-      reason: 'Codex exposes approval, sandbox, AGENTS.md, and built-in slash surfaces, but project custom workflow command semantics stay future until validated.'
-    },
-    {
-      host: 'opencode',
-      status: 'active',
-      entry: opencodeCommandEntry(canonicalCommand),
-      projectionSurfaces: ['opencode.json/jsonc', '.opencode/commands', '.opencode/agents', '.opencode/skills', 'permissions'],
-      permissionProjection: 'OpenCode allow/ask/deny permissions can project SDD tool policy; SDD artifacts remain authoritative evidence.',
-      reason: 'OpenCode documents project commands, agents, skills, and permissions suitable for host-specific projection.'
-    }
-  ];
-}
-
-function claudeCodeSlashEntry(canonicalCommand: string): string {
-  const [command, ...rest] = canonicalCommand.replace(/^sdd\s+/, '').split(' ');
-  return `/sdd:${command}${rest.length > 0 ? ` ${rest.join(' ')}` : ''}`;
-}
-
-function opencodeCommandEntry(canonicalCommand: string): string {
-  return `/sdd ${canonicalCommand.replace(/^sdd\s+/, '')}`;
-}
-
-function projectWorkflowStateProjection(resolution: WorkflowStateResolution): unknown {
-  return {
-    contract: resolution.contract,
-    generatedAt: resolution.generatedAt,
-    branch: resolution.branch,
-    workflowStatus: resolution.workflowStatus,
-    documents: resolution.documents,
-    taskCounts: resolution.taskCounts,
-    latestRun: resolution.latestRun,
-    latestRunsByTask: resolution.latestRunsByTask,
-    latestEligibleRunsByTask: resolution.latestEligibleRunsByTask,
-    affectedFileConflicts: resolution.affectedFileConflicts,
-    dependencyBlockers: resolution.dependencyBlockers,
-    blockingReasons: resolution.blockingReasons,
-    nextIntent: resolution.nextIntent,
-    recommendedNextCommand: resolution.recommendedNextCommand
-  };
-}
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { WORKFLOW_STATE_RESOLVER_CONTRACT_VERSION, type RuntimeProjectionEnvelope, type RuntimeRef, type SddStage } from '../contracts.js';
+import { listRuntimeProjections, listRuntimeRepairs, recordRuntimeProjection, type RuntimeRepairRecord } from '../storage/runtime-store.js';
+import type { RunState, RunStateTaskRuntime, RunSummary } from '../run-state/model.js';
+import { affectedFileConflictsForSelectedRun, type WorkflowAffectedFileConflict } from './affected-file-conflicts.js';
+import { readAllRunStates, summarizeRunState } from '../run-state/run-state.js';
+import { resolveSddContext, type ContextBranchSource, type ContextResolverContract } from '../sdd-docs/context.js';
+import { parseSddBranch, type SddTask, type SddTaskGap, type SddTaskModel } from '../sdd-docs/task-parser.js';
+import { dependencyBlockingReasonsForTask, workflowDependencyBlockers, type WorkflowDependencyBlocker } from './dependencies.js';
+import { selectLatestEligibleRunsByTask, type DocumentCompatibilityClass, type LatestEligibleRunSelection } from './latest-eligible-run.js';
+import {
+  EXECUTE_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+  PLAN_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+  readTruthAlignmentProjection,
+  SHIP_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+  SPEC_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+  TASKS_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+  type TruthAlignmentProjection
+} from '../stage-collaboration.js';
+import { buildTruthReconciliationDecision, minimalReworkFrontier, recordTruthReconciliationDecision, truthDriftClassForAlignment, truthReconciliationOwnerStage, type TruthReconciliationDecision } from '../truth-reconciliation.js';
+import { normalizePortablePath } from '../path-safety.js';
+import { hashDocumentContent } from '../sdd-docs/document-hashes.js';
+import { recordWorkflowRuntimeProjections } from './runtime-projections.js';
+
+export interface WorkflowTaskCounts {
+  total: number;
+  pending: number;
+  inProgress: number;
+  completed: number;
+  blocked: number;
+  deferred: number;
+  unknown: number;
+  gaps: number;
+}
+
+export interface WorkflowLatestTaskRun {
+  partition: string;
+  gitBranch: string | null;
+  taskId: string;
+  runId: string;
+  runStatus: RunState['status'];
+  validationStatus: RunState['validation']['status'];
+  affectedFiles: string[];
+  updatedAt: string;
+  compatibility: DocumentCompatibilityClass;
+  eligibleForDefaultApply: boolean;
+  reasons: string[];
+}
+
+export type WorkflowCommandSemantics = 'inspection_navigation' | 'gate_execution';
+export type WorkflowHostProjectionStatus = 'active' | 'future' | 'unsupported';
+export type SddCommandBundle = 'spec' | 'plan' | 'tasks' | 'execute' | 'ship';
+export type BundleResumeMode = 'start' | 'resume' | 'repair' | 'reconcile';
+export type WorkflowNextStage = SddCommandBundle;
+export type WorkflowNextIntentKind = 'start_spec' | 'resolve_task_gaps' | 'inspect_dependency' | 'workflow_complete' | 'ship_readiness' | 'inspect_task' | 'list_tasks' | 'continue_execute' | 'run_task_validation' | 'run_batch_validation' | 'run_wave_validation' | 'repair_failure' | 'reconcile_truth';
+
+export const COMMAND_BUNDLES: Record<SddCommandBundle, readonly SddStage[]> = {
+  spec: ['spec'],
+  plan: ['plan'],
+  tasks: ['tasks'],
+  execute: ['execute'],
+  ship: ['ship']
+};
+
+export interface CommandBundlePlan {
+  contract: 'sdd-command-bundle-plan-v1';
+  branch: string;
+  bundle: SddCommandBundle;
+  stages: SddStage[];
+  targetRuntimeStage: SddStage;
+  resumeMode: BundleResumeMode;
+  canonicalCommand: string;
+  displayCommand: string;
+  canAutoAdvanceWithinBundle: boolean;
+  autoAdvanceTo: SddStage | null;
+  stopReasons: string[];
+  evidenceSurface: string[];
+}
+
+export interface WorkflowReadinessSummary {
+  requiredTaskIds: string[];
+  acceptedTaskIds: string[];
+  missingTaskIds: string[];
+  readyForShip: boolean;
+  whyNotShip: string[];
+}
+
+export interface WorkflowHostCommandProjection {
+  host: 'claude_code' | 'codex' | 'opencode';
+  status: WorkflowHostProjectionStatus;
+  entry: string | null;
+  projectionSurfaces: string[];
+  permissionProjection: string;
+  reason: string;
+}
+
+export interface WorkflowNextIntent {
+  stage: WorkflowNextStage;
+  bundle: SddCommandBundle;
+  targetRuntimeStage: SddStage;
+  resumeMode: BundleResumeMode;
+  intent: WorkflowNextIntentKind;
+  canonicalCommand: string;
+  displayCommand: string;
+  commandSemantics: WorkflowCommandSemantics;
+  evidenceRequirement: string;
+  blockingReason: string | null;
+  canAutoAdvanceWithinBundle: boolean;
+  autoAdvanceTo: SddStage | null;
+  stopReasons: string[];
+  evidenceSurface: string[];
+  commandBundle: CommandBundlePlan;
+  hostProjections: WorkflowHostCommandProjection[];
+}
+
+
+export interface WorkflowStateResolution {
+  contract: typeof WORKFLOW_STATE_RESOLVER_CONTRACT_VERSION;
+  generatedAt: string;
+  branch: string;
+  workflowStatus: 'active' | 'not_started';
+  context: ContextResolverContract;
+  documents: SddTaskModel['documents'];
+  model: SddTaskModel;
+  taskCounts: WorkflowTaskCounts;
+  visibleGaps: SddTaskGap[];
+  latestRun: RunSummary | null;
+  latestRunState: RunState | null;
+  latestRunsByTask: WorkflowLatestTaskRun[];
+  latestEligibleRunsByTask: LatestEligibleRunSelection[];
+  affectedFileConflicts: WorkflowAffectedFileConflict[];
+  blockingReasons: string[];
+  dependencyBlockers: WorkflowDependencyBlocker[];
+  openRepairs: RuntimeRepairRecord[];
+  workflowReadiness: WorkflowReadinessSummary;
+  whyNotShip: string[];
+  recommendedNextCommand: string;
+  nextIntent: WorkflowNextIntent;
+  truthReconciliation: TruthReconciliationDecision | null;
+}
+
+export async function resolveWorkflowState(projectRoot: string, options: { branch?: string | null; branchSource?: ContextBranchSource; taskId?: string | null } = {}): Promise<WorkflowStateResolution> {
+  const context = await resolveSddContext(projectRoot, options);
+  const branch = context.partition;
+  const [model, states, openRepairs, truthAlignmentEnvelope] = await Promise.all([parseSddBranch(projectRoot, branch), readAllRunStates(projectRoot), listRuntimeRepairs(projectRoot, { branchSlug: branch, status: 'open' }), readTruthAlignmentProjection(projectRoot, { branch })]);
+  const visibleGaps = workflowIsActive(model) ? model.gaps : [];
+  const latestEligibleRunsByTask = selectLatestEligibleRunsByTask({ states, model, partition: branch, currentGitBranch: context.currentGitBranch });
+  const latestRunsByTask = selectedLatestTaskRuns(latestEligibleRunsByTask);
+  const selectedTaskRun = options.taskId
+    ? latestRunsByTask.find((entry) => entry.taskId === options.taskId) ?? null
+    : latestRunsByTask.slice().sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt))[0] ?? null;
+  const latestRunState = selectedTaskRun ? states.find((state) => state.runId === selectedTaskRun.runId) ?? null : null;
+  const affectedFileConflicts = latestRunState ? affectedFileConflictsForSelectedRun(states, latestRunState) : [];
+  const runtimeByTask = latestRuntimeTaskStates(latestEligibleRunsByTask, states);
+  const dependencyBlockers = workflowDependencyBlockers(model, { runtimeByTask });
+  const readiness = workflowReadinessSummary(model, latestRunsByTask);
+  const generatedAt = new Date().toISOString();
+  const blockingReasons = [...blockingWorkflowReasons(visibleGaps, affectedFileConflicts, dependencyBlockers), ...openRepairs.map(formatOpenRepairReason)];
+  const truthReconciliation = await resolveTruthReconciliationDecision(projectRoot, branch, truthAlignmentEnvelope?.payload ?? null, generatedAt, { states, model });
+  const resolution: WorkflowStateResolution = {
+    contract: WORKFLOW_STATE_RESOLVER_CONTRACT_VERSION,
+    generatedAt,
+    branch,
+    workflowStatus: workflowIsActive(model) ? 'active' : 'not_started',
+    context,
+    documents: model.documents,
+    model,
+    taskCounts: taskCounts(model, visibleGaps),
+    visibleGaps,
+    latestRun: latestRunState ? summarizeRunState(latestRunState) : null,
+    latestRunState,
+    latestRunsByTask,
+    latestEligibleRunsByTask,
+    affectedFileConflicts,
+    dependencyBlockers,
+    openRepairs,
+    blockingReasons,
+    workflowReadiness: readiness,
+    whyNotShip: readiness.whyNotShip,
+    nextIntent: recommendedWorkflowNextIntent(context, model, latestRunsByTask, visibleGaps, dependencyBlockers, runtimeByTask, readiness, openRepairs, truthReconciliation),
+    truthReconciliation,
+    recommendedNextCommand: ''
+  };
+  resolution.recommendedNextCommand = resolution.nextIntent.canonicalCommand;
+  try {
+    await recordRuntimeProjection(projectRoot, 'workflow_state', branch, projectWorkflowStateProjection(resolution));
+    await recordWorkflowRuntimeProjections(projectRoot, resolution);
+  } catch {
+    // Projection writes are rebuildable and must not block workflow resolution.
+  }
+  return resolution;
+}
+
+function workflowIsActive(model: SddTaskModel): boolean {
+  return model.documents.specExists || model.documents.planExists || model.documents.tasksExists;
+}
+
+function taskCounts(model: SddTaskModel, gaps: SddTaskGap[]): WorkflowTaskCounts {
+  return {
+    total: model.tasks.length,
+    pending: model.tasks.filter((task) => task.status === 'pending').length,
+    inProgress: model.tasks.filter((task) => task.status === 'in_progress').length,
+    completed: model.tasks.filter((task) => task.status === 'completed').length,
+    blocked: model.tasks.filter((task) => task.status === 'blocked').length,
+    deferred: model.tasks.filter((task) => task.status === 'deferred').length,
+    unknown: model.tasks.filter((task) => task.status === 'unknown').length,
+    gaps: gaps.length
+  };
+}
+
+function selectedLatestTaskRuns(selections: LatestEligibleRunSelection[]): WorkflowLatestTaskRun[] {
+  return selections
+    .flatMap((selection) => selection.selected ? [selection.selected] : [])
+    .map((candidate) => ({
+      partition: candidate.partition,
+      gitBranch: candidate.gitBranch,
+      taskId: candidate.taskId,
+      runId: candidate.runId,
+      runStatus: candidate.runStatus,
+      validationStatus: candidate.validationStatus,
+      affectedFiles: candidate.affectedFiles,
+      updatedAt: candidate.updatedAt,
+      compatibility: candidate.compatibility,
+      eligibleForDefaultApply: candidate.eligibleForDefaultApply,
+      reasons: candidate.reasons
+    }))
+    .sort((left, right) => left.taskId.localeCompare(right.taskId));
+}
+
+
+function blockingWorkflowReasons(gaps: SddTaskGap[], conflicts: WorkflowAffectedFileConflict[], dependencyBlockers: WorkflowDependencyBlocker[]): string[] {
+  const reasons = gaps.filter((gap) => gap.severity === 'blocking').map((gap) => `${gap.field}: ${gap.message}`);
+  for (const conflict of conflicts) {
+    reasons.push(`Affected file ${conflict.file} is active in run ${conflict.runId} for ${conflict.partition}/${conflict.taskId}.`);
+  }
+  for (const blocker of dependencyBlockers) {
+    reasons.push(blocker.reason);
+  }
+  return reasons;
+}
+
+async function resolveTruthReconciliationDecision(projectRoot: string, branch: string, truthAlignment: TruthAlignmentProjection | null, generatedAt: string, progress: { states: RunState[]; model: SddTaskModel }): Promise<TruthReconciliationDecision | null> {
+  if (!truthAlignment) {
+    return null;
+  }
+  const freshness = await refreshAlignedTruthAlignmentFreshness(projectRoot, branch, truthAlignment);
+  if (freshness.truthAlignment.status === 'aligned') {
+    return null;
+  }
+  const changeKind = truthDriftClassForAlignment(freshness.truthAlignment);
+  const ownerStage = truthReconciliationOwnerStage(changeKind, freshness.truthAlignment.ownerStage);
+  const minimalFrontier = minimalReworkFrontier({ ownerStage, semanticImpact: freshness.truthAlignment.semanticImpact, invalidatesStages: freshness.truthAlignment.invalidatesStages });
+  const targetStage = await activeTruthReconciliationStage(projectRoot, minimalFrontier, freshness.truthAlignment, progress);
+  const nextIntent = truthReconciliationNextIntent(branch, targetStage, freshness.truthAlignment.reasons);
+  const decision = buildTruthReconciliationDecision({
+    truthAlignment: freshness.truthAlignment,
+    nextIntent,
+    changeKind,
+    changedRef: freshness.changedRef,
+    oldHash: freshness.oldHash,
+    newHash: freshness.newHash
+  });
+  await recordTruthReconciliationDecision(projectRoot, decision, generatedAt);
+  return decision;
+}
+
+interface TruthAlignmentFreshness {
+  truthAlignment: TruthAlignmentProjection;
+  changedRef?: RuntimeRef;
+  oldHash?: string;
+  newHash?: string;
+}
+
+async function refreshAlignedTruthAlignmentFreshness(projectRoot: string, branch: string, truthAlignment: TruthAlignmentProjection): Promise<TruthAlignmentFreshness> {
+  if (truthAlignment.status !== 'aligned') {
+    return { truthAlignment };
+  }
+  const staleRefs: Array<{ ref: RuntimeRef; currentHash: string }> = [];
+  for (const ref of [...truthAlignment.declaredTruthRefs, ...truthAlignment.acceptedRealityRefs]) {
+    if (!ref.hash || ref.kind === 'projection' || ref.kind === 'run') {
+      continue;
+    }
+    const currentHash = await currentTruthRefHash(projectRoot, ref);
+    if (currentHash !== ref.hash) {
+      staleRefs.push({ ref, currentHash });
+    }
+  }
+  const unresolvedStaleRefs = await unresolvedStaleTruthRefs(projectRoot, branch, truthAlignment, staleRefs);
+  const firstStaleRef = unresolvedStaleRefs[0];
+  if (!firstStaleRef) {
+    return { truthAlignment };
+  }
+  const ownerStage = ownerStageForTruthRef(branch, firstStaleRef.ref) ?? truthAlignment.ownerStage ?? 'ship';
+  const semanticImpact = semanticImpactForTruthRef(branch, firstStaleRef.ref);
+  const reasons = [
+    ...truthAlignment.reasons,
+    ...unresolvedStaleRefs.map((entry) => `TruthAlignment ref hash is stale for ${entry.ref.ref}: expected ${entry.ref.hash ?? 'unknown'}, actual ${entry.currentHash}.`)
+  ];
+  return {
+    truthAlignment: {
+      ...truthAlignment,
+      status: 'update_required',
+      ownerStage,
+      semanticImpact,
+      staleRefs: uniqueRuntimeRefs([...truthAlignment.staleRefs, ...unresolvedStaleRefs.map((entry) => entry.ref)]),
+      invalidatesStages: uniqueStages([...truthAlignment.invalidatesStages, ownerStage]),
+      reasons: uniqueStrings(reasons)
+    },
+    changedRef: firstStaleRef.ref,
+    oldHash: firstStaleRef.ref.hash,
+    newHash: firstStaleRef.currentHash
+  };
+}
+
+async function unresolvedStaleTruthRefs(projectRoot: string, branch: string, truthAlignment: TruthAlignmentProjection, staleRefs: Array<{ ref: RuntimeRef; currentHash: string }>): Promise<Array<{ ref: RuntimeRef; currentHash: string }>> {
+  const unresolved: Array<{ ref: RuntimeRef; currentHash: string }> = [];
+  for (const entry of staleRefs) {
+    if (!await staleTruthRefReconciledAfterAlignment(projectRoot, branch, truthAlignment, entry)) {
+      unresolved.push(entry);
+    }
+  }
+  return unresolved;
+}
+
+async function staleTruthRefReconciledAfterAlignment(projectRoot: string, branch: string, truthAlignment: TruthAlignmentProjection, entry: { ref: RuntimeRef; currentHash: string }): Promise<boolean> {
+  const stage = ownerStageForTruthRef(branch, entry.ref);
+  return stage ? await stageCloseAcceptedTruthRefAfterTruthAlignment(projectRoot, truthAlignment, stage, entry.ref, entry.currentHash) : false;
+}
+
+async function activeTruthReconciliationStage(projectRoot: string, frontier: SddStage[], truthAlignment: TruthAlignmentProjection, progress: { states: RunState[]; model: SddTaskModel }): Promise<SddStage> {
+  for (const stage of frontier) {
+    if (!await truthReconciliationStageCompleted(projectRoot, stage, truthAlignment, progress)) {
+      return stage;
+    }
+  }
+  return frontier[frontier.length - 1] ?? truthAlignment.ownerStage ?? 'ship';
+}
+
+async function truthReconciliationStageCompleted(projectRoot: string, stage: SddStage, truthAlignment: TruthAlignmentProjection, progress: { states: RunState[]; model: SddTaskModel }): Promise<boolean> {
+  if (await stageCloseCompletedAfterTruthAlignment(projectRoot, truthAlignment, stage)) {
+    return true;
+  }
+  const taskIds = reconciliationTaskIds(truthAlignment, progress);
+  if (stage === 'execute') {
+    return taskIds.every((taskId) => progress.states.some((state) => stateAfterTruthAlignment(state, truthAlignment) && stateTaskImplemented(state.tasks[taskId]) && stateTaskValidationPassed(state.tasks[taskId], state)));
+  }
+  return false;
+}
+
+function reconciliationTaskIds(truthAlignment: TruthAlignmentProjection, progress: { states: RunState[]; model: SddTaskModel }): string[] {
+  const requiredIds = requiredTaskIds(progress.model);
+  const requiredIdSet = new Set(requiredIds);
+  const targetRefs = new Set([...truthAlignment.staleRefs, ...truthAlignment.acceptedRealityRefs].map((ref) => normalizePortablePath(ref.ref)).filter(Boolean));
+  const taskIds = new Set<string>();
+  for (const state of progress.states) {
+    if (state.partition && state.partition !== truthAlignment.branch) {
+      continue;
+    }
+    if (!stateReferencesAnyRef(state, targetRefs)) {
+      continue;
+    }
+    for (const taskId of stateTaskIds(state)) {
+      if (requiredIdSet.has(taskId)) {
+        taskIds.add(taskId);
+      }
+    }
+  }
+  const scopedTaskIds = [...taskIds].sort();
+  return scopedTaskIds.length > 0 ? scopedTaskIds : requiredIds;
+}
+
+function stateReferencesAnyRef(state: RunState, targetRefs: Set<string>): boolean {
+  if (targetRefs.size === 0) {
+    return false;
+  }
+  const refs = [
+    ...state.artifacts.map((artifact) => artifact.path),
+    ...Object.values(state.tasks).flatMap((runtime) => [...(runtime.artifacts ?? []), ...(runtime.evidence ?? [])])
+  ];
+  return refs.some((ref) => refMatchesTarget(ref, targetRefs));
+}
+
+function refMatchesTarget(ref: string, targetRefs: Set<string>): boolean {
+  const normalized = normalizePortablePath(ref);
+  return Boolean(normalized && [...targetRefs].some((target) => normalized === target || normalized.endsWith(`/${target}`) || target.endsWith(`/${normalized}`)));
+}
+
+function stateTaskIds(state: RunState): string[] {
+  return [...new Set([state.taskId, state.currentTask, ...Object.keys(state.tasks)].filter((taskId): taskId is string => typeof taskId === 'string' && taskId.length > 0))];
+}
+
+async function stageCloseCompletedAfterTruthAlignment(projectRoot: string, truthAlignment: TruthAlignmentProjection, stage: SddStage): Promise<boolean> {
+  const projectionType = stageAdjudicationProjectionType(stage);
+  if (!projectionType) {
+    return false;
+  }
+  const projections = await listRuntimeProjections(projectRoot, [projectionType]);
+  return projections
+    .map((projection) => projection.payload as RuntimeProjectionEnvelope<StageCloseAdjudicationProjection>)
+    .some((envelope) => stageAdjudicationCompletedAfterTruthAlignment(envelope, truthAlignment, stage));
+}
+
+interface StageCloseAdjudicationProjection {
+  stage?: SddStage;
+  scope?: { branch?: string };
+  health?: string | null;
+  stageDecision?: { status?: string | null; health?: string | null; acceptedDecisionRefs?: RuntimeRef[] };
+  closureRefs?: Record<string, unknown>;
+}
+
+function stageAdjudicationProjectionType(stage: SddStage): string | null {
+  const projectionTypes: Record<SddStage, string> = {
+    spec: SPEC_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+    plan: PLAN_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+    tasks: TASKS_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+    execute: EXECUTE_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+    ship: SHIP_COLLABORATION_ADJUDICATION_PROJECTION_TYPE
+  };
+  return projectionTypes[stage] ?? null;
+}
+
+async function stageCloseAcceptedTruthRefAfterTruthAlignment(projectRoot: string, truthAlignment: TruthAlignmentProjection, stage: SddStage, staleRef: RuntimeRef, currentHash: string): Promise<boolean> {
+  const projectionType = stageAdjudicationProjectionType(stage);
+  if (!projectionType) {
+    return false;
+  }
+  const projections = await listRuntimeProjections(projectRoot, [projectionType]);
+  return projections
+    .map((projection) => projection.payload as RuntimeProjectionEnvelope<StageCloseAdjudicationProjection>)
+    .some((envelope) => stageAdjudicationCompletedAfterTruthAlignment(envelope, truthAlignment, stage)
+      && acceptedStageRefs(envelope.payload).some((acceptedRef) => acceptedTruthRefMatchesCurrent(acceptedRef, staleRef, currentHash)));
+}
+
+function acceptedTruthRefMatchesCurrent(acceptedRef: RuntimeRef, staleRef: RuntimeRef, currentHash: string): boolean {
+  return acceptedRef.kind === staleRef.kind
+    && normalizePortablePath(acceptedRef.ref) === normalizePortablePath(staleRef.ref)
+    && acceptedRef.hash === currentHash;
+}
+
+function stageAdjudicationCompletedAfterTruthAlignment(envelope: RuntimeProjectionEnvelope<StageCloseAdjudicationProjection>, truthAlignment: TruthAlignmentProjection, stage: SddStage): boolean {
+  const expectedHealth = expectedStageCloseHealth(stage);
+  return envelope.payload?.scope?.branch === truthAlignment.branch
+    && envelope.payload.stage === stage
+    && Date.parse(envelope.generatedAt) > Date.parse(truthAlignment.createdAt)
+    && envelope.payload.stageDecision?.status === 'completed'
+    && (envelope.payload.health === expectedHealth || envelope.payload.stageDecision?.health === expectedHealth)
+    && acceptedStageRefs(envelope.payload).some((ref) => ownerStageForTruthRef(truthAlignment.branch, ref) === stage);
+}
+
+function expectedStageCloseHealth(stage: SddStage): string {
+  const expectedHealth: Record<SddStage, string> = {
+    spec: 'ready_for_plan',
+    plan: 'ready_for_tasks',
+    tasks: 'ready_for_execute',
+    execute: 'ready_for_ship',
+    ship: 'ship_ready'
+  };
+  return expectedHealth[stage];
+}
+
+function acceptedStageRefs(adjudication: StageCloseAdjudicationProjection): RuntimeRef[] {
+  const refs = Array.isArray(adjudication.stageDecision?.acceptedDecisionRefs) ? adjudication.stageDecision.acceptedDecisionRefs : [];
+  const closureRefs = adjudication.closureRefs ?? {};
+  const closureRefKeys = [
+    'acceptedSpecRef',
+    'acceptedPlanRef',
+    'acceptedTasksRef',
+    'acceptedVerifyRef',
+    'acceptedImplementationRef',
+    'acceptedTestEvidenceRef',
+    'acceptedEvidenceJudgmentRef',
+    'acceptedShipReadinessRef'
+  ];
+  return [
+    ...refs,
+    ...closureRefKeys.map((key) => runtimeRefFromUnknown(closureRefs[key]))
+  ].filter((ref): ref is RuntimeRef => ref !== null);
+}
+
+function runtimeRefFromUnknown(value: unknown): RuntimeRef | null {
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+  const candidate = value as Partial<RuntimeRef>;
+  if (typeof candidate.kind !== 'string' || typeof candidate.ref !== 'string') {
+    return null;
+  }
+  return {
+    kind: candidate.kind as RuntimeRef['kind'],
+    ref: candidate.ref,
+    hash: typeof candidate.hash === 'string' ? candidate.hash : undefined
+  };
+}
+
+function requiredTaskIds(model: SddTaskModel): string[] {
+  return model.tasks.filter((task) => task.status !== 'deferred').map((task) => task.id);
+}
+
+function stateAfterTruthAlignment(state: RunState, truthAlignment: TruthAlignmentProjection): boolean {
+  return Date.parse(state.updatedAt) > Date.parse(truthAlignment.createdAt);
+}
+
+function stateTaskImplemented(runtime: RunStateTaskRuntime | undefined): boolean {
+  return runtimeTaskImplemented(runtime);
+}
+
+function stateTaskValidationPassed(runtime: RunStateTaskRuntime | undefined, state: RunState): boolean {
+  return runtime?.verificationStatus === 'pass' || runtime?.status === 'implemented_verified' || state.validation.status === 'pass';
+}
+
+async function currentTruthRefHash(projectRoot: string, ref: RuntimeRef): Promise<string> {
+  const normalized = normalizePortablePath(ref.ref);
+  if (!normalized || normalized === '.' || normalized === '..' || normalized.includes('..') || path.isAbsolute(ref.ref)) {
+    return 'unsafe-ref';
+  }
+  const projectPath = path.resolve(projectRoot);
+  const filePath = path.resolve(projectPath, normalized);
+  if (!filePath.startsWith(`${projectPath}${path.sep}`)) {
+    return 'escaped-ref';
+  }
+  try {
+    return hashDocumentContent(await readFile(filePath, 'utf8'));
+  } catch {
+    return 'missing-ref';
+  }
+}
+
+function ownerStageForTruthRef(branch: string, ref: RuntimeRef): SddStage | null {
+  const normalized = normalizePortablePath(ref.ref);
+  if (!normalized) {
+    return null;
+  }
+  if (normalized === `specs/${branch}/spec.md`) {
+    return 'spec';
+  }
+  if (normalized === `specs/${branch}/plan.md`) {
+    return 'plan';
+  }
+  if (normalized === `specs/${branch}/tasks.md`) {
+    return 'tasks';
+  }
+  if (normalized === `specs/${branch}/verify.md`) {
+    return 'tasks';
+  }
+  if (normalized === `specs/${branch}/release.md`) {
+    return 'ship';
+  }
+  const runStage = normalized.match(new RegExp(`^\\.sdd/runs/${escapeRegExp(branch)}/([^/]+)/`))?.[1];
+  return runStage && isSddStage(runStage) ? runStage : null;
+}
+
+function semanticImpactForTruthRef(branch: string, ref: RuntimeRef): TruthAlignmentProjection['semanticImpact'] {
+  const ownerStage = ownerStageForTruthRef(branch, ref);
+  return ref.kind === 'document' || ownerStage === 'spec' || ownerStage === 'plan' || ownerStage === 'tasks' ? 'none' : 'material';
+}
+
+function uniqueRuntimeRefs(refs: RuntimeRef[]): RuntimeRef[] {
+  const seen = new Set<string>();
+  const result: RuntimeRef[] = [];
+  for (const ref of refs) {
+    const key = `${ref.kind}:${ref.ref}:${ref.hash ?? ''}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(ref);
+    }
+  }
+  return result;
+}
+
+function uniqueStages(stages: SddStage[]): SddStage[] {
+  return ['spec', 'plan', 'tasks', 'execute', 'ship'].filter((stage): stage is SddStage => stages.includes(stage as SddStage));
+}
+
+function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function truthReconciliationNextIntent(branch: string, ownerStage: SddStage, reasons: string[]): WorkflowNextIntent {
+  const bundle = commandBundleForRuntimeStage(ownerStage);
+  return workflowNextIntent(bundle, 'reconcile_truth', truthReconciliationCommand(branch, ownerStage), `Reconcile truth drift in ${ownerStage}-manager before downstream ship readiness.`, reasons.join('; ') || 'truthAlignment requires reconciliation', {
+    targetRuntimeStage: ownerStage,
+    resumeMode: 'reconcile',
+    canAutoAdvanceWithinBundle: ownerStage === 'execute',
+    evidenceSurface: [...evidenceSurfaceForRuntimeStage(ownerStage), 'truthReconciliation projection']
+  });
+}
+
+function truthReconciliationCommand(branch: string, ownerStage: SddStage): string {
+  return stageCloseCommandForRuntimeStage(branch, ownerStage);
+}
+
+function stageCloseCommandForRuntimeStage(branch: string, stage: SddStage): string {
+  if (stage === 'execute') {
+    return `sdd execute close --branch ${branch} --compact-json`;
+  }
+  return `sdd ${stage} close --branch ${branch} --compact-json`;
+}
+
+function formatOpenRepairReason(repair: RuntimeRepairRecord): string {
+  return `Open ${repair.repairType} ${repair.repairId}: ${repair.blockers.join('; ')}`;
+}
+
+function recommendedWorkflowNextIntent(
+  context: ContextResolverContract,
+  model: SddTaskModel,
+  latestRunsByTask: WorkflowLatestTaskRun[],
+  gaps: SddTaskGap[],
+  dependencyBlockers: WorkflowDependencyBlocker[],
+  runtimeByTask: Map<string, RunStateTaskRuntime>,
+  readiness: WorkflowReadinessSummary,
+  openRepairs: RuntimeRepairRecord[],
+  truthReconciliation: TruthReconciliationDecision | null
+): WorkflowNextIntent {
+  if (!workflowIsActive(model)) {
+    return workflowNextIntent('spec', 'start_spec', `sdd spec --branch ${context.partition}`, 'Start the spec stage before planning or task execution.', null);
+  }
+  const blockingGap = gaps.find((gap) => gap.severity === 'blocking');
+  if (blockingGap) {
+    return workflowNextIntent('tasks', 'resolve_task_gaps', `sdd tasks gaps --branch ${context.partition}`, 'Resolve blocking task document gaps before execution evidence can be trusted.', `${blockingGap.field}: ${blockingGap.message}`);
+  }
+  const openRepair = openRepairs[0];
+  if (openRepair) {
+    return workflowNextIntent('execute', 'repair_failure', openRepair.recommendedCommands[0] ?? `sdd doctor --branch ${context.partition} --latest-only`, openRepair.requiredEvidence.join('; ') || 'Resolve the open repair with new accepted evidence or a fresh gate PASS.', formatOpenRepairReason(openRepair));
+  }
+
+  if (truthReconciliation) {
+    return truthReconciliation.nextIntent;
+  }
+
+  const strictTask = model.tasks.find((task) => needsTaskValidation(task, runtimeByTask.get(task.id)));
+  if (strictTask) {
+    return workflowNextIntent('execute', 'run_task_validation', validationUnitCommand(context.partition, validationUnitIdForTask(strictTask)), 'Validate this task before more implementation proceeds.', null);
+  }
+
+  const readyBoundary = readyValidationBoundary(model, runtimeByTask);
+  if (readyBoundary?.kind === 'batch') {
+    return workflowNextIntent('execute', 'run_batch_validation', validationUnitCommand(context.partition, readyBoundary.id), `Validate accumulated implementation evidence for validation unit ${readyBoundary.id}.`, null);
+  }
+  if (readyBoundary?.kind === 'wave') {
+    return workflowNextIntent('execute', 'run_wave_validation', validationUnitCommand(context.partition, readyBoundary.id), `Validate accumulated implementation evidence for validation unit ${readyBoundary.id}.`, null);
+  }
+
+  if (readiness.readyForShip) {
+    if (evidenceJudgmentPassedForShip(model, runtimeByTask)) {
+      return workflowNextIntent('ship', 'ship_readiness', `sdd ship close --branch ${context.partition} --compact-json`, 'Execute evidence judgment passed; close ship readiness with ship-stage evidence.', null);
+    }
+    return workflowNextIntent('execute', 'continue_execute', stageCloseCommandForRuntimeStage(context.partition, 'execute'), 'Close execute with evidence-judgment material before ship readiness can run.', null, {
+      targetRuntimeStage: 'execute',
+      resumeMode: 'resume',
+      canAutoAdvanceWithinBundle: true,
+      evidenceSurface: ['.sdd/runs/<branch>/execute/*.md', 'truthAlignment projection']
+    });
+  }
+
+  const nextTask = model.tasks.find((task) => task.status === 'pending' && !runtimeTaskImplemented(runtimeByTask.get(task.id)) && dependencyBlockingReasonsForTask(model, task.id, { runtimeByTask }).length === 0);
+  if (nextTask) {
+    return workflowNextIntent('execute', 'continue_execute', `sdd execute --branch ${context.partition}`, `Continue public execute stage for ready task ${nextTask.id}.`, null);
+  }
+
+  const dependencyBlocker = dependencyBlockers[0];
+  if (dependencyBlocker) {
+    return workflowNextIntent('tasks', 'inspect_dependency', `sdd tasks inspect ${dependencyBlocker.dependencyId} --branch ${context.partition}`, 'Inspect the dependency task before continuing this workflow.', dependencyBlocker.reason);
+  }
+
+  const pendingTask = model.tasks.find((task) => task.status === 'pending');
+  return pendingTask
+    ? workflowNextIntent('tasks', 'inspect_task', `sdd tasks inspect ${pendingTask.id} --branch ${context.partition}`, 'Inspect task boundary, acceptance, validation, and capability needs before execute.', null)
+    : workflowNextIntent('tasks', 'list_tasks', `sdd tasks list --branch ${context.partition}`, 'Inspect task state and decide whether to continue or ship.', null);
+}
+
+export function latestRuntimeTaskStates(selections: LatestEligibleRunSelection[], states: RunState[]): Map<string, RunStateTaskRuntime> {
+  const stateByRunId = new Map(states.map((state) => [state.runId, state]));
+  const result = new Map<string, RunStateTaskRuntime>();
+  for (const selection of selections) {
+    const selected = selection.selected;
+    if (!selected) {
+      continue;
+    }
+    const taskState = stateByRunId.get(selected.runId)?.tasks[selected.taskId];
+    if (taskState) {
+      result.set(selected.taskId, taskState);
+    }
+  }
+  return result;
+}
+
+function needsTaskValidation(task: SddTask, runtime: RunStateTaskRuntime | undefined): boolean {
+  return Boolean(runtimeTaskImplemented(runtime) && runtime?.verificationStatus !== 'pass' && (task.requiresVerifyBeforeNext || task.validationTiming === 'task_end'));
+}
+
+function validationUnitIdForTask(task: SddTask): string {
+  return task.validationBatch ?? `task-${task.id}`;
+}
+
+
+function readyValidationBoundary(model: SddTaskModel, runtimeByTask: Map<string, RunStateTaskRuntime>): { kind: 'batch'; id: string } | { kind: 'wave'; id: string } | null {
+  const batchGroups = new Map<string, SddTask[]>();
+  const waveGroups = new Map<string, SddTask[]>();
+  for (const task of model.tasks) {
+    if (task.validationTiming === 'batch_end' && task.validationBatch) {
+      batchGroups.set(task.validationBatch, [...(batchGroups.get(task.validationBatch) ?? []), task]);
+    }
+    if (task.validationTiming === 'wave_end') {
+      const id = validationUnitIdForTask(task);
+      waveGroups.set(id, [...(waveGroups.get(id) ?? []), task]);
+    }
+  }
+  for (const [id, tasks] of batchGroups) {
+    if (validationBoundaryReady(tasks, runtimeByTask)) {
+      return { kind: 'batch', id };
+    }
+  }
+  for (const [id, tasks] of waveGroups) {
+    if (validationBoundaryReady(tasks, runtimeByTask)) {
+      return { kind: 'wave', id };
+    }
+  }
+  return null;
+}
+
+function validationBoundaryReady(tasks: SddTask[], runtimeByTask: Map<string, RunStateTaskRuntime>): boolean {
+  return tasks.every((task) => runtimeTaskImplemented(runtimeByTask.get(task.id)))
+    && tasks.some((task) => runtimeByTask.get(task.id)?.verificationStatus !== 'pass');
+}
+
+function runtimeTaskImplemented(runtime: RunStateTaskRuntime | undefined): boolean {
+  return runtime?.implementationStatus === 'implemented' || runtime?.status === 'implemented_pending_validation' || runtime?.status === 'implemented_verified';
+}
+
+function latestEligibleRunReadyForShip(run: WorkflowLatestTaskRun): boolean {
+  return run.runStatus === 'completed' && run.validationStatus === 'pass';
+}
+
+function evidenceJudgmentPassedForShip(model: SddTaskModel, runtimeByTask: Map<string, RunStateTaskRuntime>): boolean {
+  const requiredTasks = model.tasks.filter((task) => task.status !== 'deferred');
+  return requiredTasks.length > 0 && requiredTasks.every((task) => {
+    const runtime = runtimeByTask.get(task.id);
+    return runtime?.verifyStatus === 'PASS' || runtime?.status === 'implemented_verified';
+  });
+}
+
+function workflowReadinessSummary(model: SddTaskModel, latestRunsByTask: WorkflowLatestTaskRun[]): WorkflowReadinessSummary {
+  const requiredTaskIds = model.tasks.filter((task) => task.status !== 'deferred').map((task) => task.id).sort();
+  const acceptedTaskIds = requiredTaskIds.filter((taskId) => latestRunsByTask.some((run) => run.taskId === taskId && latestEligibleRunReadyForShip(run))).sort();
+  const missingTaskIds = requiredTaskIds.filter((taskId) => !acceptedTaskIds.includes(taskId));
+  return {
+    requiredTaskIds,
+    acceptedTaskIds,
+    missingTaskIds,
+    readyForShip: requiredTaskIds.length > 0 && missingTaskIds.length === 0,
+    whyNotShip: missingTaskIds.length === 0 ? [] : missingTaskIds.map((taskId) => `Task ${taskId} has no accepted validation PASS evidence.`)
+  };
+}
+
+function validationUnitCommand(branch: string, validationUnitId: string): string {
+  return `sdd execute --branch ${branch} --json`;
+}
+
+
+export interface WorkflowNextIntentOptions {
+  targetRuntimeStage?: SddStage;
+  resumeMode?: BundleResumeMode;
+  displayCommand?: string;
+  canAutoAdvanceWithinBundle?: boolean;
+  autoAdvanceTo?: SddStage | null;
+  stopReasons?: string[];
+  evidenceSurface?: string[];
+}
+
+export function workflowNextIntent(
+  stage: WorkflowNextStage,
+  intent: WorkflowNextIntentKind,
+  canonicalCommand: string,
+  evidenceRequirement: string,
+  blockingReason: string | null,
+  options: WorkflowNextIntentOptions = {}
+): WorkflowNextIntent {
+  const targetRuntimeStage = options.targetRuntimeStage ?? runtimeStageForCommand(canonicalCommand, stage);
+  const bundle = commandBundleForRuntimeStage(targetRuntimeStage);
+  const stages = [...COMMAND_BUNDLES[bundle]];
+  const autoAdvanceTo = options.autoAdvanceTo ?? null;
+  const canAutoAdvanceWithinBundle = options.canAutoAdvanceWithinBundle ?? Boolean(autoAdvanceTo && stages.includes(autoAdvanceTo));
+  const displayCommand = options.displayCommand ?? commandBundleDisplayCommand(bundle, targetRuntimeStage, canonicalCommand);
+  const stopReasons = options.stopReasons ?? [];
+  const evidenceSurface = options.evidenceSurface ?? evidenceSurfaceForRuntimeStage(targetRuntimeStage);
+  const resumeMode = options.resumeMode ?? defaultResumeMode(intent, targetRuntimeStage);
+  const commandBundle: CommandBundlePlan = {
+    contract: 'sdd-command-bundle-plan-v1',
+    branch: branchFromCommand(canonicalCommand),
+    bundle,
+    stages,
+    targetRuntimeStage,
+    resumeMode,
+    canonicalCommand,
+    displayCommand,
+    canAutoAdvanceWithinBundle,
+    autoAdvanceTo,
+    stopReasons,
+    evidenceSurface
+  };
+  return {
+    stage: bundle,
+    bundle,
+    targetRuntimeStage,
+    resumeMode,
+    intent,
+    canonicalCommand,
+    displayCommand,
+    commandSemantics: commandSemanticsForTarget(bundle, targetRuntimeStage, canonicalCommand),
+    evidenceRequirement,
+    blockingReason,
+    canAutoAdvanceWithinBundle,
+    autoAdvanceTo,
+    stopReasons,
+    evidenceSurface,
+    commandBundle,
+    hostProjections: hostCommandProjections(commandBundle)
+  };
+}
+
+export function commandBundleForRuntimeStage(stage: SddStage): SddCommandBundle {
+  return stage;
+}
+
+function runtimeStageForCommand(canonicalCommand: string, fallbackBundle: SddCommandBundle): SddStage {
+  const command = canonicalCommand.replace(/^sdd\s+/, '').split(/\s+/)[0];
+  return isSddStage(command) ? command : COMMAND_BUNDLES[fallbackBundle][0];
+}
+
+function isSddStage(value: string): value is SddStage {
+  return value === 'spec' || value === 'plan' || value === 'tasks' || value === 'execute' || value === 'ship';
+}
+
+function defaultResumeMode(intent: WorkflowNextIntentKind, targetRuntimeStage: SddStage): BundleResumeMode {
+  if (intent === 'repair_failure') {
+    return 'repair';
+  }
+  if (targetRuntimeStage === 'execute') {
+    return 'resume';
+  }
+  return 'start';
+}
+
+function commandSemanticsForTarget(bundle: SddCommandBundle, targetRuntimeStage: SddStage, canonicalCommand: string): WorkflowCommandSemantics {
+  if (/^sdd\s+status\b/.test(canonicalCommand)) {
+    return 'inspection_navigation';
+  }
+  return bundle === 'execute' || bundle === 'ship' || /\sclose\b/.test(canonicalCommand) || targetRuntimeStage === 'execute' ? 'gate_execution' : 'inspection_navigation';
+}
+
+function evidenceSurfaceForRuntimeStage(stage: SddStage): string[] {
+  const surfaces: Partial<Record<SddStage, string[]>> = {
+    spec: ['specs/<branch>/spec.md', '.sdd/runs/<branch>/spec/*.md'],
+    plan: ['specs/<branch>/plan.md', '.sdd/runs/<branch>/plan/*.md'],
+    tasks: ['specs/<branch>/tasks.md', 'specs/<branch>/verify.md', '.sdd/runs/<branch>/tasks/*.md'],
+    execute: ['.sdd/runs/<branch>/execute/*.md', 'truthAlignment projection'],
+    ship: ['.sdd/runs/<branch>/ship/*.md', 'truthAlignment projection']
+  };
+  return surfaces[stage] ?? [`.sdd/runs/<branch>/${stage}/*.md`];
+}
+
+function branchFromCommand(canonicalCommand: string): string {
+  const tokens = canonicalCommand.split(/\s+/);
+  const branchIndex = tokens.indexOf('--branch');
+  return branchIndex >= 0 ? tokens[branchIndex + 1] ?? '<branch>' : '<branch>';
+}
+
+function commandBundleDisplayCommand(bundle: SddCommandBundle, targetRuntimeStage: SddStage, canonicalCommand: string): string {
+  return claudeCodeSlashEntry({ bundle, targetRuntimeStage, canonicalCommand });
+}
+
+function hostCommandProjections(commandBundle: CommandBundlePlan): WorkflowHostCommandProjection[] {
+  return [
+    {
+      host: 'claude_code',
+      status: 'active',
+      entry: claudeCodeSlashEntry(commandBundle),
+      projectionSurfaces: ['slash command', 'skill', 'settings/hooks/statusline metadata'],
+      permissionProjection: 'Claude Code permission mode/tool prompts remain host enforcement, not SDD lifecycle truth.',
+      reason: 'Claude Code supports slash/skill/statusline projections; the canonical CLI command remains the portable source of workflow intent.'
+    },
+    {
+      host: 'codex',
+      status: 'future',
+      entry: null,
+      projectionSurfaces: ['config.toml profile', 'AGENTS.md instruction surface', 'approval_policy', 'sandbox_mode'],
+      permissionProjection: 'Codex approval and sandbox controls can project execution policy; custom command/skill projection is not marked active without stronger evidence.',
+      reason: 'Codex exposes approval, sandbox, AGENTS.md, and built-in slash surfaces, but project custom workflow command semantics stay future until validated.'
+    },
+    {
+      host: 'opencode',
+      status: 'active',
+      entry: opencodeCommandEntry(commandBundle),
+      projectionSurfaces: ['opencode.json/jsonc', '.opencode/commands', '.opencode/agents', '.opencode/skills', 'permissions'],
+      permissionProjection: 'OpenCode allow/ask/deny permissions can project SDD tool policy; SDD artifacts remain authoritative evidence.',
+      reason: 'OpenCode documents project commands, agents, skills, and permissions suitable for host-specific projection.'
+    }
+  ];
+}
+
+function claudeCodeSlashEntry(commandBundle: Pick<CommandBundlePlan, 'bundle' | 'targetRuntimeStage' | 'canonicalCommand'>): string {
+  return projectedCommandEntry('/sdd:', commandBundle, ':');
+}
+
+function opencodeCommandEntry(commandBundle: Pick<CommandBundlePlan, 'bundle' | 'targetRuntimeStage' | 'canonicalCommand'>): string {
+  return projectedCommandEntry('/sdd ', commandBundle, ' ');
+}
+
+function projectedCommandEntry(prefix: string, commandBundle: Pick<CommandBundlePlan, 'bundle' | 'targetRuntimeStage' | 'canonicalCommand'>, separator: ':' | ' '): string {
+  const tokens = commandBundle.canonicalCommand.replace(/^sdd\s+/, '').split(/\s+/).filter(Boolean);
+  const [command, ...rest] = tokens;
+  if (!command) {
+    return `/sdd ${tokens.join(' ')}`;
+  }
+  if (command === 'execute') {
+    const head = separator === ':' ? `${prefix}execute` : `${prefix}execute`;
+    return `${head}${rest.length > 0 ? ` ${rest.join(' ')}` : ''}`;
+  }
+  if (!isSddStage(command)) {
+    return `/sdd ${tokens.join(' ')}`;
+  }
+  const tailTokens = stripTargetOption(rest);
+  const publicClose = command === commandBundle.bundle && tailTokens[0] === 'close';
+  const target = publicClose || commandBundle.targetRuntimeStage === commandBundle.bundle ? '' : ` target=${commandBundle.targetRuntimeStage}`;
+  const head = separator === ':' ? `${prefix}${commandBundle.bundle}` : `${prefix}${commandBundle.bundle}`;
+  return `${head}${target}${tailTokens.length > 0 ? ` ${tailTokens.join(' ')}` : ''}`;
+}
+
+function stripTargetOption(tokens: string[]): string[] {
+  const result: string[] = [];
+  for (let index = 0; index < tokens.length; index += 1) {
+    if (tokens[index] === '--target') {
+      index += 1;
+      continue;
+    }
+    result.push(tokens[index]);
+  }
+  return result;
+}
+
+function projectWorkflowStateProjection(resolution: WorkflowStateResolution): unknown {
+  return {
+    contract: resolution.contract,
+    generatedAt: resolution.generatedAt,
+    branch: resolution.branch,
+    workflowStatus: resolution.workflowStatus,
+    documents: resolution.documents,
+    taskCounts: resolution.taskCounts,
+    latestRun: resolution.latestRun,
+    latestRunsByTask: resolution.latestRunsByTask,
+    latestEligibleRunsByTask: resolution.latestEligibleRunsByTask,
+    affectedFileConflicts: resolution.affectedFileConflicts,
+    dependencyBlockers: resolution.dependencyBlockers,
+    openRepairs: resolution.openRepairs,
+    blockingReasons: resolution.blockingReasons,
+    workflowReadiness: resolution.workflowReadiness,
+    whyNotShip: resolution.whyNotShip,
+    nextIntent: resolution.nextIntent,
+    truthReconciliation: resolution.truthReconciliation,
+    recommendedNextCommand: resolution.recommendedNextCommand
+  };
+}