sdd-agent-platform 0.4.2 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/verification/validation-wave.ts

@@ -1,556 +1,513 @@
-import { readFile } from 'node:fs/promises';
-import { resolveSddContext } from '../sdd-docs/context.js';
-import { isBackendBuildValidationCommand, isFrontendOnlyTask, parseSddBranch, type SddTask } from '../sdd-docs/task-parser.js';
-import { listRuntimeAcceptanceEvidenceMaps, recordRuntimeValidationEnvironmentSession, recordRuntimeValidationWaveRun, runtimeScopedId, type RuntimeAcceptanceEvidenceMapRecord, type RuntimeValidationWaveStatus } from '../storage/runtime-store.js';
-import { inspectVerifyContract, type VerifyContractInspection } from './verify-contract.js';
-import { runSddTest, type RunSddTestOptions, type SddTestResult, type SddTestStatus } from './test-runtime.js';
-import { evaluateAndRecordWorkflowGateDecision } from '../workflow-gate/evidence-packet.js';
-import type { WorkflowGateDecision, WorkflowGateScope } from '../workflow-gate/types.js';
-
-export const VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION = 'phase-8.17-validation-wave-runtime-v1';
-
-export interface ValidationWaveTaskPlan {
-  taskId: string;
-  wave: number | null;
-  commandCount: number;
-  acceptanceRefs: string[];
-}
-
-export type ValidationWaveSelectionBoundary = 'batch' | 'wave' | 'tasks' | 'all';
-
-interface VerifyBatchPlan {
-  id: string;
-  timing: string | null;
-  tasks: string[];
-  checks: string[];
-  forbiddenValidation: string[];
-  requiredArtifacts: string[];
-  acceptanceMapping: Map<string, string[]>;
-}
-
-export interface VerifyValidationUnit {
-  validationUnitId: string;
-  timing: string | null;
-  taskIds: string[];
-  checks: string[];
-  forbiddenValidation: string[];
-  requiredArtifacts: string[];
-  acceptanceMapping: Record<string, string[]>;
-}
-
-export interface VerifyValidationUnitList {
-  contract: 'sdd-verify-validation-units-v1';
-  branch: string;
-  verifyContract: VerifyContractInspection;
-  units: VerifyValidationUnit[];
-}
-
-export interface ValidationWavePlan {
-  contract: typeof VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION;
-  branch: string;
-  wave: number | null;
-  batchId: string | null;
-  selectionBoundary: ValidationWaveSelectionBoundary;
-  taskIds: string[];
-  tasks: ValidationWaveTaskPlan[];
-  verifyBatches: Array<{ id: string; timing: string | null; tasks: string[]; checks: string[]; forbiddenValidation: string[]; requiredArtifacts: string[]; acceptanceMapping: Record<string, string[]> }>;
-  verifyContract: VerifyContractInspection;
-  status: 'READY' | 'BLOCKED';
-  blockers: string[];
-}
-
-export interface RunValidationWaveOptions {
-  branch?: string | null;
-  wave?: number | null;
-  batchId?: string | null;
-  taskIds?: string[];
-  commandInputsByTask?: Record<string, RunSddTestOptions['commandInputs']>;
-  timeoutMs?: number;
-  approved?: boolean;
-}
-
-export interface ValidationWaveRunResult {
-  contract: typeof VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION;
-  waveRunId: string;
-  environmentSessionId: string;
-  branch: string;
-  status: RuntimeValidationWaveStatus;
-  plan: ValidationWavePlan;
-  taskResults: SddTestResult[];
-  acceptanceEvidence: RuntimeAcceptanceEvidenceMapRecord[];
-  gaps: string[];
-  workflowGateDecision: WorkflowGateDecision | null;
-  next: string;
-}
-
-export async function listVerifyValidationUnits(projectRoot: string, options: { branch?: string | null } = {}): Promise<VerifyValidationUnitList> {
-  const context = await resolveSddContext(projectRoot, { branch: options.branch ?? undefined, branchSource: options.branch ? 'cli_option' : undefined });
-  const verifyContract = await inspectVerifyContract(projectRoot, { branch: context.partition, branchSource: 'cli_option' });
-  const verifyBatches = await readVerifyBatchPlans(verifyContract);
-  return {
-    contract: 'sdd-verify-validation-units-v1',
-    branch: context.partition,
-    verifyContract,
-    units: Array.from(verifyBatches.values()).map(verifyValidationUnitFromBatch)
-  };
-}
-
-
-export async function planValidationWave(projectRoot: string, options: RunValidationWaveOptions = {}): Promise<ValidationWavePlan> {
-  const context = await resolveSddContext(projectRoot, { branch: options.branch ?? undefined, branchSource: options.branch ? 'cli_option' : undefined });
-  const model = await parseSddBranch(projectRoot, context.partition);
-  const verifyContract = await inspectVerifyContract(projectRoot, { branch: context.partition, branchSource: 'cli_option' });
-  const verifyBatches = await readVerifyBatchPlans(verifyContract);
-  const selectedTasks = selectValidationTasks(model.tasks, options, verifyBatches);
-  const selectionBoundary = validationSelectionBoundary(options);
-  const selectedBatchId = selectedValidationBatchId(options, selectedTasks);
-  const selectedVerifyBatches = selectedBatchesForTasks(selectedTasks, selectedBatchId, verifyBatches);
-  const selectedTaskIds = new Set(selectedTasks.map((task) => task.id));
-  const explicitTaskBlockers = explicitTaskCoverageBlockersForOptions(model.tasks, options, selectedTaskIds, verifyBatches);
-  const taskGapBlockers = model.gaps
-    .filter((gap) => gap.severity === 'blocking' && gap.taskId !== null && selectedTaskIds.has(gap.taskId))
-    .map((gap) => `${gap.field}: ${gap.message}`);
-  const blockers = [
-    ...(verifyContract.status === 'PASS' ? [] : [`verify.md contract is ${verifyContract.status}; run /sdd:tasks or sdd verifies write before /sdd:test.`]),
-    ...(options.batchId && !verifyBatches.has(options.batchId) ? [`verify.md does not declare verification_batch ${options.batchId}.`] : []),
-    ...(selectedTasks.length === 0 ? ['No tasks matched the validation wave selection.'] : []),
-    ...explicitTaskBlockers,
-    ...taskGapBlockers,
-    ...selectedTasks.filter((task) => task.validation.length === 0).map((task) => `Task ${task.id} has no validation commands.`),
-    ...verifyBatchContractBlockers(selectedTasks, selectedVerifyBatches)
-  ];
-  return {
-    contract: VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION,
-    branch: context.partition,
-    wave: options.wave ?? null,
-    batchId: selectedBatchId,
-    selectionBoundary,
-    taskIds: selectedTasks.map((task) => task.id),
-    tasks: selectedTasks.map((task) => ({ taskId: task.id, wave: task.wave, commandCount: task.validation.length, acceptanceRefs: acceptanceRefsForTask(task, selectedVerifyBatches) })),
-    verifyBatches: selectedVerifyBatches.map(serializeVerifyBatchPlan),
-    verifyContract,
-    status: blockers.length > 0 ? 'BLOCKED' : 'READY',
-    blockers
-  };
-}
-
-export async function runValidationWave(projectRoot: string, options: RunValidationWaveOptions = {}): Promise<ValidationWaveRunResult> {
-  const plan = await planValidationWave(projectRoot, options);
-  const startedAt = new Date().toISOString();
-  const waveRunId = runtimeScopedId(plan.branch, plan.batchId ?? plan.taskIds.join(','), String(options.wave ?? 'all'), startedAt, 'validation-wave');
-  const environmentSessionId = runtimeScopedId(plan.branch, waveRunId, 'validation-env');
-  await recordRuntimeValidationEnvironmentSession(projectRoot, {
-    sessionId: environmentSessionId,
-    partition: plan.branch,
-    runId: null,
-    waveRunId,
-    status: plan.status === 'READY' ? 'active' : 'blocked',
-    reuseKey: validationEnvironmentReuseKey(plan),
-    createdAt: startedAt,
-    updatedAt: startedAt,
-    payload: { contract: VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION, taskIds: plan.taskIds, wave: plan.wave, batchId: plan.batchId }
-  });
-  await recordRuntimeValidationWaveRun(projectRoot, {
-    waveRunId,
-    partition: plan.branch,
-    runId: null,
-    taskIds: plan.taskIds,
-    status: plan.status === 'READY' ? 'RUNNING' : 'BLOCKED',
-    environmentSessionId,
-    startedAt,
-    completedAt: startedAt,
-    payload: { contract: VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION, plan }
-  });
-
-  const taskResults: SddTestResult[] = [];
-  const acceptanceRefsByTask = acceptanceRefsByTaskFromBatches(plan.verifyBatches);
-  if (plan.status === 'READY') {
-    for (const taskId of plan.taskIds) {
-      taskResults.push(await runSddTest(projectRoot, {
-        taskId,
-        branch: plan.branch,
-        commandInputs: options.commandInputsByTask?.[taskId],
-        timeoutMs: options.timeoutMs,
-        approved: options.approved,
-        validationWave: { waveRunId, environmentSessionId, taskIds: plan.taskIds, acceptanceRefsByTask }
-      }));
-    }
-  }
-
-  const completedAt = new Date().toISOString();
-  const validationStatus = plan.status === 'BLOCKED' ? 'BLOCKED' : deriveWaveStatus(taskResults.map((result) => result.status));
-  const gaps = [...plan.blockers, ...taskResults.flatMap((result) => result.gaps)];
-  const workflowGateDecision = validationStatus === 'PASS'
-    ? (await evaluateAndRecordWorkflowGateDecision(projectRoot, {
-      branch: plan.branch,
-      taskId: taskResults[0]?.taskId ?? plan.taskIds[0] ?? null,
-      runId: taskResults[0]?.runId ?? null,
-      decisionKind: 'validation_wave',
-      waveRunId,
-      taskIds: plan.taskIds,
-      runIds: taskResults.map((result) => result.runId),
-      evidenceRefs: taskResults.flatMap((result) => [result.validationArtifact].filter((ref): ref is string => Boolean(ref)))
-    })).decision
-    : null;
-  const status = finalWaveStatus(validationStatus, workflowGateDecision);
-  await recordRuntimeValidationWaveRun(projectRoot, {
-    waveRunId,
-    partition: plan.branch,
-    runId: taskResults[0]?.runId ?? null,
-    taskIds: plan.taskIds,
-    status,
-    environmentSessionId,
-    startedAt,
-    completedAt,
-    payload: { contract: VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION, plan, validationStatus, workflowGateDecision, workflowScope: workflowScopeFromGateDecision(workflowGateDecision), taskResults: taskResults.map((result) => ({ taskId: result.taskId, runId: result.runId, testRunId: result.testRunId, status: result.status, workflowGateStatus: result.workflowGateStatus })), gaps }
-  });
-  await recordRuntimeValidationEnvironmentSession(projectRoot, {
-    sessionId: environmentSessionId,
-    partition: plan.branch,
-    runId: taskResults[0]?.runId ?? null,
-    waveRunId,
-    status: status === 'PASS' ? 'completed' : status === 'FAIL' ? 'failed' : 'blocked',
-    reuseKey: validationEnvironmentReuseKey(plan),
-    createdAt: startedAt,
-    updatedAt: completedAt,
-    payload: { contract: VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION, taskIds: plan.taskIds, wave: plan.wave, batchId: plan.batchId, validationStatus, workflowGateStatus: workflowGateDecision?.status ?? 'none', status }
-  });
-  const acceptanceEvidence = await listRuntimeAcceptanceEvidenceMaps(projectRoot, { partition: plan.branch, waveRunId });
-  return {
-    contract: VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION,
-    waveRunId,
-    environmentSessionId,
-    branch: plan.branch,
-    status,
-    plan,
-    taskResults,
-    acceptanceEvidence,
-    gaps,
-    workflowGateDecision,
-    next: nextForValidationWave(status, plan.branch, plan.selectionBoundary, plan.batchId, plan.wave, plan.taskIds, workflowGateDecision)
-  };
-}
-
-export function renderValidationWaveResult(result: ValidationWaveRunResult): string {
-  return [
-    `SDD validation ${result.plan.batchId ? `batch ${result.plan.batchId}` : `wave ${result.plan.wave ?? 'all'}`}`,
-    '',
-    `status=${result.status}`,
-    `branch=${result.branch}`,
-    `wave_run=${result.waveRunId}`,
-    `environment_session=${result.environmentSessionId}`,
-    `batch=${result.plan.batchId ?? 'none'}`,
-    `tasks=${result.plan.taskIds.join(',') || 'none'}`,
-    `acceptance_maps=${result.acceptanceEvidence.length}`,
-    `workflow_gate=${result.workflowGateDecision ? `${result.workflowGateDecision.status}:${result.workflowGateDecision.decisionId}` : 'none'}`,
-    '',
-    'Gaps:',
-    result.gaps.length > 0 ? result.gaps.map((gap) => `- ${gap}`).join('\n') : '- none',
-    '',
-    'Next:',
-    `- ${result.next}`
-  ].join('\n');
-}
-
-function selectValidationTasks(tasks: SddTask[], options: RunValidationWaveOptions, verifyBatches: Map<string, VerifyBatchPlan>): SddTask[] {
-  const explicit = new Set(options.taskIds ?? []);
-  if (explicit.size > 0) {
-    return tasks.filter((task) => explicit.has(task.id) && verifyBatchIncludesTask(verifyBatches, task.id));
-  }
-  if (options.batchId) {
-    const batchTasks = new Set(verifyBatches.get(options.batchId)?.tasks ?? []);
-    return tasks.filter((task) => batchTasks.has(task.id));
-  }
-  if (options.wave !== undefined && options.wave !== null) {
-    const verifyTaskIds = new Set(Array.from(verifyBatches.values()).flatMap((batch) => batch.tasks));
-    return tasks.filter((task) => task.wave === options.wave && verifyTaskIds.has(task.id));
-  }
-  const batchIds = new Set(verifyBatches.keys());
-  if (batchIds.size > 0) {
-    return tasks.filter((task) => task.validationBatch && batchIds.has(task.validationBatch));
-  }
-  return [];
-}
-
-function validationSelectionBoundary(options: RunValidationWaveOptions): ValidationWaveSelectionBoundary {
-  if (options.batchId) {
-    return 'batch';
-  }
-  if (options.wave !== undefined && options.wave !== null) {
-    return 'wave';
-  }
-  if ((options.taskIds ?? []).length > 0) {
-    return 'tasks';
-  }
-  return 'all';
-}
-
-function explicitTaskCoverageBlockersForOptions(tasks: SddTask[], options: RunValidationWaveOptions, selectedTaskIds: Set<string>, verifyBatches: Map<string, VerifyBatchPlan>): string[] {
-  const requestedTaskIds = [...new Set(options.taskIds ?? [])];
-  if (requestedTaskIds.length === 0) {
-    return [];
-  }
-  const taskById = new Map(tasks.map((task) => [task.id, task]));
-  return requestedTaskIds.flatMap((taskId) => {
-    if (selectedTaskIds.has(taskId)) {
-      return [];
-    }
-    if (!taskById.has(taskId)) {
-      return [`Task ${taskId} was requested but was not found in tasks.md.`];
-    }
-    if (!verifyBatchIncludesTask(verifyBatches, taskId)) {
-      return [`Task ${taskId} was requested but is not covered by verify.md verification batches.`];
-    }
-    return [`Task ${taskId} was requested but was not selected for validation.`];
-  });
-}
-
-function selectedValidationBatchId(options: RunValidationWaveOptions, tasks: SddTask[]): string | null {
-  if (options.batchId) {
-    return options.batchId;
-  }
-  const batchIds = [...new Set(tasks.map((task) => task.validationBatch).filter((value): value is string => Boolean(value)))];
-  return batchIds.length === 1 ? batchIds[0] : null;
-}
-
-async function readVerifyBatchPlans(inspection: VerifyContractInspection): Promise<Map<string, VerifyBatchPlan>> {
-  if (!inspection.exists) {
-    return new Map();
-  }
-  const raw = await readFile(inspection.verifyPath, 'utf8');
-  const batches = new Map<string, VerifyBatchPlan>();
-  let currentBatch: VerifyBatchPlan | null = null;
-  let activeList: 'tasks' | 'checks' | 'forbiddenValidation' | 'requiredArtifacts' | null = null;
-  let inAcceptanceMapping = false;
-  let currentAcceptanceTask: string | null = null;
-
-  for (const line of raw.split(/\r?\n/)) {
-    const batchMatch = line.match(/^  - id: "?([^"\n]+)"?$/);
-    if (batchMatch) {
-      currentBatch = { id: batchMatch[1], timing: null, tasks: [], checks: [], forbiddenValidation: [], requiredArtifacts: [], acceptanceMapping: new Map() };
-      batches.set(currentBatch.id, currentBatch);
-      activeList = null;
-      inAcceptanceMapping = false;
-      currentAcceptanceTask = null;
-      continue;
-    }
-    if (!currentBatch) {
-      continue;
-    }
-
-    const timingMatch = line.match(/^    timing: "?([^"\n]+)"?$/);
-    if (timingMatch) {
-      currentBatch.timing = timingMatch[1];
-      continue;
-    }
-
-    if (line === '    tasks:') {
-      activeList = 'tasks';
-      inAcceptanceMapping = false;
-      currentAcceptanceTask = null;
-      continue;
-    }
-    if (line === '    checks:') {
-      activeList = 'checks';
-      inAcceptanceMapping = false;
-      currentAcceptanceTask = null;
-      continue;
-    }
-    if (line === '    forbidden_validation:') {
-      activeList = 'forbiddenValidation';
-      inAcceptanceMapping = false;
-      currentAcceptanceTask = null;
-      continue;
-    }
-    if (line === '    required_artifacts:') {
-      activeList = 'requiredArtifacts';
-      inAcceptanceMapping = false;
-      currentAcceptanceTask = null;
-      continue;
-    }
-    if (line === '    acceptance_mapping:') {
-      activeList = null;
-      inAcceptanceMapping = true;
-      currentAcceptanceTask = null;
-      continue;
-    }
-    if (/^    [a-z_]+:/.test(line)) {
-      activeList = null;
-      inAcceptanceMapping = false;
-      currentAcceptanceTask = null;
-      continue;
-    }
-
-    if (activeList !== null) {
-      const listMatch = line.match(/^      - (.+)$/);
-      if (listMatch) {
-        currentBatch[activeList].push(cleanYamlScalar(listMatch[1]));
-        continue;
-      }
-    }
-
-    if (inAcceptanceMapping) {
-      const taskMatch = line.match(/^      ([^:]+):\s*$/);
-      if (taskMatch) {
-        currentAcceptanceTask = cleanYamlScalar(taskMatch[1]);
-        currentBatch.acceptanceMapping.set(currentAcceptanceTask, []);
-        continue;
-      }
-      if (currentAcceptanceTask !== null) {
-        const refMatch = line.match(/^        - (.+)$/);
-        if (refMatch) {
-          currentBatch.acceptanceMapping.get(currentAcceptanceTask)?.push(cleanYamlScalar(refMatch[1]));
-        }
-      }
-    }
-  }
-  return batches;
-}
-
-function verifyBatchContractBlockers(tasks: SddTask[], batches: VerifyBatchPlan[]): string[] {
-  const taskById = new Map(tasks.map((task) => [task.id, task]));
-  const blockers: string[] = [];
-  const forbiddenBackendBuild = batches.some((batch) => batch.forbiddenValidation.some(isBackendBuildValidationCommand));
-  for (const batch of batches) {
-    for (const taskId of batch.tasks) {
-      const task = taskById.get(taskId);
-      if (!task) {
-        continue;
-      }
-      const mappedAcceptance = batch.acceptanceMapping.get(taskId) ?? [];
-      for (const ref of mappedAcceptance) {
-        if (!task.acceptanceRefs.includes(ref) && !task.acceptance.includes(ref)) {
-          blockers.push(`verify.md batch ${batch.id} maps ${taskId} to unknown acceptance ${ref}.`);
-        }
-      }
-      for (const artifact of batch.requiredArtifacts) {
-        if (task.requiredArtifacts.length > 0 && !task.requiredArtifacts.includes(artifact)) {
-          blockers.push(`verify.md batch ${batch.id} requires artifact ${artifact} that task ${taskId} does not declare.`);
-        }
-      }
-      if (batch.forbiddenValidation.some(isBackendBuildValidationCommand) && task.validation.some(isBackendBuildValidationCommand)) {
-        blockers.push(`Task ${task.id} declares backend build validation forbidden by verify.md batch ${batch.id}.`);
-      }
-      if ((task.changeSurface === 'frontend_only' || isFrontendOnlyTask(task)) && task.validation.some(isBackendBuildValidationCommand) && forbiddenBackendBuild) {
-        blockers.push(`Task ${task.id} is frontend_only but declares backend build validation forbidden by its verification batch.`);
-      }
-    }
-  }
-  return blockers;
-}
-
-function acceptanceRefsForTask(task: SddTask, batches: VerifyBatchPlan[]): string[] {
-  const mappedRefs = batches.flatMap((batch) => batch.acceptanceMapping.get(task.id) ?? []);
-  const refs = mappedRefs.length > 0 ? mappedRefs : task.acceptanceRefs.length > 0 ? task.acceptanceRefs : task.acceptance;
-  return [...new Set(refs)];
-}
-
-function acceptanceRefsByTaskFromBatches(batches: ValidationWavePlan['verifyBatches']): Record<string, string[]> {
-  const refsByTask = new Map<string, string[]>();
-  for (const batch of batches) {
-    for (const [taskId, refs] of Object.entries(batch.acceptanceMapping)) {
-      refsByTask.set(taskId, [...new Set([...(refsByTask.get(taskId) ?? []), ...refs])]);
-    }
-  }
-  return Object.fromEntries(refsByTask);
-}
-
-function selectedBatchesForTasks(tasks: SddTask[], selectedBatchId: string | null, verifyBatches: Map<string, VerifyBatchPlan>): VerifyBatchPlan[] {
-  if (selectedBatchId) {
-    return [verifyBatches.get(selectedBatchId)].filter((batch): batch is VerifyBatchPlan => Boolean(batch));
-  }
-  const selectedTaskIds = new Set(tasks.map((task) => task.id));
-  return Array.from(verifyBatches.values()).filter((batch) => batch.tasks.some((taskId) => selectedTaskIds.has(taskId)));
-}
-
-function verifyBatchIncludesTask(verifyBatches: Map<string, VerifyBatchPlan>, taskId: string): boolean {
-  return Array.from(verifyBatches.values()).some((batch) => batch.tasks.includes(taskId));
-}
-
-function serializeVerifyBatchPlan(batch: VerifyBatchPlan): ValidationWavePlan['verifyBatches'][number] {
-  return {
-    id: batch.id,
-    timing: batch.timing,
-    tasks: batch.tasks,
-    checks: batch.checks,
-    forbiddenValidation: batch.forbiddenValidation,
-    requiredArtifacts: batch.requiredArtifacts,
-    acceptanceMapping: Object.fromEntries(batch.acceptanceMapping)
-  };
-}
-
-
-function verifyValidationUnitFromBatch(batch: VerifyBatchPlan): VerifyValidationUnit {
-  return {
-    validationUnitId: batch.id,
-    timing: batch.timing,
-    taskIds: batch.tasks,
-    checks: batch.checks,
-    forbiddenValidation: batch.forbiddenValidation,
-    requiredArtifacts: batch.requiredArtifacts,
-    acceptanceMapping: Object.fromEntries(batch.acceptanceMapping)
-  };
-}
-
-function cleanYamlScalar(value: string): string {
-  const trimmed = value.trim();
-  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
-    try {
-      return JSON.parse(trimmed) as string;
-    } catch {
-      return trimmed.slice(1, -1);
-    }
-  }
-  if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
-    return trimmed.slice(1, -1);
-  }
-  return trimmed;
-}
-
-function deriveWaveStatus(statuses: SddTestStatus[]): RuntimeValidationWaveStatus {
-  if (statuses.length === 0 || statuses.some((status) => status === 'BLOCKED')) {
-    return 'BLOCKED';
-  }
-  if (statuses.some((status) => status === 'FAIL')) {
-    return 'FAIL';
-  }
-  return 'PASS';
-}
-
-function validationEnvironmentReuseKey(plan: ValidationWavePlan): string {
-  return `${plan.branch}:${plan.batchId ?? plan.wave ?? 'all'}:${plan.taskIds.join(',')}`;
-}
-
-function workflowScopeFromGateDecision(decision: WorkflowGateDecision | null): WorkflowGateScope | null {
-  if (!decision?.payload || typeof decision.payload !== 'object') {
-    return null;
-  }
-  return ((decision.payload as { workflowScope?: WorkflowGateScope }).workflowScope) ?? null;
-}
-
-function finalWaveStatus(validationStatus: RuntimeValidationWaveStatus, workflowGateDecision: WorkflowGateDecision | null): RuntimeValidationWaveStatus {
-  if (validationStatus !== 'PASS') {
-    return validationStatus;
-  }
-  return workflowGateDecision?.status === 'PASS' ? 'PASS' : 'BLOCKED';
-}
-
-function nextForValidationWave(status: RuntimeValidationWaveStatus, branch: string, selectionBoundary: ValidationWaveSelectionBoundary, batchId: string | null, wave: number | null, taskIds: string[], workflowGateDecision: WorkflowGateDecision | null): string {
-  if (status === 'PASS') {
-    return `sdd test close --branch ${branch} --target goal-verify --compact-json`;
-  }
-  if (workflowGateDecision && workflowGateDecision.status !== 'PASS') {
-    return `Inspect validation wave gate ${workflowGateDecision.decisionId}, resolve blockers or decision-card requirements, then rerun ${rerunValidationCommand(branch, selectionBoundary, batchId, wave, taskIds)}.`;
-  }
-  return `Inspect validation wave evidence, fix blocked or failed tasks, then rerun ${rerunValidationCommand(branch, selectionBoundary, batchId, wave, taskIds)}.`;
-}
-
-function rerunValidationCommand(branch: string, selectionBoundary: ValidationWaveSelectionBoundary, batchId: string | null, wave: number | null, taskIds: string[]): string {
-  if (selectionBoundary === 'batch' && batchId) {
-    return `sdd test ${batchId} --branch ${branch}`;
-  }
-  if (selectionBoundary === 'tasks' && taskIds.length > 0) {
-    return `sdd test ${taskIds.length === 1 ? `task-${taskIds[0]}` : taskIds.map((taskId) => `task-${taskId}`).join(',')} --branch ${branch}`;
-  }
-  return wave === null ? `sdd test wave-all --branch ${branch}` : `sdd test wave-${wave} --branch ${branch}`;
-}
+import { readFile } from 'node:fs/promises';
+import { resolveSddContext } from '../sdd-docs/context.js';
+import { isBackendBuildValidationCommand, isFrontendOnlyTask, parseSddBranch, type SddTask } from '../sdd-docs/task-parser.js';
+import { listRuntimeAcceptanceEvidenceMaps, recordRuntimeValidationEnvironmentSession, recordRuntimeValidationWaveRun, runtimeScopedId, type RuntimeAcceptanceEvidenceMapRecord, type RuntimeValidationWaveStatus } from '../storage/runtime-store.js';
+import { inspectVerifyContract, type VerifyContractInspection } from './verify-contract.js';
+import { runSddTest, type RunSddTestOptions, type SddTestResult, type SddTestStatus } from './test-runtime.js';
+import { evaluateAndRecordWorkflowGateDecision } from '../workflow-gate/evidence-packet.js';
+import type { WorkflowGateDecision, WorkflowGateScope } from '../workflow-gate/types.js';
+
+export const VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION = 'phase-8.17-validation-wave-runtime-v1';
+
+export interface ValidationWaveTaskPlan {
+  taskId: string;
+  wave: number | null;
+  commandCount: number;
+  acceptanceRefs: string[];
+}
+
+export type ValidationWaveSelectionBoundary = 'batch' | 'wave' | 'tasks' | 'all';
+
+interface VerifyBatchPlan {
+  id: string;
+  timing: string | null;
+  tasks: string[];
+  checks: string[];
+  forbiddenValidation: string[];
+  requiredArtifacts: string[];
+  acceptanceMapping: Map<string, string[]>;
+}
+
+export interface ValidationWavePlan {
+  contract: typeof VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION;
+  branch: string;
+  wave: number | null;
+  batchId: string | null;
+  selectionBoundary: ValidationWaveSelectionBoundary;
+  taskIds: string[];
+  tasks: ValidationWaveTaskPlan[];
+  verifyBatches: Array<{ id: string; timing: string | null; tasks: string[]; checks: string[]; forbiddenValidation: string[]; requiredArtifacts: string[]; acceptanceMapping: Record<string, string[]> }>;
+  verifyContract: VerifyContractInspection;
+  status: 'READY' | 'BLOCKED';
+  blockers: string[];
+}
+
+export interface RunValidationWaveOptions {
+  branch?: string | null;
+  wave?: number | null;
+  batchId?: string | null;
+  taskIds?: string[];
+  commandInputsByTask?: Record<string, RunSddTestOptions['commandInputs']>;
+  timeoutMs?: number;
+  approved?: boolean;
+}
+
+export interface ValidationWaveRunResult {
+  contract: typeof VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION;
+  waveRunId: string;
+  environmentSessionId: string;
+  branch: string;
+  status: RuntimeValidationWaveStatus;
+  plan: ValidationWavePlan;
+  taskResults: SddTestResult[];
+  acceptanceEvidence: RuntimeAcceptanceEvidenceMapRecord[];
+  gaps: string[];
+  workflowGateDecision: WorkflowGateDecision | null;
+  next: string;
+}
+
+export async function planValidationWave(projectRoot: string, options: RunValidationWaveOptions = {}): Promise<ValidationWavePlan> {
+  const context = await resolveSddContext(projectRoot, { branch: options.branch ?? undefined, branchSource: options.branch ? 'cli_option' : undefined });
+  const model = await parseSddBranch(projectRoot, context.partition);
+  const verifyContract = await inspectVerifyContract(projectRoot, { branch: context.partition, branchSource: 'cli_option' });
+  const verifyBatches = await readVerifyBatchPlans(verifyContract);
+  const selectedTasks = selectValidationTasks(model.tasks, options, verifyBatches);
+  const selectionBoundary = validationSelectionBoundary(options);
+  const selectedBatchId = selectedValidationBatchId(options, selectedTasks);
+  const selectedVerifyBatches = selectedBatchesForTasks(selectedTasks, selectedBatchId, verifyBatches);
+  const selectedTaskIds = new Set(selectedTasks.map((task) => task.id));
+  const explicitTaskBlockers = explicitTaskCoverageBlockersForOptions(model.tasks, options, selectedTaskIds, verifyBatches);
+  const taskGapBlockers = model.gaps
+    .filter((gap) => gap.severity === 'blocking' && gap.taskId !== null && selectedTaskIds.has(gap.taskId))
+    .map((gap) => `${gap.field}: ${gap.message}`);
+  const blockers = [
+    ...(verifyContract.status === 'PASS' ? [] : [`verify.md contract is ${verifyContract.status}; run /sdd:tasks or sdd verifies write before /sdd:test.`]),
+    ...(options.batchId && !verifyBatches.has(options.batchId) ? [`verify.md does not declare verification_batch ${options.batchId}.`] : []),
+    ...(selectedTasks.length === 0 ? ['No tasks matched the validation wave selection.'] : []),
+    ...explicitTaskBlockers,
+    ...taskGapBlockers,
+    ...selectedTasks.filter((task) => task.validation.length === 0).map((task) => `Task ${task.id} has no validation commands.`),
+    ...verifyBatchContractBlockers(selectedTasks, selectedVerifyBatches)
+  ];
+  return {
+    contract: VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION,
+    branch: context.partition,
+    wave: options.wave ?? null,
+    batchId: selectedBatchId,
+    selectionBoundary,
+    taskIds: selectedTasks.map((task) => task.id),
+    tasks: selectedTasks.map((task) => ({ taskId: task.id, wave: task.wave, commandCount: task.validation.length, acceptanceRefs: acceptanceRefsForTask(task, selectedVerifyBatches) })),
+    verifyBatches: selectedVerifyBatches.map(serializeVerifyBatchPlan),
+    verifyContract,
+    status: blockers.length > 0 ? 'BLOCKED' : 'READY',
+    blockers
+  };
+}
+
+export async function runValidationWave(projectRoot: string, options: RunValidationWaveOptions = {}): Promise<ValidationWaveRunResult> {
+  const plan = await planValidationWave(projectRoot, options);
+  const startedAt = new Date().toISOString();
+  const waveRunId = runtimeScopedId(plan.branch, plan.batchId ?? plan.taskIds.join(','), String(options.wave ?? 'all'), startedAt, 'validation-wave');
+  const environmentSessionId = runtimeScopedId(plan.branch, waveRunId, 'validation-env');
+  await recordRuntimeValidationEnvironmentSession(projectRoot, {
+    sessionId: environmentSessionId,
+    partition: plan.branch,
+    runId: null,
+    waveRunId,
+    status: plan.status === 'READY' ? 'active' : 'blocked',
+    reuseKey: validationEnvironmentReuseKey(plan),
+    createdAt: startedAt,
+    updatedAt: startedAt,
+    payload: { contract: VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION, taskIds: plan.taskIds, wave: plan.wave, batchId: plan.batchId }
+  });
+  await recordRuntimeValidationWaveRun(projectRoot, {
+    waveRunId,
+    partition: plan.branch,
+    runId: null,
+    taskIds: plan.taskIds,
+    status: plan.status === 'READY' ? 'RUNNING' : 'BLOCKED',
+    environmentSessionId,
+    startedAt,
+    completedAt: startedAt,
+    payload: { contract: VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION, plan }
+  });
+
+  const taskResults: SddTestResult[] = [];
+  const acceptanceRefsByTask = acceptanceRefsByTaskFromBatches(plan.verifyBatches);
+  if (plan.status === 'READY') {
+    for (const taskId of plan.taskIds) {
+      taskResults.push(await runSddTest(projectRoot, {
+        taskId,
+        branch: plan.branch,
+        commandInputs: options.commandInputsByTask?.[taskId],
+        timeoutMs: options.timeoutMs,
+        approved: options.approved,
+        validationWave: { waveRunId, environmentSessionId, taskIds: plan.taskIds, acceptanceRefsByTask }
+      }));
+    }
+  }
+
+  const completedAt = new Date().toISOString();
+  const validationStatus = plan.status === 'BLOCKED' ? 'BLOCKED' : deriveWaveStatus(taskResults.map((result) => result.status));
+  const gaps = [...plan.blockers, ...taskResults.flatMap((result) => result.gaps)];
+  const workflowGateDecision = validationStatus === 'PASS'
+    ? (await evaluateAndRecordWorkflowGateDecision(projectRoot, {
+      branch: plan.branch,
+      taskId: taskResults[0]?.taskId ?? plan.taskIds[0] ?? null,
+      runId: taskResults[0]?.runId ?? null,
+      decisionKind: 'validation_wave',
+      waveRunId,
+      taskIds: plan.taskIds,
+      runIds: taskResults.map((result) => result.runId),
+      evidenceRefs: taskResults.flatMap((result) => [result.validationArtifact, result.indexArtifact].filter((ref): ref is string => Boolean(ref)))
+    })).decision
+    : null;
+  const status = finalWaveStatus(validationStatus, workflowGateDecision);
+  await recordRuntimeValidationWaveRun(projectRoot, {
+    waveRunId,
+    partition: plan.branch,
+    runId: taskResults[0]?.runId ?? null,
+    taskIds: plan.taskIds,
+    status,
+    environmentSessionId,
+    startedAt,
+    completedAt,
+    payload: { contract: VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION, plan, validationStatus, workflowGateDecision, workflowScope: workflowScopeFromGateDecision(workflowGateDecision), taskResults: taskResults.map((result) => ({ taskId: result.taskId, runId: result.runId, testRunId: result.testRunId, status: result.status, workflowGateStatus: result.workflowGateStatus })), gaps }
+  });
+  await recordRuntimeValidationEnvironmentSession(projectRoot, {
+    sessionId: environmentSessionId,
+    partition: plan.branch,
+    runId: taskResults[0]?.runId ?? null,
+    waveRunId,
+    status: status === 'PASS' ? 'completed' : status === 'FAIL' ? 'failed' : 'blocked',
+    reuseKey: validationEnvironmentReuseKey(plan),
+    createdAt: startedAt,
+    updatedAt: completedAt,
+    payload: { contract: VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION, taskIds: plan.taskIds, wave: plan.wave, batchId: plan.batchId, validationStatus, workflowGateStatus: workflowGateDecision?.status ?? 'none', status }
+  });
+  const acceptanceEvidence = await listRuntimeAcceptanceEvidenceMaps(projectRoot, { partition: plan.branch, waveRunId });
+  return {
+    contract: VALIDATION_WAVE_RUNTIME_CONTRACT_VERSION,
+    waveRunId,
+    environmentSessionId,
+    branch: plan.branch,
+    status,
+    plan,
+    taskResults,
+    acceptanceEvidence,
+    gaps,
+    workflowGateDecision,
+    next: nextForValidationWave(status, plan.branch, plan.selectionBoundary, plan.batchId, plan.wave, plan.taskIds, workflowGateDecision)
+  };
+}
+
+export function renderValidationWaveResult(result: ValidationWaveRunResult): string {
+  return [
+    `SDD validation ${result.plan.batchId ? `batch ${result.plan.batchId}` : `wave ${result.plan.wave ?? 'all'}`}`,
+    '',
+    `status=${result.status}`,
+    `branch=${result.branch}`,
+    `wave_run=${result.waveRunId}`,
+    `environment_session=${result.environmentSessionId}`,
+    `batch=${result.plan.batchId ?? 'none'}`,
+    `tasks=${result.plan.taskIds.join(',') || 'none'}`,
+    `acceptance_maps=${result.acceptanceEvidence.length}`,
+    `workflow_gate=${result.workflowGateDecision ? `${result.workflowGateDecision.status}:${result.workflowGateDecision.decisionId}` : 'none'}`,
+    '',
+    'Gaps:',
+    result.gaps.length > 0 ? result.gaps.map((gap) => `- ${gap}`).join('\n') : '- none',
+    '',
+    'Next:',
+    `- ${result.next}`
+  ].join('\n');
+}
+
+function selectValidationTasks(tasks: SddTask[], options: RunValidationWaveOptions, verifyBatches: Map<string, VerifyBatchPlan>): SddTask[] {
+  const explicit = new Set(options.taskIds ?? []);
+  if (explicit.size > 0) {
+    return tasks.filter((task) => explicit.has(task.id) && verifyBatchIncludesTask(verifyBatches, task.id));
+  }
+  if (options.batchId) {
+    const batchTasks = new Set(verifyBatches.get(options.batchId)?.tasks ?? []);
+    return tasks.filter((task) => batchTasks.has(task.id));
+  }
+  if (options.wave !== undefined && options.wave !== null) {
+    const verifyTaskIds = new Set(Array.from(verifyBatches.values()).flatMap((batch) => batch.tasks));
+    return tasks.filter((task) => task.wave === options.wave && verifyTaskIds.has(task.id));
+  }
+  const batchIds = new Set(verifyBatches.keys());
+  if (batchIds.size > 0) {
+    return tasks.filter((task) => task.validationBatch && batchIds.has(task.validationBatch));
+  }
+  return [];
+}
+
+function validationSelectionBoundary(options: RunValidationWaveOptions): ValidationWaveSelectionBoundary {
+  if (options.batchId) {
+    return 'batch';
+  }
+  if (options.wave !== undefined && options.wave !== null) {
+    return 'wave';
+  }
+  if ((options.taskIds ?? []).length > 0) {
+    return 'tasks';
+  }
+  return 'all';
+}
+
+function explicitTaskCoverageBlockersForOptions(tasks: SddTask[], options: RunValidationWaveOptions, selectedTaskIds: Set<string>, verifyBatches: Map<string, VerifyBatchPlan>): string[] {
+  const requestedTaskIds = [...new Set(options.taskIds ?? [])];
+  if (requestedTaskIds.length === 0) {
+    return [];
+  }
+  const taskById = new Map(tasks.map((task) => [task.id, task]));
+  return requestedTaskIds.flatMap((taskId) => {
+    if (selectedTaskIds.has(taskId)) {
+      return [];
+    }
+    if (!taskById.has(taskId)) {
+      return [`Task ${taskId} was requested but was not found in tasks.md.`];
+    }
+    if (!verifyBatchIncludesTask(verifyBatches, taskId)) {
+      return [`Task ${taskId} was requested but is not covered by verify.md verification batches.`];
+    }
+    return [`Task ${taskId} was requested but was not selected for validation.`];
+  });
+}
+
+function selectedValidationBatchId(options: RunValidationWaveOptions, tasks: SddTask[]): string | null {
+  if (options.batchId) {
+    return options.batchId;
+  }
+  const batchIds = [...new Set(tasks.map((task) => task.validationBatch).filter((value): value is string => Boolean(value)))];
+  return batchIds.length === 1 ? batchIds[0] : null;
+}
+
+async function readVerifyBatchPlans(inspection: VerifyContractInspection): Promise<Map<string, VerifyBatchPlan>> {
+  if (!inspection.exists) {
+    return new Map();
+  }
+  const raw = await readFile(inspection.verifyPath, 'utf8');
+  const batches = new Map<string, VerifyBatchPlan>();
+  let currentBatch: VerifyBatchPlan | null = null;
+  let activeList: 'tasks' | 'checks' | 'forbiddenValidation' | 'requiredArtifacts' | null = null;
+  let inAcceptanceMapping = false;
+  let currentAcceptanceTask: string | null = null;
+
+  for (const line of raw.split(/\r?\n/)) {
+    const batchMatch = line.match(/^  - id: "?([^"\n]+)"?$/);
+    if (batchMatch) {
+      currentBatch = { id: batchMatch[1], timing: null, tasks: [], checks: [], forbiddenValidation: [], requiredArtifacts: [], acceptanceMapping: new Map() };
+      batches.set(currentBatch.id, currentBatch);
+      activeList = null;
+      inAcceptanceMapping = false;
+      currentAcceptanceTask = null;
+      continue;
+    }
+    if (!currentBatch) {
+      continue;
+    }
+
+    const timingMatch = line.match(/^    timing: "?([^"\n]+)"?$/);
+    if (timingMatch) {
+      currentBatch.timing = timingMatch[1];
+      continue;
+    }
+
+    if (line === '    tasks:') {
+      activeList = 'tasks';
+      inAcceptanceMapping = false;
+      currentAcceptanceTask = null;
+      continue;
+    }
+    if (line === '    checks:') {
+      activeList = 'checks';
+      inAcceptanceMapping = false;
+      currentAcceptanceTask = null;
+      continue;
+    }
+    if (line === '    forbidden_validation:') {
+      activeList = 'forbiddenValidation';
+      inAcceptanceMapping = false;
+      currentAcceptanceTask = null;
+      continue;
+    }
+    if (line === '    required_artifacts:') {
+      activeList = 'requiredArtifacts';
+      inAcceptanceMapping = false;
+      currentAcceptanceTask = null;
+      continue;
+    }
+    if (line === '    acceptance_mapping:') {
+      activeList = null;
+      inAcceptanceMapping = true;
+      currentAcceptanceTask = null;
+      continue;
+    }
+    if (/^    [a-z_]+:/.test(line)) {
+      activeList = null;
+      inAcceptanceMapping = false;
+      currentAcceptanceTask = null;
+      continue;
+    }
+
+    if (activeList !== null) {
+      const listMatch = line.match(/^      - (.+)$/);
+      if (listMatch) {
+        currentBatch[activeList].push(cleanYamlScalar(listMatch[1]));
+        continue;
+      }
+    }
+
+    if (inAcceptanceMapping) {
+      const taskMatch = line.match(/^      ([^:]+):\s*$/);
+      if (taskMatch) {
+        currentAcceptanceTask = cleanYamlScalar(taskMatch[1]);
+        currentBatch.acceptanceMapping.set(currentAcceptanceTask, []);
+        continue;
+      }
+      if (currentAcceptanceTask !== null) {
+        const refMatch = line.match(/^        - (.+)$/);
+        if (refMatch) {
+          currentBatch.acceptanceMapping.get(currentAcceptanceTask)?.push(cleanYamlScalar(refMatch[1]));
+        }
+      }
+    }
+  }
+  return batches;
+}
+
+function verifyBatchContractBlockers(tasks: SddTask[], batches: VerifyBatchPlan[]): string[] {
+  const taskById = new Map(tasks.map((task) => [task.id, task]));
+  const blockers: string[] = [];
+  const forbiddenBackendBuild = batches.some((batch) => batch.forbiddenValidation.some(isBackendBuildValidationCommand));
+  for (const batch of batches) {
+    for (const taskId of batch.tasks) {
+      const task = taskById.get(taskId);
+      if (!task) {
+        continue;
+      }
+      const mappedAcceptance = batch.acceptanceMapping.get(taskId) ?? [];
+      for (const ref of mappedAcceptance) {
+        if (!task.acceptanceRefs.includes(ref) && !task.acceptance.includes(ref)) {
+          blockers.push(`verify.md batch ${batch.id} maps ${taskId} to unknown acceptance ${ref}.`);
+        }
+      }
+      for (const artifact of batch.requiredArtifacts) {
+        if (task.requiredArtifacts.length > 0 && !task.requiredArtifacts.includes(artifact)) {
+          blockers.push(`verify.md batch ${batch.id} requires artifact ${artifact} that task ${taskId} does not declare.`);
+        }
+      }
+      if (batch.forbiddenValidation.some(isBackendBuildValidationCommand) && task.validation.some(isBackendBuildValidationCommand)) {
+        blockers.push(`Task ${task.id} declares backend build validation forbidden by verify.md batch ${batch.id}.`);
+      }
+      if ((task.changeSurface === 'frontend_only' || isFrontendOnlyTask(task)) && task.validation.some(isBackendBuildValidationCommand) && forbiddenBackendBuild) {
+        blockers.push(`Task ${task.id} is frontend_only but declares backend build validation forbidden by its verification batch.`);
+      }
+    }
+  }
+  return blockers;
+}
+
+function acceptanceRefsForTask(task: SddTask, batches: VerifyBatchPlan[]): string[] {
+  const mappedRefs = batches.flatMap((batch) => batch.acceptanceMapping.get(task.id) ?? []);
+  const refs = mappedRefs.length > 0 ? mappedRefs : task.acceptanceRefs.length > 0 ? task.acceptanceRefs : task.acceptance;
+  return [...new Set(refs)];
+}
+
+function acceptanceRefsByTaskFromBatches(batches: ValidationWavePlan['verifyBatches']): Record<string, string[]> {
+  const refsByTask = new Map<string, string[]>();
+  for (const batch of batches) {
+    for (const [taskId, refs] of Object.entries(batch.acceptanceMapping)) {
+      refsByTask.set(taskId, [...new Set([...(refsByTask.get(taskId) ?? []), ...refs])]);
+    }
+  }
+  return Object.fromEntries(refsByTask);
+}
+
+function selectedBatchesForTasks(tasks: SddTask[], selectedBatchId: string | null, verifyBatches: Map<string, VerifyBatchPlan>): VerifyBatchPlan[] {
+  if (selectedBatchId) {
+    return [verifyBatches.get(selectedBatchId)].filter((batch): batch is VerifyBatchPlan => Boolean(batch));
+  }
+  const selectedTaskIds = new Set(tasks.map((task) => task.id));
+  return Array.from(verifyBatches.values()).filter((batch) => batch.tasks.some((taskId) => selectedTaskIds.has(taskId)));
+}
+
+function verifyBatchIncludesTask(verifyBatches: Map<string, VerifyBatchPlan>, taskId: string): boolean {
+  return Array.from(verifyBatches.values()).some((batch) => batch.tasks.includes(taskId));
+}
+
+function serializeVerifyBatchPlan(batch: VerifyBatchPlan): ValidationWavePlan['verifyBatches'][number] {
+  return {
+    id: batch.id,
+    timing: batch.timing,
+    tasks: batch.tasks,
+    checks: batch.checks,
+    forbiddenValidation: batch.forbiddenValidation,
+    requiredArtifacts: batch.requiredArtifacts,
+    acceptanceMapping: Object.fromEntries(batch.acceptanceMapping)
+  };
+}
+
+function cleanYamlScalar(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    try {
+      return JSON.parse(trimmed) as string;
+    } catch {
+      return trimmed.slice(1, -1);
+    }
+  }
+  if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function deriveWaveStatus(statuses: SddTestStatus[]): RuntimeValidationWaveStatus {
+  if (statuses.length === 0 || statuses.some((status) => status === 'BLOCKED')) {
+    return 'BLOCKED';
+  }
+  if (statuses.some((status) => status === 'FAIL')) {
+    return 'FAIL';
+  }
+  return 'PASS';
+}
+
+function validationEnvironmentReuseKey(plan: ValidationWavePlan): string {
+  return `${plan.branch}:${plan.batchId ?? plan.wave ?? 'all'}:${plan.taskIds.join(',')}`;
+}
+
+function workflowScopeFromGateDecision(decision: WorkflowGateDecision | null): WorkflowGateScope | null {
+  if (!decision?.payload || typeof decision.payload !== 'object') {
+    return null;
+  }
+  return ((decision.payload as { workflowScope?: WorkflowGateScope }).workflowScope) ?? null;
+}
+
+function finalWaveStatus(validationStatus: RuntimeValidationWaveStatus, workflowGateDecision: WorkflowGateDecision | null): RuntimeValidationWaveStatus {
+  if (validationStatus !== 'PASS') {
+    return validationStatus;
+  }
+  return workflowGateDecision?.status === 'PASS' ? 'PASS' : 'BLOCKED';
+}
+
+function nextForValidationWave(status: RuntimeValidationWaveStatus, branch: string, selectionBoundary: ValidationWaveSelectionBoundary, batchId: string | null, wave: number | null, taskIds: string[], workflowGateDecision: WorkflowGateDecision | null): string {
+  if (status === 'PASS') {
+    return `sdd ship --branch ${branch} --dry-run`;
+  }
+  if (workflowGateDecision && workflowGateDecision.status !== 'PASS') {
+    return `Inspect validation wave gate ${workflowGateDecision.decisionId}, resolve blockers or decision-card requirements, then rerun ${rerunValidationCommand(branch, selectionBoundary, batchId, wave, taskIds)}.`;
+  }
+  return `Inspect validation wave evidence, fix blocked or failed tasks, then rerun ${rerunValidationCommand(branch, selectionBoundary, batchId, wave, taskIds)}.`;
+}
+
+function rerunValidationCommand(branch: string, selectionBoundary: ValidationWaveSelectionBoundary, batchId: string | null, wave: number | null, taskIds: string[]): string {
+  if (selectionBoundary === 'batch' && batchId) {
+    return `sdd test batch ${batchId} --branch ${branch}`;
+  }
+  if (selectionBoundary === 'tasks' && taskIds.length > 0) {
+    return `sdd test wave --branch ${branch} ${taskIds.map((taskId) => `--task ${taskId}`).join(' ')}`;
+  }
+  return wave === null ? `sdd test wave --branch ${branch}` : `sdd test wave --branch ${branch} --wave ${wave}`;
+}