sdd-agent-platform 0.4.0 → 0.4.2

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

@@ -0,0 +1,712 @@
+import { createHash } from 'node:crypto';
+
+import type { RuntimeProjectionEnvelope, RuntimeRef, RuntimeScope, SddStage } from '../contracts.js';
+import type { RunStateTaskRuntime } from '../run-state/model.js';
+import type { SddTask, SddTaskModel } from '../sdd-docs/task-parser.js';
+import {
+  readRuntimeProjectionEnvelope,
+  recordRuntimeProjectionEnvelope,
+  type RuntimeArtifactPayloadRecord,
+  type RuntimeEvidenceSetRecord,
+  type RuntimeEvidenceSetStatus,
+  type RuntimeProjectionEnvelopeWriteResult,
+  type RuntimeSelectionPointerRecord
+} from '../storage/runtime-store.js';
+import type { WorkflowLatestTaskRun, WorkflowNextIntent, WorkflowStateResolution } from './resolve.js';
+
+export const WORKFLOW_CURRENT_STATE_PROJECTION_TYPE = 'phase9_25_workflow_current_state';
+export const TASK_ORCHESTRATION_PROJECTION_TYPE = 'phase9_26_task_orchestration';
+export const VALIDATION_UNIT_PROJECTION_TYPE = 'phase9_26_validation_unit';
+export const NEXT_INTENT_PROJECTION_TYPE = 'phase9_29_next_intent';
+export const WORKFLOW_RUNTIME_PROJECTION_PRODUCER = 'phase9-workflow-state-runtime';
+export const WORKFLOW_RUNTIME_PROJECTION_PRODUCER_VERSION = 'phase9.25-9.29-runtime-projections-v1';
+
+export type RuntimeStateWriter = 'runtime_sqlite';
+export type RuntimeStateAuthority = 'runtime_gate' | 'runtime_projection' | 'selection_pointer';
+export type RuntimeConsumability = 'consumable' | 'not_consumable' | 'blocked' | 'stale';
+export type LifecycleRuntimeStatus = 'not_started' | 'active' | 'blocked' | 'ready_for_ship' | 'ship_ready';
+export type TaskRuntimeStatus = 'pending' | 'blocked' | 'implemented' | 'implemented_pending_validation' | 'implemented_verified' | 'deferred' | 'unknown';
+export type ValidationUnitRuntimeStatus = 'not_ready' | 'ready' | 'pass' | 'pass_with_gaps' | 'blocked' | 'failed';
+export type NextIntentCandidateStatus = 'recommended' | 'allowed' | 'blocked';
+
+export interface RuntimeProjectionMetadata {
+  contract: 'sdd-runtime-projection-metadata-v1';
+  inputRefs: RuntimeRef[];
+  inputHash: string;
+  schemaVersion: string;
+  projectorVersion: typeof WORKFLOW_RUNTIME_PROJECTION_PRODUCER_VERSION;
+  generatedAt: string;
+}
+
+export interface LifecycleRuntimeState {
+  contract: 'sdd-lifecycle-runtime-state-v1';
+  branch: string;
+  currentStage: SddStage | 'not_started';
+  status: LifecycleRuntimeStatus;
+  writer: RuntimeStateWriter;
+  authority: RuntimeStateAuthority;
+  blockingReasons: string[];
+  readiness: {
+    requiredTaskIds: string[];
+    acceptedTaskIds: string[];
+    missingTaskIds: string[];
+    readyForShip: boolean;
+  };
+  updatedAt: string;
+}
+
+export interface TaskRuntimeState {
+  contract: 'sdd-task-runtime-state-v1';
+  branch: string;
+  taskId: string;
+  taskHash: string;
+  status: TaskRuntimeStatus;
+  declaredStatus: SddTask['status'];
+  implementationStatus: RunStateTaskRuntime['implementationStatus'] | null;
+  verificationStatus: RunStateTaskRuntime['verificationStatus'] | null;
+  verifyStatus: string | null;
+  consumability: RuntimeConsumability;
+  acceptedRunId: string | null;
+  acceptedEvidenceInputHash: string;
+  evidenceRefs: RuntimeRef[];
+  blockers: string[];
+  updatedAt: string;
+}
+
+export interface ValidationUnitRuntimeState {
+  contract: 'sdd-validation-unit-runtime-state-v1';
+  branch: string;
+  validationUnitId: string;
+  validationUnitHash: string;
+  taskIds: string[];
+  validationTiming: SddTask['validationTiming'];
+  status: ValidationUnitRuntimeStatus;
+  consumability: RuntimeConsumability;
+  evidenceRefs: RuntimeRef[];
+  blockers: string[];
+  updatedAt: string;
+}
+
+export interface TaskOrchestrationProjectionItem {
+  taskId: string;
+  title: string | null;
+  unitHash: string;
+  boundaryHash: string;
+  dependencyHash: string;
+  capabilityHash: string;
+  affectedFilesHash: string;
+  validationUnitId: string;
+  validationTiming: SddTask['validationTiming'];
+  dependsOn: string[];
+  affectedFiles: string[];
+  capabilitySignals: string[];
+  sourceRef: RuntimeRef;
+}
+
+export interface TaskOrchestrationProjection {
+  contract: 'sdd-task-orchestration-projection-v1';
+  branch: string;
+  metadata: RuntimeProjectionMetadata;
+  tasks: TaskOrchestrationProjectionItem[];
+}
+
+export interface ValidationUnitProjectionItem {
+  validationUnitId: string;
+  unitHash: string;
+  validationTiming: SddTask['validationTiming'];
+  taskIds: string[];
+  commands: string[];
+  sourceRefs: RuntimeRef[];
+}
+
+export interface ValidationUnitProjection {
+  contract: 'sdd-validation-unit-projection-v1';
+  branch: string;
+  metadata: RuntimeProjectionMetadata;
+  validationUnits: ValidationUnitProjectionItem[];
+}
+
+export interface EvidenceRecord {
+  contract: 'sdd-evidence-record-v1';
+  branch: string;
+  scope: RuntimeScope;
+  logicalRef: RuntimeRef;
+  digest: string;
+  role: string;
+  status: RuntimeArtifactPayloadRecord['status'] | RuntimeEvidenceSetStatus;
+  consumable: boolean;
+  selectedBy: RuntimeSelectionPointerRecord | null;
+  sourceEvidenceSetId: string | null;
+}
+
+export interface AcceptedStageEvidenceSet {
+  contract: 'sdd-accepted-stage-evidence-set-v1';
+  branch: string;
+  stage: SddStage;
+  taskId?: string;
+  acceptedRefs: RuntimeRef[];
+  partialRefs: RuntimeRef[];
+  supersededRefs: RuntimeRef[];
+  rejectedRefs: RuntimeRef[];
+  quarantinedRefs: RuntimeRef[];
+  staleRefs: RuntimeRef[];
+  activeAttemptRefs: RuntimeRef[];
+  boundInputHashes: Record<string, string>;
+  selectionReasons: string[];
+}
+
+export interface StageManagerContract {
+  contract: 'sdd-stage-manager-contract-v1';
+  stage: SddStage;
+  branch: string;
+  authority: 'coordinate_agent_team' | 'request_runtime_gate' | 'author_stage_evidence';
+  forbiddenAuthority: Array<'write_runtime_sqlite' | 'mark_gate_passed' | 'ship_without_runtime_gate'>;
+  requiredInputRefs: RuntimeRef[];
+  requiredOutputSurfaces: string[];
+}
+
+export interface AgentTeamPlan {
+  contract: 'sdd-agent-team-plan-v1';
+  branch: string;
+  stage: SddStage;
+  taskIds: string[];
+  manager: string;
+  members: Array<{ role: string; capabilitySignals: string[]; evidenceResponsibilities: string[] }>;
+  fanInPolicy: 'manager_review_required' | 'runtime_gate_required';
+}
+
+export interface RuntimeContextPack {
+  contract: 'sdd-runtime-context-pack-v1';
+  scope: RuntimeScope;
+  sourceRefs: RuntimeRef[];
+  sourceInputHash: string;
+  taskIds: string[];
+  validationUnitIds: string[];
+  allowedEvidenceSurfaces: string[];
+}
+
+export interface CapabilityRegistry {
+  contract: 'sdd-capability-registry-v1';
+  branch: string;
+  domains: Array<{ id: string; source: 'task_capability_signal' | 'agent_catalog' | 'skill_catalog' | 'tool_catalog'; refs: RuntimeRef[] }>;
+}
+
+export interface NextIntentCandidate {
+  status: NextIntentCandidateStatus;
+  bundle: WorkflowNextIntent['bundle'];
+  targetRuntimeStage: SddStage;
+  canonicalCommand: string;
+  displayCommand: string;
+  commandSemantics: WorkflowNextIntent['commandSemantics'];
+  reason: string;
+  gateStillRequired: boolean;
+}
+
+export interface NextIntentProjection {
+  contract: 'sdd-next-intent-projection-v1';
+  branch: string;
+  advisory: true;
+  generatedAt: string;
+  primary: WorkflowNextIntent;
+  candidates: NextIntentCandidate[];
+  hostProjections: WorkflowNextIntent['hostProjections'];
+  rules: {
+    recommendationIsNotAGate: true;
+    executionMustCheckReadiness: true;
+    internalStagesStayBundleScoped: true;
+  };
+}
+
+export interface WorkflowCurrentStateProjection {
+  contract: 'sdd-workflow-current-state-projection-v1';
+  branch: string;
+  generatedAt: string;
+  writer: RuntimeStateWriter;
+  metadata: RuntimeProjectionMetadata;
+  lifecycle: LifecycleRuntimeState;
+  tasks: TaskRuntimeState[];
+  validationUnits: ValidationUnitRuntimeState[];
+  taskOrchestration: TaskOrchestrationProjection;
+  validationUnitProjection: ValidationUnitProjection;
+  nextIntentRef: RuntimeRef;
+}
+
+export async function recordWorkflowRuntimeProjections(projectRoot: string, resolution: WorkflowStateResolution): Promise<void> {
+  await Promise.all([
+    recordWorkflowCurrentStateProjection(projectRoot, resolution),
+    recordTaskOrchestrationProjection(projectRoot, resolution),
+    recordValidationUnitProjection(projectRoot, resolution),
+    recordNextIntentProjection(projectRoot, resolution)
+  ]);
+}
+
+export async function recordWorkflowCurrentStateProjection(projectRoot: string, resolution: WorkflowStateResolution): Promise<RuntimeProjectionEnvelopeWriteResult<WorkflowCurrentStateProjection>> {
+  const projection = buildWorkflowCurrentStateProjection(resolution);
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: WORKFLOW_CURRENT_STATE_PROJECTION_TYPE,
+    scopeKey: workflowRuntimeProjectionScopeKey(resolution.branch),
+    inputHash: projection.metadata.inputHash,
+    producer: WORKFLOW_RUNTIME_PROJECTION_PRODUCER,
+    producerVersion: WORKFLOW_RUNTIME_PROJECTION_PRODUCER_VERSION,
+    generatedAt: resolution.generatedAt,
+    payload: projection
+  });
+}
+
+export async function readWorkflowCurrentStateProjection(projectRoot: string, branch: string): Promise<RuntimeProjectionEnvelope<WorkflowCurrentStateProjection> | null> {
+  return readRuntimeProjectionEnvelope(projectRoot, WORKFLOW_CURRENT_STATE_PROJECTION_TYPE, workflowRuntimeProjectionScopeKey(branch));
+}
+
+export async function recordTaskOrchestrationProjection(projectRoot: string, resolution: WorkflowStateResolution): Promise<RuntimeProjectionEnvelopeWriteResult<TaskOrchestrationProjection>> {
+  const projection = buildTaskOrchestrationProjection(resolution.model, resolution.generatedAt);
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: TASK_ORCHESTRATION_PROJECTION_TYPE,
+    scopeKey: workflowRuntimeProjectionScopeKey(resolution.branch),
+    inputHash: projection.metadata.inputHash,
+    producer: WORKFLOW_RUNTIME_PROJECTION_PRODUCER,
+    producerVersion: WORKFLOW_RUNTIME_PROJECTION_PRODUCER_VERSION,
+    generatedAt: resolution.generatedAt,
+    payload: projection
+  });
+}
+
+export async function readTaskOrchestrationProjection(projectRoot: string, branch: string): Promise<RuntimeProjectionEnvelope<TaskOrchestrationProjection> | null> {
+  return readRuntimeProjectionEnvelope(projectRoot, TASK_ORCHESTRATION_PROJECTION_TYPE, workflowRuntimeProjectionScopeKey(branch));
+}
+
+export async function recordValidationUnitProjection(projectRoot: string, resolution: WorkflowStateResolution): Promise<RuntimeProjectionEnvelopeWriteResult<ValidationUnitProjection>> {
+  const projection = buildValidationUnitProjection(resolution.model, resolution.generatedAt);
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: VALIDATION_UNIT_PROJECTION_TYPE,
+    scopeKey: workflowRuntimeProjectionScopeKey(resolution.branch),
+    inputHash: projection.metadata.inputHash,
+    producer: WORKFLOW_RUNTIME_PROJECTION_PRODUCER,
+    producerVersion: WORKFLOW_RUNTIME_PROJECTION_PRODUCER_VERSION,
+    generatedAt: resolution.generatedAt,
+    payload: projection
+  });
+}
+
+export async function readValidationUnitProjection(projectRoot: string, branch: string): Promise<RuntimeProjectionEnvelope<ValidationUnitProjection> | null> {
+  return readRuntimeProjectionEnvelope(projectRoot, VALIDATION_UNIT_PROJECTION_TYPE, workflowRuntimeProjectionScopeKey(branch));
+}
+
+export async function recordNextIntentProjection(projectRoot: string, resolution: WorkflowStateResolution): Promise<RuntimeProjectionEnvelopeWriteResult<NextIntentProjection>> {
+  const projection = buildNextIntentProjection(resolution);
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: NEXT_INTENT_PROJECTION_TYPE,
+    scopeKey: workflowRuntimeProjectionScopeKey(resolution.branch),
+    inputHash: stableHash({
+      branch: projection.branch,
+      primary: projection.primary,
+      candidates: projection.candidates,
+      rules: projection.rules
+    }),
+    producer: WORKFLOW_RUNTIME_PROJECTION_PRODUCER,
+    producerVersion: WORKFLOW_RUNTIME_PROJECTION_PRODUCER_VERSION,
+    generatedAt: resolution.generatedAt,
+    payload: projection
+  });
+}
+
+export async function readNextIntentProjection(projectRoot: string, branch: string): Promise<RuntimeProjectionEnvelope<NextIntentProjection> | null> {
+  return readRuntimeProjectionEnvelope(projectRoot, NEXT_INTENT_PROJECTION_TYPE, workflowRuntimeProjectionScopeKey(branch));
+}
+
+export function buildWorkflowCurrentStateProjection(resolution: WorkflowStateResolution): WorkflowCurrentStateProjection {
+  const metadata = runtimeProjectionMetadata(resolution);
+  const taskOrchestration = buildTaskOrchestrationProjection(resolution.model, resolution.generatedAt);
+  const validationUnitProjection = buildValidationUnitProjection(resolution.model, resolution.generatedAt);
+  const runtimeByTask = runtimeByTaskId(resolution);
+  const latestRunByTask = new Map(resolution.latestRunsByTask.map((run) => [run.taskId, run]));
+  return {
+    contract: 'sdd-workflow-current-state-projection-v1',
+    branch: resolution.branch,
+    generatedAt: resolution.generatedAt,
+    writer: 'runtime_sqlite',
+    metadata,
+    lifecycle: lifecycleRuntimeState(resolution),
+    tasks: resolution.model.tasks.map((task) => taskRuntimeState(resolution, task, runtimeByTask.get(task.id) ?? null, latestRunByTask.get(task.id) ?? null)),
+    validationUnits: validationUnitProjection.validationUnits.map((unit) => validationUnitRuntimeState(resolution, unit, runtimeByTask)),
+    taskOrchestration,
+    validationUnitProjection,
+    nextIntentRef: { kind: 'projection', ref: `${NEXT_INTENT_PROJECTION_TYPE}:${workflowRuntimeProjectionScopeKey(resolution.branch)}` }
+  };
+}
+
+export function buildNextIntentProjection(resolution: WorkflowStateResolution): NextIntentProjection {
+  return {
+    contract: 'sdd-next-intent-projection-v1',
+    branch: resolution.branch,
+    advisory: true,
+    generatedAt: resolution.generatedAt,
+    primary: resolution.nextIntent,
+    candidates: nextIntentCandidates(resolution.nextIntent),
+    hostProjections: resolution.nextIntent.hostProjections,
+    rules: {
+      recommendationIsNotAGate: true,
+      executionMustCheckReadiness: true,
+      internalStagesStayBundleScoped: true
+    }
+  };
+}
+
+export function workflowRuntimeProjectionScopeKey(branch: string): string {
+  return branch;
+}
+
+export function evidenceRecordFromPayload(input: { payload: RuntimeArtifactPayloadRecord; evidenceSet?: RuntimeEvidenceSetRecord | null; pointer?: RuntimeSelectionPointerRecord | null }): EvidenceRecord {
+  return {
+    contract: 'sdd-evidence-record-v1',
+    branch: input.payload.branchSlug,
+    scope: { branch: input.payload.branchSlug, taskId: input.payload.taskId ?? undefined, runId: input.payload.runId },
+    logicalRef: { kind: 'artifact', ref: input.payload.logicalRef, hash: input.payload.digest },
+    digest: input.payload.digest,
+    role: input.payload.artifactRole,
+    status: input.evidenceSet?.status ?? input.payload.status,
+    consumable: isConsumableEvidenceStatus(input.evidenceSet?.status ?? input.payload.status),
+    selectedBy: input.pointer ?? null,
+    sourceEvidenceSetId: input.evidenceSet?.evidenceSetId ?? null
+  };
+}
+
+function runtimeProjectionMetadata(resolution: WorkflowStateResolution): RuntimeProjectionMetadata {
+  const inputRefs = workflowInputRefs(resolution.model);
+  return {
+    contract: 'sdd-runtime-projection-metadata-v1',
+    inputRefs,
+    inputHash: stableHash({
+      branch: resolution.branch,
+      documents: resolution.documents,
+      tasks: resolution.model.tasks.map(taskProjectionInput),
+      latestRunsByTask: resolution.latestRunsByTask.map((run) => ({ taskId: run.taskId, runId: run.runId, runStatus: run.runStatus, validationStatus: run.validationStatus, compatibility: run.compatibility })),
+      dependencyBlockers: resolution.dependencyBlockers,
+      blockingReasons: resolution.blockingReasons,
+      truthReconciliation: resolution.truthReconciliation,
+      nextIntent: resolution.nextIntent
+    }),
+    schemaVersion: 'phase9.25-9.29-runtime-projections-v1',
+    projectorVersion: WORKFLOW_RUNTIME_PROJECTION_PRODUCER_VERSION,
+    generatedAt: resolution.generatedAt
+  };
+}
+
+function buildTaskOrchestrationProjection(model: SddTaskModel, generatedAt: string): TaskOrchestrationProjection {
+  const tasks = model.tasks.map((task) => ({
+    taskId: task.id,
+    title: task.title,
+    unitHash: taskUnitHash(task),
+    boundaryHash: stableHash({ boundary: task.boundary, acceptance: task.acceptance }),
+    dependencyHash: stableHash({ dependsOn: task.dependsOn, validationBatch: task.validationBatch, validationTiming: task.validationTiming, wave: task.wave }),
+    capabilityHash: stableHash({ risk: task.risk, agentFit: task.agentFit, allowedAgents: task.allowedAgents, fileOwnership: task.fileOwnership, changeSurface: task.changeSurface }),
+    affectedFilesHash: stableHash(task.affectedFiles),
+    validationUnitId: validationUnitIdForTask(task),
+    validationTiming: task.validationTiming,
+    dependsOn: task.dependsOn,
+    affectedFiles: task.affectedFiles,
+    capabilitySignals: [...new Set([...task.risk, ...task.agentFit, ...task.allowedAgents])].sort(),
+    sourceRef: { kind: 'task' as const, ref: `${projectRelativeRef(task.source.filePath)}#${task.id}`, hash: taskUnitHash(task) }
+  }));
+  return {
+    contract: 'sdd-task-orchestration-projection-v1',
+    branch: model.branch,
+    metadata: {
+      contract: 'sdd-runtime-projection-metadata-v1',
+      inputRefs: workflowInputRefs(model),
+      inputHash: stableHash({ documents: model.documents, tasks: tasks.map((task) => ({ taskId: task.taskId, unitHash: task.unitHash })) }),
+      schemaVersion: 'sdd-task-orchestration-projection-v1',
+      projectorVersion: WORKFLOW_RUNTIME_PROJECTION_PRODUCER_VERSION,
+      generatedAt
+    },
+    tasks
+  };
+}
+
+function buildValidationUnitProjection(model: SddTaskModel, generatedAt: string): ValidationUnitProjection {
+  const units = new Map<string, SddTask[]>();
+  for (const task of model.tasks) {
+    const unitId = validationUnitIdForTask(task);
+    units.set(unitId, [...(units.get(unitId) ?? []), task]);
+  }
+  const validationUnits = [...units.entries()].map(([validationUnitId, tasks]) => ({
+    validationUnitId,
+    unitHash: stableHash(tasks.map((task) => ({ taskId: task.id, validationTiming: task.validationTiming, validationBatch: task.validationBatch, validationCommands: task.validationCommands, acceptanceRefs: task.acceptanceRefs }))),
+    validationTiming: tasks[0]?.validationTiming ?? 'task_end',
+    taskIds: tasks.map((task) => task.id).sort(),
+    commands: [...new Set(tasks.flatMap((task) => task.validation))].sort(),
+    sourceRefs: tasks.map((task) => ({ kind: 'task' as const, ref: `${projectRelativeRef(task.source.filePath)}#${task.id}`, hash: taskUnitHash(task) }))
+  })).sort((left, right) => left.validationUnitId.localeCompare(right.validationUnitId));
+  return {
+    contract: 'sdd-validation-unit-projection-v1',
+    branch: model.branch,
+    metadata: {
+      contract: 'sdd-runtime-projection-metadata-v1',
+      inputRefs: workflowInputRefs(model),
+      inputHash: stableHash({ documents: model.documents, validationUnits: validationUnits.map((unit) => ({ validationUnitId: unit.validationUnitId, unitHash: unit.unitHash })) }),
+      schemaVersion: 'sdd-validation-unit-projection-v1',
+      projectorVersion: WORKFLOW_RUNTIME_PROJECTION_PRODUCER_VERSION,
+      generatedAt
+    },
+    validationUnits
+  };
+}
+
+function lifecycleRuntimeState(resolution: WorkflowStateResolution): LifecycleRuntimeState {
+  return {
+    contract: 'sdd-lifecycle-runtime-state-v1',
+    branch: resolution.branch,
+    currentStage: resolution.workflowStatus === 'not_started' ? 'not_started' : resolution.nextIntent.targetRuntimeStage,
+    status: lifecycleStatus(resolution),
+    writer: 'runtime_sqlite',
+    authority: 'runtime_projection',
+    blockingReasons: resolution.blockingReasons,
+    readiness: {
+      requiredTaskIds: resolution.workflowReadiness.requiredTaskIds,
+      acceptedTaskIds: resolution.workflowReadiness.acceptedTaskIds,
+      missingTaskIds: resolution.workflowReadiness.missingTaskIds,
+      readyForShip: resolution.workflowReadiness.readyForShip
+    },
+    updatedAt: resolution.generatedAt
+  };
+}
+
+function taskRuntimeState(resolution: WorkflowStateResolution, task: SddTask, runtime: RunStateTaskRuntime | null, latestRun: WorkflowLatestTaskRun | null): TaskRuntimeState {
+  const evidenceRefs = [...new Set([...(runtime?.artifacts ?? []), ...(runtime?.evidence ?? []), ...(latestRun ? latestRun.affectedFiles.map((file) => `file:${file}`) : [])])]
+    .map((ref) => ref.startsWith('file:') ? { kind: 'external' as const, ref: ref.slice('file:'.length) } : { kind: 'artifact' as const, ref });
+  return {
+    contract: 'sdd-task-runtime-state-v1',
+    branch: resolution.branch,
+    taskId: task.id,
+    taskHash: taskUnitHash(task),
+    status: taskRuntimeStatus(task, runtime),
+    declaredStatus: task.status,
+    implementationStatus: runtime?.implementationStatus ?? null,
+    verificationStatus: runtime?.verificationStatus ?? null,
+    verifyStatus: runtime?.verifyStatus ?? null,
+    consumability: taskConsumability(task, runtime, latestRun),
+    acceptedRunId: latestRun?.runId ?? null,
+    acceptedEvidenceInputHash: stableHash({ taskHash: taskUnitHash(task), latestRun, runtime: runtime ? { status: runtime.status, implementationStatus: runtime.implementationStatus, verificationStatus: runtime.verificationStatus, verifyStatus: runtime.verifyStatus, artifacts: runtime.artifacts, evidence: runtime.evidence } : null }),
+    evidenceRefs,
+    blockers: taskBlockers(resolution, task.id),
+    updatedAt: resolution.generatedAt
+  };
+}
+
+function validationUnitRuntimeState(resolution: WorkflowStateResolution, unit: ValidationUnitProjectionItem, runtimeByTask: Map<string, RunStateTaskRuntime>): ValidationUnitRuntimeState {
+  const runtimes = unit.taskIds.map((taskId) => runtimeByTask.get(taskId) ?? null);
+  const evidenceRefs = runtimes.flatMap((runtime) => [...(runtime?.artifacts ?? []), ...(runtime?.evidence ?? [])]).map((ref) => ({ kind: 'artifact' as const, ref }));
+  const blockers = unit.taskIds.flatMap((taskId) => taskBlockers(resolution, taskId));
+  return {
+    contract: 'sdd-validation-unit-runtime-state-v1',
+    branch: resolution.branch,
+    validationUnitId: unit.validationUnitId,
+    validationUnitHash: unit.unitHash,
+    taskIds: unit.taskIds,
+    validationTiming: unit.validationTiming,
+    status: validationUnitStatus(runtimes),
+    consumability: blockers.length > 0 ? 'blocked' : validationUnitConsumability(runtimes),
+    evidenceRefs,
+    blockers,
+    updatedAt: resolution.generatedAt
+  };
+}
+
+function nextIntentCandidates(primary: WorkflowNextIntent): NextIntentCandidate[] {
+  const sameBundleBase = sameBundleBaseCandidate(primary);
+  return [
+    nextIntentCandidate(primary, 'recommended', 'Primary advisory route from current runtime state.'),
+    ...(sameBundleBase ? [sameBundleBase] : [])
+  ];
+}
+
+function nextIntentCandidate(intent: WorkflowNextIntent, status: NextIntentCandidateStatus, reason: string): NextIntentCandidate {
+  return {
+    status,
+    bundle: intent.bundle,
+    targetRuntimeStage: intent.targetRuntimeStage,
+    canonicalCommand: intent.canonicalCommand,
+    displayCommand: intent.displayCommand,
+    commandSemantics: intent.commandSemantics,
+    reason,
+    gateStillRequired: true
+  };
+}
+
+function sameBundleBaseCandidate(primary: WorkflowNextIntent): NextIntentCandidate | null {
+  if (primary.targetRuntimeStage === primary.bundle) {
+    return null;
+  }
+  const canonicalCommand = primary.canonicalCommand.replace(/\s+--target\s+\S+/g, '');
+  const displayCommand = primary.displayCommand.replace(/\s+target=\S+/g, '');
+  return {
+    status: 'allowed',
+    bundle: primary.bundle,
+    targetRuntimeStage: primary.bundle,
+    canonicalCommand,
+    displayCommand,
+    commandSemantics: primary.commandSemantics,
+    reason: 'Allowed by nextIntent advisory policy; execution still runs runtime readiness and gate checks.',
+    gateStillRequired: true
+  };
+}
+
+function lifecycleStatus(resolution: WorkflowStateResolution): LifecycleRuntimeStatus {
+  if (resolution.workflowStatus === 'not_started') {
+    return 'not_started';
+  }
+  if (resolution.blockingReasons.length > 0 || resolution.nextIntent.blockingReason) {
+    return 'blocked';
+  }
+  if (resolution.nextIntent.targetRuntimeStage === 'ship' && resolution.workflowReadiness.readyForShip) {
+    return 'ready_for_ship';
+  }
+  return 'active';
+}
+
+function runtimeByTaskId(resolution: WorkflowStateResolution): Map<string, RunStateTaskRuntime> {
+  const result = new Map<string, RunStateTaskRuntime>();
+  for (const state of [resolution.latestRunState].filter((state): state is NonNullable<typeof resolution.latestRunState> => Boolean(state))) {
+    for (const [taskId, runtime] of Object.entries(state.tasks)) {
+      result.set(taskId, runtime);
+    }
+  }
+  return result;
+}
+
+function taskRuntimeStatus(task: SddTask, runtime: RunStateTaskRuntime | null): TaskRuntimeStatus {
+  if (task.status === 'deferred') {
+    return 'deferred';
+  }
+  if (!runtime) {
+    return task.status === 'blocked' ? 'blocked' : task.status === 'pending' ? 'pending' : 'unknown';
+  }
+  if (runtime.status === 'implemented_verified' || runtime.verifyStatus === 'PASS') {
+    return 'implemented_verified';
+  }
+  if (runtime.status === 'implemented_pending_validation' || runtime.implementationStatus === 'implemented') {
+    return 'implemented_pending_validation';
+  }
+  if (runtime.status === 'blocked' || runtime.implementationStatus === 'blocked') {
+    return 'blocked';
+  }
+  return task.status === 'pending' ? 'pending' : 'unknown';
+}
+
+function taskConsumability(task: SddTask, runtime: RunStateTaskRuntime | null, latestRun: WorkflowLatestTaskRun | null): RuntimeConsumability {
+  if (task.status === 'deferred') {
+    return 'not_consumable';
+  }
+  if (!runtime) {
+    return 'not_consumable';
+  }
+  if (latestRun?.compatibility && latestRun.compatibility !== 'compatible') {
+    return 'stale';
+  }
+  if (runtime.status === 'implemented_verified' || runtime.verifyStatus === 'PASS') {
+    return 'consumable';
+  }
+  if (runtime.status === 'blocked' || runtime.implementationStatus === 'blocked' || runtime.verificationStatus === 'blocked') {
+    return 'blocked';
+  }
+  return 'not_consumable';
+}
+
+function validationUnitStatus(runtimes: Array<RunStateTaskRuntime | null>): ValidationUnitRuntimeStatus {
+  if (runtimes.some((runtime) => runtime?.verificationStatus === 'blocked' || runtime?.status === 'blocked')) {
+    return 'blocked';
+  }
+  if (runtimes.length > 0 && runtimes.every((runtime) => runtime?.verifyStatus === 'PASS' || runtime?.status === 'implemented_verified' || runtime?.verificationStatus === 'pass')) {
+    return 'pass';
+  }
+  if (runtimes.some((runtime) => runtime?.verificationStatus === 'pass_with_gaps')) {
+    return 'pass_with_gaps';
+  }
+  if (runtimes.length > 0 && runtimes.every((runtime) => runtime?.implementationStatus === 'implemented' || runtime?.status === 'implemented_pending_validation' || runtime?.status === 'implemented_verified')) {
+    return 'ready';
+  }
+  if (runtimes.some((runtime) => runtime?.verificationStatus === 'failed')) {
+    return 'failed';
+  }
+  return 'not_ready';
+}
+
+function validationUnitConsumability(runtimes: Array<RunStateTaskRuntime | null>): RuntimeConsumability {
+  const status = validationUnitStatus(runtimes);
+  if (status === 'pass') {
+    return 'consumable';
+  }
+  if (status === 'blocked' || status === 'failed') {
+    return 'blocked';
+  }
+  return 'not_consumable';
+}
+
+function taskBlockers(resolution: WorkflowStateResolution, taskId: string): string[] {
+  return [
+    ...resolution.visibleGaps.filter((gap) => gap.taskId === taskId && gap.severity === 'blocking').map((gap) => `${gap.field}: ${gap.message}`),
+    ...resolution.dependencyBlockers.filter((blocker) => blocker.taskId === taskId).map((blocker) => blocker.reason)
+  ];
+}
+
+function validationUnitIdForTask(task: SddTask): string {
+  if ((task.validationTiming === 'batch_end' || task.validationTiming === 'wave_end') && task.validationBatch) {
+    return task.validationBatch;
+  }
+  return task.id;
+}
+
+function workflowInputRefs(model: SddTaskModel): RuntimeRef[] {
+  return [
+    documentRef(projectRelativeRef(model.specPath), model.documents.specHash ?? model.documents.specDocHash ?? null),
+    documentRef(projectRelativeRef(model.planPath), model.documents.planHash ?? model.documents.planDocHash ?? null),
+    documentRef(projectRelativeRef(model.tasksPath), model.documents.tasksHash ?? model.documents.tasksDocHash ?? null),
+    documentRef(projectRelativeRef(model.verifyPath), model.documents.verifyHash ?? model.documents.verifyDocHash ?? null)
+  ].filter((ref): ref is RuntimeRef => ref !== null);
+}
+
+function documentRef(ref: string, hash: string | null): RuntimeRef | null {
+  if (!hash) {
+    return null;
+  }
+  return { kind: 'document', ref, hash };
+}
+
+function projectRelativeRef(ref: string): string {
+  return ref.replace(/\\/g, '/').replace(/^.*?(specs\/[^/]+\/[^/]+\.md)$/, '$1');
+}
+
+function taskProjectionInput(task: SddTask): unknown {
+  return {
+    id: task.id,
+    title: task.title,
+    status: task.status,
+    wave: task.wave,
+    implementationWave: task.implementationWave,
+    validationBatch: task.validationBatch,
+    validationTiming: task.validationTiming,
+    requiresVerifyBeforeNext: task.requiresVerifyBeforeNext,
+    dependsOn: task.dependsOn,
+    affectedFiles: task.affectedFiles,
+    validation: task.validation,
+    risk: task.risk,
+    acceptanceRefs: task.acceptanceRefs,
+    planRefs: task.planRefs,
+    fileOwnership: task.fileOwnership,
+    agentFit: task.agentFit,
+    allowedAgents: task.allowedAgents,
+    boundary: task.boundary,
+    acceptance: task.acceptance
+  };
+}
+
+function taskUnitHash(task: SddTask): string {
+  return stableHash(taskProjectionInput(task));
+}
+
+function isConsumableEvidenceStatus(status: RuntimeArtifactPayloadRecord['status'] | RuntimeEvidenceSetStatus): boolean {
+  return status === 'active' || status === 'accepted';
+}
+
+function stableHash(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}