sdd-agent-platform 0.4.2 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/task-execution-contract.ts

@@ -0,0 +1,566 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
+import type { RuntimeProjectionEnvelope, RuntimeRef } from './contracts.js';
+import { parseSddTasksMarkdown, type SddTask } from './sdd-docs/task-parser.js';
+import { recordRuntimeProjectionEnvelope, readRuntimeProjectionEnvelope, type RuntimeProjectionEnvelopeWriteResult } from './storage/runtime-store.js';
+
+export const TASK_UNIT_PROJECTION_TYPE = 'phase10_1_task_unit_projection';
+export const EXECUTION_LANE_PROJECTION_TYPE = 'phase10_2_execution_lane_projection';
+export const TASK_DEPENDENCY_GRAPH_PROJECTION_TYPE = 'phase10_3_task_dependency_graph_projection';
+const TASK_EXECUTION_CONTRACT_PRODUCER = 'phase10-task-execution-contract';
+const TASK_EXECUTION_CONTRACT_PRODUCER_VERSION = 'phase10.11-task-execution-contract-v1';
+
+export type TaskDependencyState = 'ready' | 'blocked' | 'invalid';
+export type TaskExecutionState = 'pending' | 'implemented' | 'validated';
+export type TaskEvidenceState = 'none' | 'accepted';
+export type TaskWorkType = 'implementation' | 'test' | 'data-correction' | 'migration' | 'config' | 'docs' | 'investigation' | 'review-fix';
+
+export type TaskAgentRoutingBoard = 'implementation' | 'validation';
+export type TaskCheckpointState = 'open' | 'locked' | 'closed' | 'resolved';
+
+export interface TaskUnitRuntimeDetail {
+  unitType: string;
+  agentRouting: {
+    board: TaskAgentRoutingBoard;
+  };
+}
+export interface TaskUnitProjection {
+  contract: 'sdd-task-unit-projection-v1';
+  branch: string;
+  taskId: string;
+  laneId: string;
+  workType: TaskWorkType;
+  unit: TaskUnitRuntimeDetail;
+  checkpointState: TaskCheckpointState;
+  wave: number | null;
+  dependencies: string[];
+  primaryWritableOwnership: string[];
+  touches: string[];
+  rollbackUnit: string | null;
+  sourceRef: RuntimeRef;
+  sourceRequirements: string[];
+  sourceAcceptanceCriteria: string[];
+  planRefs: string[];
+  completionEvidence: string[];
+  validationCoverage: Record<string, unknown>;
+  failureRoute: string | null;
+  dependencyState: TaskDependencyState;
+  executionState: TaskExecutionState;
+  evidenceState: TaskEvidenceState;
+  generatedAt: string;
+}
+
+export interface ExecutionLaneProjection {
+  contract: 'sdd-execution-lane-projection-v1';
+  branch: string;
+  laneId: string;
+  taskIds: string[];
+  generatedAt: string;
+}
+
+export interface TaskDependencyGraphProjection {
+  contract: 'sdd-task-dependency-graph-projection-v1';
+  branch: string;
+  tasksRef: RuntimeRef;
+  tasksHash: string;
+  taskIds: string[];
+  invalidTaskIds: string[];
+  edges: Array<{ from: string; to: string }>;
+  generatedAt: string;
+}
+
+export interface TaskExecutionProjectionBundleInput {
+  branch: string;
+  acceptedTasksRef: RuntimeRef;
+  acceptedTasksHash: string;
+  generatedAt: string;
+}
+
+export type ExecuteTaskKind = 'implementation' | 'validation' | 'investigation' | 'docs' | 'migration' | 'config' | 'data-correction' | 'review-fix';
+export type ExecuteMode = 'change' | 'validate' | 'investigate' | 'document';
+export type HostExecutorProfileId =
+  | 'host-frontend-executor'
+  | 'host-backend-executor'
+  | 'host-database-executor'
+  | 'host-docs-executor'
+  | 'host-validation-executor'
+  | 'host-investigation-executor'
+  | 'host-generic-executor';
+
+export interface HostExecutorProfile {
+  id: HostExecutorProfileId;
+  kind: 'host-executor-profile';
+  role: string;
+  appliesWhen: {
+    taskKinds: ExecuteTaskKind[];
+    primaryLanes: string[];
+    executeModes: ExecuteMode[];
+  };
+  mayEdit: true;
+  mayRunCommands: true;
+  maySpawnImplementationAgent: false;
+  implementationDelegation: 'forbidden';
+  mayCloseRuntimeTask: false;
+  defaultSkills: string[];
+  defaultMaterialPacks: string[];
+  preferredSupportAgents: string[];
+  operatingRules: string[];
+}
+
+export interface HostBoundExecutionWorkOrder {
+  contract: 'sdd-host-execution-work-order-v1';
+  branch: string;
+  taskId: string;
+  acceptedTasksRef: RuntimeRef;
+  acceptedTasksHash: string | null;
+  generatedAt: string;
+  executionSignal: {
+    taskKind: ExecuteTaskKind;
+    primaryLane: string;
+    supportingLanes: string[];
+    executeMode: ExecuteMode;
+  };
+  hostExecutor: {
+    kind: 'host-main-session';
+    profileId: HostExecutorProfileId;
+    mayEdit: true;
+    implementationDelegation: 'forbidden';
+    maySpawnImplementationAgent: false;
+    mayCloseRuntimeTask: false;
+  };
+  taskBrief: {
+    title: string | null;
+    outcome: string | null;
+    currentState: string | null;
+    targetState: string | null;
+    planDecisionToPreserve: string | null;
+    implementationDirection: string[];
+    validationItems: string[];
+    completionEvidence: string[];
+    validationHandoff: string | null;
+  };
+  boundary: {
+    allowedSurfaces: string[];
+    forbiddenSurfaces: string[];
+    overlapOrRollbackNote: string | null;
+  };
+  aci: {
+    whereToStart: string[];
+    whatToChangeFirst: string | null;
+    suggestedChecks: string[];
+    readiness: 'ready' | 'tasks-revise';
+    readinessGaps: string[];
+    feedbackPolicy: {
+      onImplementationDefect: 'execute-repair';
+      onTaskBoundaryGap: 'tasks-revise';
+      onDesignGap: 'plan-revise';
+      onRequirementGap: 'spec-revise';
+    };
+  };
+  supportProfile: {
+    skills: string[];
+    materialPacks: string[];
+    supportAgents: Array<'execute-scout' | 'execute-reviewer' | 'execute-validator'>;
+    supportAgentsMayEdit: false;
+    supportAgentsMayCloseTask: false;
+  };
+  close: {
+    allowedStatuses: Array<'completed' | 'blocked' | 'needs-revision'>;
+    failureRoutes: Array<'execute-repair' | 'tasks-revise' | 'plan-revise' | 'spec-revise'>;
+  };
+}
+
+export interface HostBoundExecutionWorkOrderInput {
+  branch: string;
+  acceptedTasksRef: RuntimeRef;
+  acceptedTasksHash?: string | null;
+  task: SddTask;
+  generatedAt: string;
+}
+
+export const HOST_EXECUTOR_PROFILES: HostExecutorProfile[] = [
+  hostExecutorProfile('host-frontend-executor', 'Implement frontend or UI-facing task changes in the host main session.', ['implementation', 'review-fix'], ['frontend', 'ui', 'ui-design'], ['change'], ['ui-ux-pro-max'], ['frontend-baseline', 'ui-accessibility-checklist'], ['execute-reviewer']),
+  hostExecutorProfile('host-backend-executor', 'Implement backend/API/service task changes in the host main session.', ['implementation', 'review-fix'], ['backend', 'api', 'service'], ['change'], ['systematic-debugging'], ['backend-api-baseline'], ['execute-reviewer']),
+  hostExecutorProfile('host-database-executor', 'Implement database, migration, or data-correction task changes in the host main session.', ['implementation', 'migration', 'data-correction'], ['database', 'db', 'data'], ['change'], ['systematic-debugging'], ['database-change-checklist'], ['execute-reviewer', 'execute-validator']),
+  hostExecutorProfile('host-docs-executor', 'Update documentation or project documents in the host main session.', ['docs'], ['docs', 'documentation'], ['document'], [], ['documentation-guidance'], []),
+  hostExecutorProfile('host-validation-executor', 'Run or inspect validation work in the host main session.', ['validation'], ['validation', 'test', 'qa'], ['validate'], ['verification-before-completion'], ['validation-checklist'], ['execute-validator']),
+  hostExecutorProfile('host-investigation-executor', 'Investigate bounded execution questions in the host main session.', ['investigation'], ['research', 'investigation'], ['investigate'], ['systematic-debugging'], ['investigation-checklist'], ['execute-scout']),
+  hostExecutorProfile('host-generic-executor', 'Execute a bounded project-native task in the host main session.', ['implementation', 'validation', 'investigation', 'docs', 'migration', 'config', 'data-correction', 'review-fix'], ['*'], ['change', 'validate', 'investigate', 'document'], [], ['generic-execution-baseline'], [])
+];
+
+export function buildHostBoundExecutionWorkOrder(input: HostBoundExecutionWorkOrderInput): HostBoundExecutionWorkOrder {
+  const taskKind = executeTaskKind(input.task);
+  const primaryLane = primaryLaneForTask(input.task, taskKind);
+  const executeMode = executeModeFor(taskKind);
+  const profile = selectHostExecutorProfile(taskKind, primaryLane, executeMode);
+  const taskContext = taskReadableContext(input.task);
+  const completionEvidence = uniqueStrings([...listByNames(input.task.rawMetadata, ['completionEvidence', 'completion_evidence']), ...completionEvidenceFromTaskContext(input.task)]);
+  const allowedSurfaces = uniqueStrings([...input.task.fileOwnership, ...listByNames(input.task.rawMetadata, ['allowedSurfaces', 'allowed_surfaces']), ...input.task.affectedFiles]);
+  const forbiddenSurfaces = listByNames(input.task.rawMetadata, ['forbiddenSurfaces', 'forbidden_surfaces']);
+  const whereToStart = uniqueStrings([...listByNames(input.task.rawMetadata, ['whereToStart', 'where_to_start']), ...allowedSurfaces, ...input.task.affectedFiles]);
+  const suggestedChecks = uniqueStrings([...input.task.validationCommands.map((command) => command.command), ...input.task.validation]);
+  const failureRoute = scalarByNames(input.task.rawMetadata, ['failureRoute', 'failure_route']) ?? failureRouteFromTaskContext(taskContext);
+  const readinessGaps = executeReadinessGaps({ allowedSurfaces, completionEvidence, failureRoute, whereToStart, taskContext });
+
+  return {
+    contract: 'sdd-host-execution-work-order-v1',
+    branch: input.branch,
+    taskId: input.task.id,
+    acceptedTasksRef: input.acceptedTasksRef,
+    acceptedTasksHash: input.acceptedTasksHash ?? null,
+    generatedAt: input.generatedAt,
+    executionSignal: {
+      taskKind,
+      primaryLane,
+      supportingLanes: listByNames(input.task.rawMetadata, ['supportingLanes', 'supporting_lanes']),
+      executeMode
+    },
+    hostExecutor: {
+      kind: 'host-main-session',
+      profileId: profile.id,
+      mayEdit: true,
+      implementationDelegation: 'forbidden',
+      maySpawnImplementationAgent: false,
+      mayCloseRuntimeTask: false
+    },
+    taskBrief: {
+      title: input.task.title,
+      outcome: scalarByNames(input.task.rawMetadata, ['outcome', 'taskOutcome', 'task_outcome']),
+      currentState: scalarByNames(input.task.rawMetadata, ['currentState', 'current_state']),
+      targetState: scalarByNames(input.task.rawMetadata, ['targetState', 'target_state']),
+      planDecisionToPreserve: scalarByNames(input.task.rawMetadata, ['planDecisionToPreserve', 'plan_decision_to_preserve']),
+      implementationDirection: uniqueStrings([...listByNames(input.task.rawMetadata, ['implementationDirection', 'implementation_direction']), ...nullableList(input.task.implementationNotes)]),
+      validationItems: suggestedChecks,
+      completionEvidence,
+      validationHandoff: scalarByNames(input.task.rawMetadata, ['coveredBy', 'covered_by', 'validationHandoff', 'validation_handoff'])
+    },
+    boundary: {
+      allowedSurfaces,
+      forbiddenSurfaces,
+      overlapOrRollbackNote: scalarByNames(input.task.rawMetadata, ['overlapOrRollbackNote', 'overlap_or_rollback_note', 'rollbackUnit', 'rollback_unit']) ?? input.task.boundary
+    },
+    aci: {
+      whereToStart,
+      whatToChangeFirst: scalarByNames(input.task.rawMetadata, ['whatToChangeFirst', 'what_to_change_first']),
+      suggestedChecks,
+      readiness: readinessGaps.length > 0 ? 'tasks-revise' : 'ready',
+      readinessGaps,
+      feedbackPolicy: {
+        onImplementationDefect: 'execute-repair',
+        onTaskBoundaryGap: 'tasks-revise',
+        onDesignGap: 'plan-revise',
+        onRequirementGap: 'spec-revise'
+      }
+    },
+    supportProfile: {
+      skills: profile.defaultSkills,
+      materialPacks: profile.defaultMaterialPacks,
+      supportAgents: profile.preferredSupportAgents as Array<'execute-scout' | 'execute-reviewer' | 'execute-validator'>,
+      supportAgentsMayEdit: false,
+      supportAgentsMayCloseTask: false
+    },
+    close: {
+      allowedStatuses: ['completed', 'blocked', 'needs-revision'],
+      failureRoutes: ['execute-repair', 'tasks-revise', 'plan-revise', 'spec-revise']
+    }
+  };
+}
+
+export function selectHostExecutorProfile(taskKind: ExecuteTaskKind, primaryLane: string, executeMode: ExecuteMode): HostExecutorProfile {
+  return HOST_EXECUTOR_PROFILES.find((profile) => profile.id !== 'host-generic-executor' && matchesProfile(profile, taskKind, primaryLane, executeMode)) ?? HOST_EXECUTOR_PROFILES[HOST_EXECUTOR_PROFILES.length - 1];
+}
+
+function hostExecutorProfile(id: HostExecutorProfileId, role: string, taskKinds: ExecuteTaskKind[], primaryLanes: string[], executeModes: ExecuteMode[], defaultSkills: string[], defaultMaterialPacks: string[], preferredSupportAgents: string[]): HostExecutorProfile {
+  return {
+    id,
+    kind: 'host-executor-profile',
+    role,
+    appliesWhen: { taskKinds, primaryLanes, executeModes },
+    mayEdit: true,
+    mayRunCommands: true,
+    maySpawnImplementationAgent: false,
+    implementationDelegation: 'forbidden',
+    mayCloseRuntimeTask: false,
+    defaultSkills,
+    defaultMaterialPacks,
+    preferredSupportAgents,
+    operatingRules: ['Implement only in the host main session.', 'Do not delegate implementation to subagents.', 'Treat support agents and skills as advisory unless runtime explicitly requires them.']
+  };
+}
+
+function matchesProfile(profile: HostExecutorProfile, taskKind: ExecuteTaskKind, primaryLane: string, executeMode: ExecuteMode): boolean {
+  return profile.appliesWhen.taskKinds.includes(taskKind) && profile.appliesWhen.executeModes.includes(executeMode) && (profile.appliesWhen.primaryLanes.includes('*') || profile.appliesWhen.primaryLanes.includes(primaryLane));
+}
+
+function executeReadinessGaps(input: { allowedSurfaces: string[]; completionEvidence: string[]; failureRoute: string | null; whereToStart: string[]; taskContext: string }): string[] {
+  const gaps: string[] = [];
+  if (input.whereToStart.length === 0 && !hasReadableStartContext(input.taskContext)) gaps.push('missing where-to-start context');
+  if (input.allowedSurfaces.length === 0 && !hasReadableBoundaryContext(input.taskContext)) gaps.push('missing change boundary context');
+  if (input.completionEvidence.length === 0 && !hasReadableCompletionContext(input.taskContext)) gaps.push('missing completion evidence context');
+  if (!input.failureRoute && !hasReadableFailureRoute(input.taskContext)) gaps.push('missing failure route context');
+  return gaps;
+}
+
+function taskReadableContext(task: SddTask): string {
+  return [task.boundary, task.implementationNotes, ...task.acceptance].filter((item): item is string => Boolean(item)).join('\n');
+}
+
+function completionEvidenceFromTaskContext(task: SddTask): string[] {
+  return task.acceptance.filter((item) => /evidence|proof|complete|done|pass criteria|expected result|验证|证据|完成|预期/i.test(item));
+}
+
+function failureRouteFromTaskContext(context: string): string | null {
+  return hasReadableFailureRoute(context) ? 'tasks-revise' : null;
+}
+
+function hasReadableStartContext(context: string): boolean {
+  return /where to start|start from|first inspect|begin with|起点|先看|从.*开始/i.test(context);
+}
+
+function hasReadableBoundaryContext(context: string): boolean {
+  return /boundary|scope|allowed|forbidden|do not|must not|rollback|change only|边界|范围|不得|不要|只改|回滚/i.test(context);
+}
+
+function hasReadableCompletionContext(context: string): boolean {
+  return /completion evidence|evidence|proof|pass criteria|expected result|done when|完成证据|证据|预期结果|验收/i.test(context);
+}
+
+function hasReadableFailureRoute(context: string): boolean {
+  return /failure route|failure routing|if .*fail|return to|revise tasks|revise plan|revise spec|environment diagnostic|失败|回到|修复|诊断/i.test(context);
+}
+
+function executeTaskKind(task: SddTask): ExecuteTaskKind {
+  const workType = taskWorkType(task.rawMetadata);
+  if (workType === 'test') return 'validation';
+  return workType;
+}
+
+function executeModeFor(taskKind: ExecuteTaskKind): ExecuteMode {
+  if (taskKind === 'validation') return 'validate';
+  if (taskKind === 'investigation') return 'investigate';
+  if (taskKind === 'docs') return 'document';
+  return 'change';
+}
+
+function primaryLaneForTask(task: SddTask, taskKind: ExecuteTaskKind): string {
+  return scalarByNames(task.rawMetadata, ['executionLane', 'execution_lane', 'primaryLane', 'primary_lane'])
+    ?? laneFromTaskSurface(task)
+    ?? defaultPrimaryLane(taskKind);
+}
+
+function laneFromTaskSurface(task: SddTask): string | null {
+  const unitType = task.unitType?.toLowerCase() ?? '';
+  if (['frontend', 'ui', 'ui-design'].includes(unitType)) return 'frontend';
+  if (['backend', 'api', 'service', 'core'].includes(unitType)) return 'backend';
+  if (['database', 'db', 'data'].includes(unitType)) return 'database';
+  if (task.changeSurface === 'frontend_only') return 'frontend';
+  if (task.changeSurface === 'backend_only' || task.changeSurface === 'cli_only') return 'backend';
+  if (task.changeSurface === 'docs_only') return 'docs';
+  if (task.changeSurface === 'config_only') return 'backend';
+  const surfaces = [...task.affectedFiles, ...task.fileOwnership].join('\n');
+  if (/\.(?:jsp|vue|tsx|jsx|css|scss|less)\b|\/webapp\/|\\webapp\\|frontend|ui|views?\b/i.test(surfaces)) return 'frontend';
+  if (/\.(?:sql)\b|mapper\s+xml|database|db\b/i.test(surfaces)) return 'database';
+  return null;
+}
+
+function defaultPrimaryLane(taskKind: ExecuteTaskKind): string {
+  if (taskKind === 'validation') return 'validation';
+  if (taskKind === 'docs') return 'docs';
+  if (taskKind === 'investigation') return 'research';
+  if (taskKind === 'migration' || taskKind === 'data-correction') return 'database';
+  return 'backend';
+}
+
+function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values.filter((value) => value.length > 0))];
+}
+
+function nullableList(value: string | null): string[] {
+  return value ? [value] : [];
+}
+
+export function taskUnitScopeKey(branch: string, taskId: string): string {
+  return `${branch}:${taskId}`;
+}
+
+export function executionLaneScopeKey(branch: string, laneId: string): string {
+  return `${branch}:${laneId}`;
+}
+
+export function taskDependencyGraphScopeKey(branch: string): string {
+  return branch;
+}
+
+export async function readTaskDependencyGraphProjection(projectRoot: string, branch: string): Promise<RuntimeProjectionEnvelope<TaskDependencyGraphProjection> | null> {
+  return readRuntimeProjectionEnvelope(projectRoot, TASK_DEPENDENCY_GRAPH_PROJECTION_TYPE, taskDependencyGraphScopeKey(branch));
+}
+
+export async function recordTaskExecutionProjectionBundleFromAcceptedTasks(projectRoot: string, input: TaskExecutionProjectionBundleInput): Promise<void> {
+  const tasksPath = `${projectRoot}/${input.acceptedTasksRef.ref}`.replace(/\//g, process.platform === 'win32' ? '\\' : '/');
+  const content = await readFile(tasksPath, 'utf8');
+  const model = parseSddTasksMarkdown(content, { tasksPath });
+  const taskIds = new Set(model.tasks.map((task) => task.id));
+  const taskUnits = model.tasks.map((task) => taskUnitProjection(input.branch, input.acceptedTasksRef, task, taskIds, input.generatedAt));
+  const lanes = executionLaneProjections(input.branch, taskUnits, input.generatedAt);
+  const graph = taskDependencyGraphProjection(input, taskUnits);
+
+  await Promise.all([
+    ...taskUnits.map((unit) => recordTaskUnitProjection(projectRoot, unit)),
+    ...lanes.map((lane) => recordExecutionLaneProjection(projectRoot, lane)),
+    recordTaskDependencyGraphProjection(projectRoot, graph)
+  ]);
+}
+
+function recordTaskUnitProjection(projectRoot: string, projection: TaskUnitProjection): Promise<RuntimeProjectionEnvelopeWriteResult<TaskUnitProjection>> {
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: TASK_UNIT_PROJECTION_TYPE,
+    scopeKey: taskUnitScopeKey(projection.branch, projection.taskId),
+    inputHash: stableHash(projection),
+    producer: TASK_EXECUTION_CONTRACT_PRODUCER,
+    producerVersion: TASK_EXECUTION_CONTRACT_PRODUCER_VERSION,
+    generatedAt: projection.generatedAt,
+    payload: projection
+  });
+}
+
+function recordExecutionLaneProjection(projectRoot: string, projection: ExecutionLaneProjection): Promise<RuntimeProjectionEnvelopeWriteResult<ExecutionLaneProjection>> {
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: EXECUTION_LANE_PROJECTION_TYPE,
+    scopeKey: executionLaneScopeKey(projection.branch, projection.laneId),
+    inputHash: stableHash(projection),
+    producer: TASK_EXECUTION_CONTRACT_PRODUCER,
+    producerVersion: TASK_EXECUTION_CONTRACT_PRODUCER_VERSION,
+    generatedAt: projection.generatedAt,
+    payload: projection
+  });
+}
+
+function recordTaskDependencyGraphProjection(projectRoot: string, projection: TaskDependencyGraphProjection): Promise<RuntimeProjectionEnvelopeWriteResult<TaskDependencyGraphProjection>> {
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: TASK_DEPENDENCY_GRAPH_PROJECTION_TYPE,
+    scopeKey: taskDependencyGraphScopeKey(projection.branch),
+    inputHash: stableHash(projection),
+    producer: TASK_EXECUTION_CONTRACT_PRODUCER,
+    producerVersion: TASK_EXECUTION_CONTRACT_PRODUCER_VERSION,
+    generatedAt: projection.generatedAt,
+    payload: projection
+  });
+}
+
+function taskUnitProjection(branch: string, acceptedTasksRef: RuntimeRef, task: SddTask, taskIds: Set<string>, generatedAt: string): TaskUnitProjection {
+  const dependencies = task.dependsOn;
+  const missingDependencies = dependencies.filter((dependency) => !taskIds.has(dependency));
+  return {
+    contract: 'sdd-task-unit-projection-v1',
+    branch,
+    taskId: task.id,
+    laneId: scalarByNames(task.rawMetadata, ['executionLane', 'execution_lane']) ?? 'code',
+    workType: taskWorkType(task.rawMetadata),
+    unit: {
+      unitType: task.unitType ?? taskWorkType(task.rawMetadata),
+      agentRouting: { board: taskAgentRoutingBoard(task) }
+    },
+    checkpointState: taskCheckpointState(task.rawMetadata),
+    wave: task.wave,
+    dependencies,
+    primaryWritableOwnership: task.fileOwnership,
+    touches: task.affectedFiles,
+    rollbackUnit: scalarByNames(task.rawMetadata, ['rollbackUnit', 'rollback_unit']),
+    sourceRef: acceptedTasksRef,
+    sourceRequirements: listByNames(task.rawMetadata, ['sourceRequirements', 'source_requirements']),
+    sourceAcceptanceCriteria: task.acceptanceRefs,
+    planRefs: task.planRefs,
+    completionEvidence: listByNames(task.rawMetadata, ['completionEvidence', 'completion_evidence']),
+    validationCoverage: validationCoverage(task.rawMetadata),
+    failureRoute: scalarByNames(task.rawMetadata, ['failureRoute', 'failure_route']),
+    dependencyState: missingDependencies.length > 0 ? 'invalid' : 'ready',
+    executionState: task.status === 'completed' ? 'validated' : 'pending',
+    evidenceState: task.status === 'completed' ? 'accepted' : 'none',
+    generatedAt
+  };
+}
+
+function taskWorkType(metadata: Record<string, string | string[]>): TaskWorkType {
+  const value = scalarByNames(metadata, ['workType', 'work_type']);
+  if (value === 'test' || value === 'data-correction' || value === 'migration' || value === 'config' || value === 'docs' || value === 'investigation' || value === 'review-fix') {
+    return value;
+  }
+  return 'implementation';
+}
+
+function taskAgentRoutingBoard(task: SddTask): TaskAgentRoutingBoard {
+  if (task.taskClass === 'validation' || taskWorkType(task.rawMetadata) === 'test') {
+    return 'validation';
+  }
+  return 'implementation';
+}
+
+function taskCheckpointState(metadata: Record<string, string | string[]>): TaskCheckpointState {
+  const value = scalarByNames(metadata, ['checkpointState', 'checkpoint_state']);
+  if (value === 'open' || value === 'locked' || value === 'resolved') {
+    return value;
+  }
+  return 'closed';
+}
+
+function executionLaneProjections(branch: string, taskUnits: TaskUnitProjection[], generatedAt: string): ExecutionLaneProjection[] {
+  const lanes = new Map<string, string[]>();
+  for (const unit of taskUnits) {
+    lanes.set(unit.laneId, [...(lanes.get(unit.laneId) ?? []), unit.taskId]);
+  }
+  return [...lanes.entries()].map(([laneId, taskIds]) => ({
+    contract: 'sdd-execution-lane-projection-v1',
+    branch,
+    laneId,
+    taskIds,
+    generatedAt
+  }));
+}
+
+function taskDependencyGraphProjection(input: TaskExecutionProjectionBundleInput, taskUnits: TaskUnitProjection[]): TaskDependencyGraphProjection {
+  return {
+    contract: 'sdd-task-dependency-graph-projection-v1',
+    branch: input.branch,
+    tasksRef: input.acceptedTasksRef,
+    tasksHash: input.acceptedTasksHash,
+    taskIds: taskUnits.map((unit) => unit.taskId),
+    invalidTaskIds: taskUnits.filter((unit) => unit.dependencyState === 'invalid').map((unit) => unit.taskId),
+    edges: taskUnits.flatMap((unit) => unit.dependencies.map((dependency) => ({ from: dependency, to: unit.taskId }))),
+    generatedAt: input.generatedAt
+  };
+}
+
+function validationCoverage(metadata: Record<string, string | string[]>): Record<string, unknown> {
+  return {
+    coveredBy: listByNames(metadata, ['coveredBy', 'covered_by']),
+    level: scalarByNames(metadata, ['level'])
+  };
+}
+
+function scalarByNames(metadata: Record<string, string | string[]>, names: string[]): string | null {
+  for (const name of names) {
+    const value = metadata[name];
+    if (typeof value === 'string' && value.length > 0) {
+      return value;
+    }
+  }
+  return null;
+}
+
+function listByNames(metadata: Record<string, string | string[]>, names: string[]): string[] {
+  for (const name of names) {
+    const value = metadata[name];
+    if (Array.isArray(value) && value.length > 0) {
+      return value;
+    }
+    if (typeof value === 'string' && value.length > 0) {
+      return [value];
+    }
+  }
+  return [];
+}
+
+function stableHash(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}