sdd-agent-platform 0.4.2 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/verification/test-runtime.ts

@@ -1,1190 +1,1190 @@
-import { createHash } from 'node:crypto';
-import { spawn } from 'node:child_process';
-import { appendEvent } from '../run-state/events.js';
-import { appendArtifactHashLedgerEntry, appendInvocationLedgerEntry } from '../run-state/invocation-ledger.js';
-import type { RunState, RunStateTaskRuntime } from '../run-state/model.js';
-import { createRun, readAllRunStates, readRunState, writeRunState } from '../run-state/run-state.js';
-import { recordRuntimeOnlyArtifact, recordStageEvidenceArtifact } from '../run-state/artifacts.js';
-import { toBranchStageEvidenceRef } from '../runtime-paths.js';
-import { resolveSddContext } from '../sdd-docs/context.js';
-import { bindRunStateToTask } from '../sdd-docs/run-binding.js';
-import { parseSddBranch, type SddTask, type SddTaskModel } from '../sdd-docs/task-parser.js';
-import { inspectSddTask } from '../sdd-docs/task-inspection.js';
-import { listRuntimeArtifactPayloads, readRuntimeValidationCacheEntry, recordRuntimeAcceptanceEvidenceMap, recordRuntimeDurableGap, recordRuntimeProjection, recordRuntimeTestRun, recordRuntimeTestStep, recordRuntimeValidationCacheEntry, recordRuntimeValidationCacheUse, recordRuntimeValidationEnvironmentSession, recordRuntimeValidationWaveRun, runtimeScopedId, updateRuntimeDurableGapStatus, type RuntimeValidationCacheEntryRecord } from '../storage/runtime-store.js';
-import { ACCEPTANCE_POLICY_RULESET_VERSION, SDD_EVIDENCE_CONTRACT, SDD_EVIDENCE_VERSION, SDD_RESULT_CONTRACT, SDD_RESULT_VERSION, TEST_EVIDENCE_RUN_CONTRACT_VERSION, WORKFLOW_HANDOFF_CONTRACT_VERSION } from '../contracts.js';
-import type { LifecycleRiskDecision } from '../risk/contracts.js';
-import { inspectVerifyContract, type VerifyContractInspection } from './verify-contract.js';
-import type { AcceptanceEvidenceCoverage, CapabilityEvidenceClassification, EvidenceCoverageStatus, TestEvidenceStatus, UnifiedTestEvidenceRun } from '../evidence-runtime.js';
-import { ensureTaskOrchestration, inspectOrchestrationGate } from '../orchestration/runtime.js';
-import { recordStageRunProjection, recordWorkflowHandoffProjection, validateWorkflowHandoff } from '../stage-runtime/runtime.js';
-import type { StageRun, WorkflowHandoff } from '../stage-runtime/contracts.js';
-import { evaluateTaskWorkflowGate, verifyContractBlockedGate, type ApprovalPolicy, type LifecycleRiskProfile, type LifecycleWorkflowGate } from '../risk.js';
-import { validateSddResultArtifact } from '../artifacts/sdd-result.js';
-import { dependencyBlockingReasonsForTask } from '../workflow-state/dependencies.js';
-import { selectLatestEligibleRunsByTask } from '../workflow-state/latest-eligible-run.js';
-import { latestRuntimeTaskStates } from '../workflow-state/resolve.js';
-import { routeSddTask } from '../router/route-sdd-task.js';
-import type { AgentCapabilityRouteDecision } from '../router/agent-runtime.js';
-import { evaluateAndRecordWorkflowGateDecision } from '../workflow-gate/evidence-packet.js';
-import type { WorkflowGateDecision, WorkflowGateStatus } from '../workflow-gate/types.js';
-import { buildValidationCachePlan, type ValidationCacheUnsafeReason } from './validation-cache.js';
-
-const DEFAULT_TEST_TIMEOUT_MS = 120_000;
-const MAX_CAPTURE_BYTES = 256 * 1024;
-
-export type SddTestStatus = 'PASS' | 'FAIL' | 'BLOCKED';
-export type SddTestStepStatus = 'pass' | 'fail' | 'blocked';
-
-export interface SddTestCommandInput {
-  command?: string;
-  argv?: string[];
-}
-
-export interface SddTestCommandStep {
-  stepId: string;
-  command: string;
-  argv: string[] | null;
-  shell: boolean;
-  acceptanceRefs: string[];
-  status: SddTestStepStatus;
-  exitCode: number | null;
-  signal: string | null;
-  durationMs: number;
-  outputArtifact: string | null;
-  stdoutBytes: number;
-  stderrBytes: number;
-  truncated: boolean;
-  startedAt: string;
-  endedAt: string;
-  cwd: string;
-  stdoutDigest: string;
-  stderrDigest: string;
-  outputSummary: string;
-  cacheStatus: 'hit' | 'miss' | 'unsafe';
-  cacheKey: string | null;
-  cacheSourceTestRunId: string | null;
-  cacheUnsafeReasons: ValidationCacheUnsafeReason[];
-}
-
-interface NormalizedSddTestCommand {
-  command: string;
-  argv: string[] | null;
-  shell: boolean;
-}
-
-type VerifyContractAction = 'none' | 'created' | 'refreshed' | 'blocked';
-
-type RuntimeTestJudgment = WorkflowGateStatus;
-
-export interface SddTestResult {
-  contract: 'sdd-test-runtime-v1';
-  runId: string;
-  testRunId: string;
-  validationWaveRunId: string;
-  validationEnvironmentSessionId: string;
-  branch: string;
-  taskId: string;
-  status: SddTestStatus;
-  validationStatus: SddTestStatus;
-  workflowGateStatus: WorkflowGateStatus;
-  runtimeJudgment: RuntimeTestJudgment;
-  workflowGateDecision: WorkflowGateDecision;
-  verifyContractStatus: string;
-  verifyContractAction: VerifyContractAction;
-  lifecycleGate: LifecycleWorkflowGate;
-  lifecycleProfile: LifecycleRiskProfile | null;
-  approvalPolicy: ApprovalPolicy | null;
-  requiredStages: string[];
-  primaryReason: string;
-  commandStatus: TestEvidenceStatus;
-  evidenceCoverage: EvidenceCoverageStatus;
-  policyJudgment: TestEvidenceStatus;
-  acceptanceCoverage: AcceptanceEvidenceCoverage[];
-  capabilityEvidence: CapabilityEvidenceClassification[];
-  commands: string[];
-  steps: SddTestCommandStep[];
-  validationArtifact: string | null;
-  indexArtifact: string | null;
-  gaps: string[];
-  next: string;
-}
-
-export interface RunSddTestOptions {
-  taskId: string;
-  branch?: string | null;
-  runId?: string | null;
-  commands?: string[];
-  commandInputs?: SddTestCommandInput[];
-  timeoutMs?: number;
-  approved?: boolean;
-  validationWave?: { waveRunId: string; environmentSessionId: string; taskIds: string[]; acceptanceRefsByTask?: Record<string, string[]> };
-}
-
-export async function runSddTest(projectRoot: string, options: RunSddTestOptions): Promise<SddTestResult> {
-  const context = await resolveSddContext(projectRoot, { branch: options.branch ?? undefined, branchSource: options.branch ? 'cli_option' : undefined });
-  const model = await parseSddBranch(projectRoot, context.partition);
-  const inspected = inspectSddTask(model, options.taskId);
-  const task = inspected.task;
-  const verifyContract = await ensureVerifyContractForTest(projectRoot, context.partition);
-  const verifyInspection = verifyContract.inspection;
-  const initialState = options.runId ? await readRunState(projectRoot, options.runId) : await createRun(projectRoot);
-  const state = await bindRunStateToTask(projectRoot, initialState, context, model, task, options.taskId);
-  const testRunId = runtimeScopedId(state.runId, options.taskId, new Date().toISOString(), 'sdd-test');
-  const commandInputs = normalizeTestCommandInputs(options.commandInputs, options.commands, task?.validation ?? []);
-  const commands = commandInputs.map((input) => input.command);
-  const gaps: string[] = [];
-  const startedAt = new Date().toISOString();
-  const ownsValidationWave = !options.validationWave;
-  const validationWaveRunId = options.validationWave?.waveRunId ?? runtimeScopedId(context.partition, options.taskId, state.runId, testRunId, 'validation-wave');
-  const validationEnvironmentSessionId = options.validationWave?.environmentSessionId ?? runtimeScopedId(context.partition, validationWaveRunId, 'validation-env');
-  const validationWaveTaskIds = options.validationWave?.taskIds ?? [options.taskId];
-  const validationWaveAcceptanceRefs = options.validationWave?.acceptanceRefsByTask?.[options.taskId];
-  const validationWaveScopeAcceptanceRefs = [...new Set(Object.values(options.validationWave?.acceptanceRefsByTask ?? { [options.taskId]: task?.acceptanceRefs ?? [] }).flat())].sort();
-  if (ownsValidationWave) {
-    await recordRuntimeValidationEnvironmentSession(projectRoot, {
-      sessionId: validationEnvironmentSessionId,
-      partition: context.partition,
-      runId: state.runId,
-      waveRunId: validationWaveRunId,
-      status: 'active',
-      reuseKey: `${context.partition}:${options.taskId}`,
-      createdAt: startedAt,
-      updatedAt: startedAt,
-      payload: { contract: 'phase-8.17-validation-wave-runtime-v1', mode: 'single-task' }
-    });
-    await recordRuntimeValidationWaveRun(projectRoot, {
-      waveRunId: validationWaveRunId,
-      partition: context.partition,
-      runId: state.runId,
-      taskIds: validationWaveTaskIds,
-      status: 'RUNNING',
-      environmentSessionId: validationEnvironmentSessionId,
-      startedAt,
-      completedAt: startedAt,
-      payload: { contract: 'phase-8.17-validation-wave-runtime-v1', mode: 'single-task', taskId: options.taskId }
-    });
-  }
-
-  await appendEvent(projectRoot, state.runId, {
-    event: 'test_runtime_started',
-    runId: state.runId,
-    summary: `SDD test runtime started for ${options.taskId}`,
-    data: { taskId: options.taskId, branch: context.partition, testRunId, commands }
-  });
-
-  const states = await readAllRunStates(projectRoot);
-  const latestEligibleRunsByTask = selectLatestEligibleRunsByTask({ states, model, partition: context.partition, currentGitBranch: context.currentGitBranch });
-  const runtimeByTask = latestRuntimeTaskStates(latestEligibleRunsByTask, states);
-
-  if (!task) {
-    gaps.push(`Task ${options.taskId} was not found in specs/${context.partition}/tasks.md.`);
-  }
-  if (task) {
-    gaps.push(...inspected.gaps.filter((gap) => gap.severity === 'blocking').map((gap) => `${gap.field}: ${gap.message}`));
-    gaps.push(...dependencyBlockingReasonsForTask(model, options.taskId, { runtimeByTask }));
-  }
-  if (verifyContract.action === 'blocked') {
-    gaps.push(verifyContractBlocker(verifyInspection));
-  }
-  if (commands.length === 0) {
-    gaps.push(`Task ${options.taskId} has no validation commands.`);
-  }
-  const orchestration = await ensureTaskOrchestration(projectRoot, model, task, {
-    branch: context.partition,
-    runId: state.runId,
-    taskId: options.taskId,
-    agent: 'validator',
-    stage: 'test',
-    status: 'active'
-  });
-  const orchestrationGate = await inspectOrchestrationGate(projectRoot, {
-    branch: context.partition,
-    runId: state.runId,
-    taskId: options.taskId,
-    target: 'test',
-    riskDecision: orchestration.riskDecision,
-    stageRun: orchestration.stageRun,
-    contextLoadSignal: orchestration.contextLoadSignal,
-    contextOffloadDecision: orchestration.contextOffloadDecision
-  });
-  const reviewerCheckpointSatisfied = await hasReviewerCheckpoint(projectRoot, state, options.taskId);
-  const workflowGate = verifyContract.action === 'blocked'
-    ? verifyContractBlockedGate(options.taskId)
-    : evaluateTaskWorkflowGate({ task, taskId: options.taskId, riskDecision: orchestration.riskDecision, approved: options.approved, reviewerCheckpointSatisfied });
-  if (workflowGate.blocksTest) {
-    gaps.push(workflowGate.primaryReason);
-  }
-  gaps.push(...orchestrationGate.blockingReasons);
-
-  await recordRuntimeTestRun(projectRoot, {
-    testRunId,
-    runId: state.runId,
-    partition: context.partition,
-    taskId: options.taskId,
-    status: 'RUNNING',
-    startedAt,
-    completedAt: startedAt,
-    payload: { verifyContractStatus: verifyInspection.status, verifyContractAction: verifyContract.action, lifecycleGate: workflowGate.lifecycleGate, lifecycleProfile: workflowGate.lifecycleProfile, approvalPolicy: workflowGate.approvalPolicy, requiredStages: workflowGate.requiredStages, primaryReason: workflowGate.primaryReason, commands, commandInputs, evidence: [], gaps }
-  });
-
-  const steps: SddTestCommandStep[] = [];
-  if (gaps.length === 0) {
-    for (const [index, commandInput] of commandInputs.entries()) {
-      const step = await runCommandStep(projectRoot, state.runId, context.partition, options.taskId, testRunId, index + 1, commandInput, acceptanceRefsForCommand(task, commandInput.command, validationWaveAcceptanceRefs), options.timeoutMs ?? DEFAULT_TEST_TIMEOUT_MS, model, task!, validationWaveTaskIds, validationWaveScopeAcceptanceRefs);
-      steps.push(step);
-      await appendEvent(projectRoot, state.runId, {
-        event: 'test_step_completed',
-        runId: state.runId,
-        summary: `SDD test step ${step.status}: ${step.command}`,
-        data: { taskId: options.taskId, testRunId, step }
-      });
-    }
-  }
-
-  const commandStatus = deriveCommandStatus(gaps, steps);
-  const acceptanceCoverage = buildAcceptanceCoverage(task, steps, commandStatus, validationWaveAcceptanceRefs);
-  const evidenceCoverage = summarizeEvidenceCoverage(acceptanceCoverage);
-  const policyJudgment = derivePolicyJudgment(commandStatus, evidenceCoverage);
-  await recordAcceptanceEvidenceMaps(projectRoot, validationWaveRunId, testRunId, context.partition, state.runId, options.taskId, acceptanceCoverage);
-  const validationStatus = policyJudgment;
-  const capabilityRoute = task ? await routeSddTask(projectRoot, { taskId: options.taskId, branch: context.partition, approved: options.approved }) : null;
-  const capabilityEvidence = buildCapabilityEvidenceClassification(capabilityRoute?.capabilityDecision ?? null, steps);
-  const validationArtifact = task ? await writeValidationArtifact(projectRoot, state.runId, context.partition, task, validationStatus, steps, gaps, capabilityEvidence) : null;
-  const evidenceBeforeGate = runtimeEvidenceRefs(validationArtifact?.runRelativePath ?? null, steps);
-  await persistTestRunState(projectRoot, state, options.taskId, validationStatus, commands, evidenceBeforeGate, validationArtifact?.runRelativePath ?? null);
-  await resolveTestRuntimeDurableGap(projectRoot, context.partition, state.runId, options.taskId, validationStatus, gaps);
-
-  const gateDecision = (await evaluateAndRecordWorkflowGateDecision(projectRoot, {
-    branch: context.partition,
-    taskId: options.taskId,
-    runId: state.runId,
-    decisionKind: 'test'
-  })).decision;
-  const runtimeJudgment = gateDecision.status;
-  const status = finalStatusForTest(validationStatus, runtimeJudgment);
-  await recordTestRuntimeDurableGap(projectRoot, context.partition, state.runId, options.taskId, status, validationStatus, runtimeJudgment, gaps, evidenceBeforeGate);
-  const unifiedEvidence = buildUnifiedTestEvidenceRun(testRunId, context.partition, state.runId, options.taskId, commandStatus, evidenceCoverage, policyJudgment, status, runtimeJudgment, steps, acceptanceCoverage, capabilityEvidence, gaps, workflowGate.nextAction, gateDecision);
-  const completedAt = new Date().toISOString();
-  const evidence = runtimeEvidenceRefs(validationArtifact?.runRelativePath ?? null, steps);
-
-  await recordRuntimeTestRun(projectRoot, {
-    testRunId,
-    runId: state.runId,
-    partition: context.partition,
-    taskId: options.taskId,
-    status,
-    startedAt,
-    completedAt,
-    payload: { verifyContractStatus: verifyInspection.status, verifyContractAction: verifyContract.action, lifecycleGate: workflowGate.lifecycleGate, lifecycleProfile: workflowGate.lifecycleProfile, approvalPolicy: workflowGate.approvalPolicy, requiredStages: workflowGate.requiredStages, primaryReason: workflowGate.primaryReason, commandStatus, evidenceCoverage, policyJudgment, validationStatus, workflowGateStatus: gateDecision.status, runtimeJudgment, workflowGateDecision: gateDecision, acceptanceCoverage, capabilityEvidence, commands, commandInputs, evidence, gaps }
-  });
-  await recordRuntimeProjection(projectRoot, 'test_runtime', `${context.partition}:${options.taskId}:${state.runId}`, {
-    contract: 'sdd-test-runtime-v1',
-    testRunId,
-    runId: state.runId,
-    taskId: options.taskId,
-    status,
-    validationStatus,
-    workflowGateStatus: gateDecision.status,
-    runtimeJudgment,
-    lifecycleGate: workflowGate.lifecycleGate,
-    primaryReason: workflowGate.primaryReason,
-    evidence,
-    gaps
-  });
-  await recordRuntimeProjection(projectRoot, 'test_evidence_run', `${context.partition}:${options.taskId}:${state.runId}`, unifiedEvidence);
-  await recordTestWorkflowProjection(projectRoot, {
-    taskId: options.taskId,
-    stageRun: orchestration.stageRun,
-    status,
-    completedAt,
-    evidence,
-    gaps,
-    riskDecision: orchestration.riskDecision
-  });
-  await persistTestGateOutcome(projectRoot, state.runId, options.taskId, status, validationStatus, commands, evidence, validationArtifact?.runRelativePath ?? null, gateDecision);
-  if (ownsValidationWave) {
-    await recordRuntimeValidationWaveRun(projectRoot, {
-      waveRunId: validationWaveRunId,
-      partition: context.partition,
-      runId: state.runId,
-      taskIds: validationWaveTaskIds,
-      status,
-      environmentSessionId: validationEnvironmentSessionId,
-      startedAt,
-      completedAt,
-      payload: { contract: 'phase-8.17-validation-wave-runtime-v1', mode: 'single-task', taskId: options.taskId, testRunId, evidence, gaps, workflowGateDecision: gateDecision }
-    });
-    await recordRuntimeValidationEnvironmentSession(projectRoot, {
-      sessionId: validationEnvironmentSessionId,
-      partition: context.partition,
-      runId: state.runId,
-      waveRunId: validationWaveRunId,
-      status: status === 'PASS' ? 'completed' : status === 'FAIL' ? 'failed' : 'blocked',
-      reuseKey: `${context.partition}:${options.taskId}`,
-      createdAt: startedAt,
-      updatedAt: completedAt,
-      payload: { contract: 'phase-8.17-validation-wave-runtime-v1', mode: 'single-task', taskId: options.taskId, validationStatus, workflowGateStatus: gateDecision.status, status }
-    });
-  }
-
-  await appendEvent(projectRoot, state.runId, {
-    event: status === 'PASS' ? 'test_runtime_passed' : 'test_runtime_blocked',
-    runId: state.runId,
-    summary: `SDD test runtime ${status} for ${options.taskId}`,
-    data: { taskId: options.taskId, testRunId, status, validationStatus, evidence, gaps, gateDecisionId: gateDecision.decisionId, gateStatus: gateDecision.status }
-  });
-
-  return {
-    contract: 'sdd-test-runtime-v1',
-    runId: state.runId,
-    testRunId,
-    validationWaveRunId,
-    validationEnvironmentSessionId,
-    branch: context.partition,
-    taskId: options.taskId,
-    status,
-    validationStatus,
-    workflowGateStatus: gateDecision.status,
-    runtimeJudgment,
-    workflowGateDecision: gateDecision,
-    verifyContractStatus: verifyInspection.status,
-    verifyContractAction: verifyContract.action,
-    lifecycleGate: workflowGate.lifecycleGate,
-    lifecycleProfile: workflowGate.lifecycleProfile,
-    approvalPolicy: workflowGate.approvalPolicy,
-    requiredStages: workflowGate.requiredStages,
-    primaryReason: workflowGate.primaryReason,
-    commandStatus,
-    evidenceCoverage,
-    policyJudgment,
-    acceptanceCoverage,
-    capabilityEvidence,
-    commands,
-    steps,
-    validationArtifact: validationArtifact?.runRelativePath ?? null,
-    indexArtifact: null,
-    gaps,
-    next: nextForTestResult(status, runtimeJudgment, context.partition, options.taskId, workflowGate.nextAction, gateDecision)
-  };
-}
-
-async function recordAcceptanceEvidenceMaps(projectRoot: string, waveRunId: string, testRunId: string, partition: string, runId: string, taskId: string, acceptanceCoverage: AcceptanceEvidenceCoverage[]): Promise<void> {
-  const createdAt = new Date().toISOString();
-  for (const coverage of acceptanceCoverage) {
-    await recordRuntimeAcceptanceEvidenceMap(projectRoot, {
-      mapId: runtimeScopedId(waveRunId, testRunId, taskId, coverage.acceptanceRef),
-      waveRunId,
-      testRunId,
-      partition,
-      runId,
-      taskId,
-      acceptanceRef: coverage.acceptanceRef,
-      status: coverage.status,
-      evidenceRefs: coverage.evidenceRefs.map((ref) => ref.ref),
-      gaps: coverage.gaps,
-      createdAt,
-      payload: coverage
-    });
-  }
-}
-
-async function recordTestWorkflowProjection(projectRoot: string, input: { taskId: string; stageRun: StageRun; status: SddTestStatus; completedAt: string; evidence: string[]; gaps: string[]; riskDecision: LifecycleRiskDecision }): Promise<void> {
-  const outputRefs = input.evidence.map((ref) => ({ kind: 'artifact' as const, ref }));
-  const completedStage: StageRun = {
-    ...input.stageRun,
-    status: input.status === 'PASS' ? 'completed' : input.status === 'FAIL' ? 'failed' : 'blocked',
-    outputRefs,
-    blockingReasons: input.status === 'PASS' ? [] : input.gaps.length > 0 ? input.gaps : [`SDD test ${input.status}.`],
-    updatedAt: input.completedAt
-  };
-  await recordStageRunProjection(projectRoot, completedStage);
-
-  const handoff: WorkflowHandoff = {
-    contract: WORKFLOW_HANDOFF_CONTRACT_VERSION,
-    id: `${completedStage.id}:handoff:goal-verify`,
-    scope: completedStage.scope,
-    fromStage: 'test',
-    toStage: 'goal-verify',
-    fromAgent: 'validator',
-    toAgent: 'verifier',
-    status: input.status === 'PASS' ? 'proposed' : 'blocked',
-    outputRefs,
-    requiredInputRefs: [{ kind: 'task', ref: input.taskId }],
-    riskDecisionRef: input.stageRun.decisionRefs[0] ?? { kind: 'task', ref: input.taskId },
-    evidenceRefs: outputRefs,
-    openQuestions: [],
-    blockingGaps: input.status === 'PASS' ? [] : completedStage.blockingReasons,
-    createdAt: input.completedAt,
-    decidedAt: input.completedAt
-  };
-  const validation = validateWorkflowHandoff({ handoff, sourceStageRun: completedStage, lifecycleRiskDecision: input.riskDecision });
-  await recordWorkflowHandoffProjection(projectRoot, validation.valid ? handoff : { ...handoff, status: 'blocked', blockingGaps: validation.issues, decidedAt: input.completedAt });
-}
-
-
-async function ensureVerifyContractForTest(projectRoot: string, branch: string): Promise<{ inspection: VerifyContractInspection; action: VerifyContractAction }> {
-  const inspection = await inspectVerifyContract(projectRoot, { branch, branchSource: 'cli_option' });
-  return { inspection, action: inspection.status === 'PASS' ? 'none' : 'blocked' };
-}
-
-function verifyContractBlocker(inspection: VerifyContractInspection): string {
-  const issueSummary = inspection.issues.map((issue) => `${issue.field}: ${issue.message}`).join(' ');
-  return `verify.md contract is ${inspection.status}; ${issueSummary || 'inspect verify.md before executing tests.'}`;
-}
-
-async function hasReviewerCheckpoint(projectRoot: string, state: RunState, taskId: string): Promise<boolean> {
-  const artifactPaths = new Set(state.artifacts
-    .filter((artifact) => artifact.task === taskId && (artifact.agent === 'reviewer' || artifact.kind === 'review'))
-    .map((artifact) => artifact.path));
-  const branch = state.partition ?? state.gitBranch ?? 'unscoped';
-  const payloads = await listRuntimeArtifactPayloads(projectRoot, { runId: state.runId, taskId });
-  for (const payload of payloads) {
-    const fileName = payload.logicalRef.replace(/\\/g, '/').split('/').filter(Boolean).pop();
-    if (fileName && (payload.artifactRole === 'review' || /review/i.test(fileName))) {
-      artifactPaths.add(toBranchStageEvidenceRef(branch, 'do', fileName));
-    }
-  }
-
-  for (const artifactPath of artifactPaths) {
-    const report = await validateSddResultArtifact(projectRoot, state.runId, artifactPath, { expectedTask: taskId, expectedAgent: 'reviewer' });
-    if (report.valid && report.result?.status === 'PASS') {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-export function renderSddTestResult(result: SddTestResult): string {
-  return [
-    `SDD test ${result.taskId}`,
-    '',
-    resultSentenceForTest(result),
-    '',
-    'Decision:',
-    `- validation_status=${result.validationStatus}`,
-    `- workflow_gate_status=${result.workflowGateStatus}`,
-    `- workflow_gate_decision=${result.workflowGateDecision.decisionId}`,
-    '',
-    'Why:',
-    `- ${result.primaryReason}`,
-    `- capability_evidence=${capabilityEvidenceSummary(result.capabilityEvidence)}`,
-    '',
-    'Next:',
-    `- ${result.next}`
-  ].join('\n');
-}
-
-
-async function runCommandStep(projectRoot: string, runId: string, branch: string, taskId: string, testRunId: string, sequence: number, commandInput: NormalizedSddTestCommand, acceptanceRefs: string[], timeoutMs: number, model: SddTaskModel, task: SddTask, validationScopeTaskIds: string[], validationScopeAcceptanceRefs: string[]): Promise<SddTestCommandStep> {
-  const cachePlan = buildValidationCachePlan({ branch, model, task, command: commandInput.command, argv: commandInput.argv, shell: commandInput.shell, validationScopeTaskIds, acceptanceRefs: validationScopeAcceptanceRefs });
-  const cached = cachePlan.eligible ? await readRuntimeValidationCacheEntry(projectRoot, { branchSlug: branch, cacheKey: cachePlan.cacheKey }) : null;
-  if (cached) {
-    return recordCachedCommandStep(projectRoot, runId, branch, taskId, testRunId, sequence, commandInput, acceptanceRefs, cachePlan.cacheKey, cached);
-  }
-
-  const started = Date.now();
-  const startedAt = new Date(started).toISOString();
-  const executed = await executeCommand(projectRoot, commandInput, timeoutMs);
-  const ended = Date.now();
-  const endedAt = new Date(ended).toISOString();
-  const durationMs = ended - started;
-  const status: SddTestStepStatus = executed.timedOut || executed.error ? 'blocked' : executed.exitCode === 0 ? 'pass' : 'fail';
-  const stepId = `${testRunId}-${String(sequence).padStart(3, '0')}`;
-  const cacheStatus = cachePlan.eligible ? 'miss' : 'unsafe';
-  const shouldPersistOutputArtifact = shouldPersistCommandOutputArtifact(status, executed, cacheStatus, cachePlan.unsafeReasons);
-  const outputFileName = shouldPersistOutputArtifact ? `test-${taskId}-${String(sequence).padStart(3, '0')}.log` : null;
-  const outputRef = outputFileName ? toBranchStageEvidenceRef(branch, 'test', outputFileName) : null;
-  const output = outputFileName ? renderCommandOutput(commandInput, status, executed, durationMs, cacheStatus, cachePlan.cacheKey, null, cachePlan.unsafeReasons) : null;
-  if (outputFileName && outputRef && output) {
-    await recordRuntimeOnlyArtifact(projectRoot, runId, outputFileName, output, { logicalRef: outputRef, branch, taskId, artifactRole: 'test-command-output' });
-    await appendArtifactHashLedgerEntry(projectRoot, {
-      runId,
-      taskId,
-      branch,
-      artifactPath: outputRef,
-      content: output,
-      status: 'recorded'
-    });
-  }
-  const stdoutDigest = hashDocumentContent(executed.stdout);
-  const stderrDigest = hashDocumentContent(executed.stderr);
-  const outputSummary = summarizeCommandOutput(executed);
-  await appendInvocationLedgerEntry(projectRoot, {
-    runId,
-    taskId,
-    branch,
-    kind: 'command',
-    ref: commandInput.command,
-    status,
-    artifactPath: outputRef,
-    outputHash: output ? hashDocumentContent(output) : null,
-    materialRefs: outputRef ? [outputRef] : [],
-    metadata: {
-      stepId,
-      source: 'sdd-test',
-      exitCode: executed.exitCode,
-      durationMs,
-      stdoutBytes: executed.stdoutBytes,
-      stderrBytes: executed.stderrBytes,
-      truncated: executed.truncated,
-      acceptanceRefs: acceptanceRefs.join(','),
-      shell: commandInput.shell,
-      argv: commandInput.argv ? JSON.stringify(commandInput.argv) : null,
-      stdoutDigest,
-      stderrDigest,
-      cacheKey: cachePlan.cacheKey,
-      cacheStatus,
-      cacheUnsafeReasons: cachePlan.unsafeReasons.join(',')
-    }
-  });
-  const step: SddTestCommandStep = {
-    stepId,
-    command: commandInput.command,
-    argv: commandInput.argv,
-    shell: commandInput.shell,
-    acceptanceRefs,
-    status,
-    exitCode: executed.exitCode,
-    signal: executed.signal,
-    durationMs,
-    outputArtifact: outputRef,
-    stdoutBytes: executed.stdoutBytes,
-    stderrBytes: executed.stderrBytes,
-    truncated: executed.truncated,
-    startedAt,
-    endedAt,
-    cwd: projectRoot,
-    stdoutDigest,
-    stderrDigest,
-    outputSummary,
-    cacheStatus,
-    cacheKey: cachePlan.cacheKey,
-    cacheSourceTestRunId: null,
-    cacheUnsafeReasons: cachePlan.unsafeReasons
-  };
-  await recordRuntimeTestStep(projectRoot, {
-    stepId,
-    testRunId,
-    runId,
-    taskId,
-    command: commandInput.command,
-    status,
-    exitCode: executed.exitCode,
-    durationMs,
-    outputArtifact: outputRef,
-    payload: step
-  });
-  if (status === 'pass' && cachePlan.eligible) {
-    const now = new Date().toISOString();
-    await recordRuntimeValidationCacheEntry(projectRoot, {
-      cacheKey: cachePlan.cacheKey,
-      branchSlug: branch,
-      command: commandInput.command,
-      status: 'valid',
-      sourceTestRunId: testRunId,
-      sourceRunId: runId,
-      sourceEvidenceSetId: null,
-      outputArtifact: outputRef,
-      stdoutDigest,
-      stderrDigest,
-      createdAt: now,
-      lastUsedAt: now,
-      payload: { cachePlan, step }
-    });
-  }
-  return step;
-}
-
-async function recordCachedCommandStep(projectRoot: string, runId: string, branch: string, taskId: string, testRunId: string, sequence: number, commandInput: NormalizedSddTestCommand, acceptanceRefs: string[], cacheKey: string, cached: RuntimeValidationCacheEntryRecord): Promise<SddTestCommandStep> {
-  const now = new Date().toISOString();
-  const stepId = `${testRunId}-${String(sequence).padStart(3, '0')}`;
-  const step: SddTestCommandStep = {
-    stepId,
-    command: commandInput.command,
-    argv: commandInput.argv,
-    shell: commandInput.shell,
-    acceptanceRefs,
-    status: 'pass',
-    exitCode: 0,
-    signal: null,
-    durationMs: 0,
-    outputArtifact: null,
-    stdoutBytes: 0,
-    stderrBytes: 0,
-    truncated: false,
-    startedAt: now,
-    endedAt: now,
-    cwd: projectRoot,
-    stdoutDigest: cached.stdoutDigest,
-    stderrDigest: cached.stderrDigest,
-    outputSummary: `cache_hit source_test_run=${cached.sourceTestRunId} source_artifact=${cached.outputArtifact ?? 'none'}`,
-    cacheStatus: 'hit',
-    cacheKey,
-    cacheSourceTestRunId: cached.sourceTestRunId,
-    cacheUnsafeReasons: []
-  };
-  await appendInvocationLedgerEntry(projectRoot, {
-    runId,
-    taskId,
-    branch,
-    kind: 'command',
-    ref: commandInput.command,
-    status: 'pass',
-    artifactPath: null,
-    outputHash: null,
-    materialRefs: cached.outputArtifact ? [cached.outputArtifact] : [],
-    metadata: { source: 'sdd-test-cache', stepId, cacheKey, sourceTestRunId: cached.sourceTestRunId, sourceEvidenceSetId: cached.sourceEvidenceSetId, acceptanceRefs: acceptanceRefs.join(',') }
-  });
-  await recordRuntimeTestStep(projectRoot, {
-    stepId,
-    testRunId,
-    runId,
-    taskId,
-    command: commandInput.command,
-    status: 'pass',
-    exitCode: 0,
-    durationMs: 0,
-    outputArtifact: null,
-    payload: step
-  });
-  await recordRuntimeValidationCacheUse(projectRoot, {
-    useId: runtimeScopedId(cacheKey, testRunId, taskId, stepId),
-    cacheKey,
-    branchSlug: branch,
-    testRunId,
-    runId,
-    taskId,
-    sourceTestRunId: cached.sourceTestRunId,
-    sourceEvidenceSetId: cached.sourceEvidenceSetId,
-    reusedAt: now,
-    mappedTaskIds: [taskId],
-    reason: 'same validation cache key within compatible branch contract scope',
-    payload: { sourceRunId: cached.sourceRunId, sourceArtifact: cached.outputArtifact }
-  });
-  return step;
-}
-
-function executeCommand(projectRoot: string, commandInput: NormalizedSddTestCommand, timeoutMs: number): Promise<{ exitCode: number | null; signal: string | null; stdout: string; stderr: string; stdoutBytes: number; stderrBytes: number; truncated: boolean; timedOut: boolean; error: string | null }> {
-  return new Promise((resolve) => {
-    const child = commandInput.argv
-      ? spawn(commandInput.argv[0], commandInput.argv.slice(1), { cwd: projectRoot, shell: false, windowsHide: true, env: process.env })
-      : spawn(commandInput.command, { cwd: projectRoot, shell: true, windowsHide: true, env: process.env });
-    let stdout = '';
-    let stderr = '';
-    let stdoutBytes = 0;
-    let stderrBytes = 0;
-    let truncated = false;
-    let settled = false;
-    let timedOut = false;
-    const timer = setTimeout(() => {
-      timedOut = true;
-      child.kill();
-    }, timeoutMs);
-    const finish = (result: { exitCode: number | null; signal: string | null; error: string | null }) => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      clearTimeout(timer);
-      resolve({ ...result, stdout, stderr, stdoutBytes, stderrBytes, truncated, timedOut });
-    };
-    child.stdout?.on('data', (chunk: Buffer) => {
-      stdoutBytes += chunk.length;
-      const next = chunk.toString('utf8');
-      if (Buffer.byteLength(stdout, 'utf8') < MAX_CAPTURE_BYTES) {
-        stdout += next;
-      } else {
-        truncated = true;
-      }
-    });
-    child.stderr?.on('data', (chunk: Buffer) => {
-      stderrBytes += chunk.length;
-      const next = chunk.toString('utf8');
-      if (Buffer.byteLength(stderr, 'utf8') < MAX_CAPTURE_BYTES) {
-        stderr += next;
-      } else {
-        truncated = true;
-      }
-    });
-    child.on('error', (error) => finish({ exitCode: null, signal: null, error: error.message }));
-    child.on('close', (code, signal) => finish({ exitCode: code, signal, error: null }));
-  });
-}
-
-async function writeValidationArtifact(projectRoot: string, runId: string, branch: string, task: SddTask, status: SddTestStatus, steps: SddTestCommandStep[], gaps: string[], _capabilityEvidence: CapabilityEvidenceClassification[]): Promise<{ absolutePath: string; runRelativePath: string }> {
-  const artifactPath = validationArtifactPath(task);
-  const stageEvidenceRef = toBranchStageEvidenceRef(branch, 'test', artifactPath);
-  const resultStatus = status === 'PASS' ? 'PASS' : status === 'FAIL' ? 'FAIL' : 'BLOCKED';
-  const content = `# Test Validation ${task.id}\n\n\`\`\`sdd-result\ncontract: ${SDD_RESULT_CONTRACT}\nversion: ${SDD_RESULT_VERSION}\nagent: validator\ntask: ${task.id}\nstatus: ${resultStatus}\nartifacts:\n  - ${stageEvidenceRef}\n\`\`\`\n\n## Test Runtime\n\n- status: ${status}\n- commands:\n${steps.length > 0 ? steps.map((step) => `  - [${step.status}] ${step.command}`).join('\n') : '  - none'}\n- gaps:\n${gaps.length > 0 ? gaps.map((gap) => `  - ${gap}`).join('\n') : '  - none'}\n\n## Acceptance Evidence\n\n${renderEvidenceBlocks(task, status, stageEvidenceRef, steps)}\n`;
-  const written = await recordStageEvidenceArtifact(projectRoot, runId, stageEvidenceRef, content, { taskId: task.id, artifactRole: 'test-validation' });
-  return { ...written, runRelativePath: stageEvidenceRef };
-}
-
-function validationArtifactPath(task: SddTask): string {
-  return `test-validation-${task.id}.md`;
-}
-
-
-
-async function persistTestRunState(projectRoot: string, state: RunState, taskId: string, validationStatus: SddTestStatus, commands: string[], evidence: string[], validationArtifact: string | null): Promise<void> {
-  const latest = await readRunState(projectRoot, state.runId);
-  const knownArtifacts = new Set(latest.artifacts.map((artifact) => artifact.path));
-  const now = new Date().toISOString();
-  const nextArtifacts = evidence
-    .filter((artifactPath) => !knownArtifacts.has(artifactPath))
-    .map((artifactPath) => ({ path: artifactPath, kind: testArtifactKind(artifactPath), task: taskId, agent: 'test-runtime', createdAt: now }));
-  const existingTaskState = latest.tasks[taskId];
-  await writeRunState(projectRoot, {
-    ...latest,
-    status: validationStatus === 'PASS' ? 'running' : validationStatus === 'FAIL' ? 'failed' : 'blocked',
-    phase: 'test',
-    currentTask: taskId,
-    tasks: {
-      ...latest.tasks,
-      [taskId]: {
-        ...baseRuntimeTaskState(existingTaskState),
-        status: validationStatus === 'PASS' ? 'validation_passed_pending_gate' : validationStatus === 'FAIL' ? 'validation_failed' : 'validation_blocked',
-        implementationStatus: existingTaskState?.implementationStatus ?? 'not_started',
-        verificationStatus: verificationStatusFromTest(validationStatus),
-        testStatus: validationStatus,
-        evidence
-      }
-    },
-    artifacts: [...latest.artifacts, ...nextArtifacts],
-    validation: {
-      status: validationStatus === 'PASS' ? 'pass' : validationStatus === 'FAIL' ? 'fail' : 'blocked',
-      commands,
-      evidence
-    }
-  });
-}
-
-async function persistTestGateOutcome(projectRoot: string, runId: string, taskId: string, status: SddTestStatus, validationStatus: SddTestStatus, commands: string[], evidence: string[], validationArtifact: string | null, gateDecision: WorkflowGateDecision): Promise<void> {
-  const latest = await readRunState(projectRoot, runId);
-  const knownArtifacts = new Set(latest.artifacts.map((artifact) => artifact.path));
-  const now = new Date().toISOString();
-  const nextArtifacts = evidence
-    .filter((artifactPath) => !knownArtifacts.has(artifactPath))
-    .map((artifactPath) => ({ path: artifactPath, kind: testArtifactKind(artifactPath), task: taskId, agent: 'test-runtime', createdAt: now }));
-  const existingTaskState = latest.tasks[taskId];
-  await writeRunState(projectRoot, {
-    ...latest,
-    status: status === 'PASS' ? 'completed' : status === 'FAIL' ? 'failed' : 'blocked',
-    phase: 'test',
-    currentTask: taskId,
-    tasks: {
-      ...latest.tasks,
-      [taskId]: {
-        ...baseRuntimeTaskState(existingTaskState),
-        status: runtimeTaskStatusAfterGate(status, validationStatus),
-        implementationStatus: existingTaskState?.implementationStatus ?? 'not_started',
-        verificationStatus: verificationStatusFromTest(validationStatus),
-        testStatus: status,
-        validationStatus,
-        workflowGateStatus: gateDecision.status,
-        workflowGateDecisionId: gateDecision.decisionId,
-        evidence
-      }
-    },
-    artifacts: [...latest.artifacts, ...nextArtifacts],
-    validation: {
-      status: validationStatus === 'PASS' ? 'pass' : validationStatus === 'FAIL' ? 'fail' : 'blocked',
-      commands,
-      evidence
-    }
-  });
-}
-
-function testArtifactKind(artifactPath: string): string {
-  const fileName = artifactPath.split('/').pop() ?? artifactPath;
-  if (fileName.startsWith('test-validation-')) {
-    return 'test-validation';
-  }
-  return 'test';
-}
-
-function baseRuntimeTaskState(existing: RunStateTaskRuntime | undefined): RunStateTaskRuntime {
-  return {
-    status: existing?.status ?? 'not_started',
-    implementationStatus: existing?.implementationStatus ?? 'not_started',
-    verificationStatus: existing?.verificationStatus ?? 'not_run',
-    validationBatch: existing?.validationBatch ?? null,
-    validationTiming: existing?.validationTiming ?? 'task_end',
-    requiresVerifyBeforeNext: existing?.requiresVerifyBeforeNext ?? true,
-    gaps: existing?.gaps,
-    artifacts: existing?.artifacts,
-    testStatus: existing?.testStatus,
-    workflowGateStatus: existing?.workflowGateStatus,
-    workflowGateDecisionId: existing?.workflowGateDecisionId,
-    evidence: existing?.evidence
-  };
-}
-
-function verificationStatusFromTest(validationStatus: SddTestStatus): RunStateTaskRuntime['verificationStatus'] {
-  if (validationStatus === 'PASS') {
-    return 'pass';
-  }
-  return validationStatus === 'FAIL' ? 'failed' : 'blocked';
-}
-
-function runtimeTaskStatusAfterGate(status: SddTestStatus, validationStatus: SddTestStatus): string {
-  if (status === 'PASS') {
-    return 'implemented_verified';
-  }
-  if (validationStatus === 'PASS') {
-    return 'workflow_gate_blocked';
-  }
-  return validationStatus === 'FAIL' ? 'validation_failed' : 'validation_blocked';
-}
-
-function deriveCommandStatus(gaps: string[], steps: SddTestCommandStep[]): TestEvidenceStatus {
-  if (gaps.length > 0 || steps.some((step) => step.status === 'blocked')) {
-    return 'BLOCKED';
-  }
-  if (steps.some((step) => step.status === 'fail')) {
-    return 'FAIL';
-  }
-  return 'PASS';
-}
-
-function buildAcceptanceCoverage(task: SddTask | null, steps: SddTestCommandStep[], commandStatus: TestEvidenceStatus, acceptanceRefsOverride: string[] | undefined): AcceptanceEvidenceCoverage[] {
-  const acceptanceRefs = acceptanceRefsOverride && acceptanceRefsOverride.length > 0 ? [...new Set(acceptanceRefsOverride)] : task ? taskAcceptanceRefs(task) : [];
-  return acceptanceRefs.map((acceptanceRef) => {
-    const mappedSteps = steps.filter((step) => step.acceptanceRefs.includes(acceptanceRef));
-    const hasPassingEvidence = mappedSteps.some((step) => step.status === 'pass');
-    const hasFailingEvidence = mappedSteps.some((step) => step.status === 'fail' || step.status === 'blocked');
-    const status: EvidenceCoverageStatus = hasPassingEvidence && !hasFailingEvidence && commandStatus === 'PASS'
-      ? 'complete'
-      : mappedSteps.length > 0
-        ? 'partial'
-        : 'missing';
-    return {
-      acceptanceRef,
-      status,
-      evidenceRefs: mappedSteps.map(commandStepRuntimeRef),
-      gaps: status === 'complete' ? [] : [`Acceptance ${acceptanceRef} has no complete non-stale evidence from sdd test task.`]
-    };
-  });
-}
-
-function runtimeEvidenceRefs(validationArtifact: string | null, steps: SddTestCommandStep[]): string[] {
-  return [validationArtifact, ...steps.map((step) => step.outputArtifact)].filter((item): item is string => Boolean(item));
-}
-
-function commandStepRuntimeRef(step: SddTestCommandStep): { kind: 'command'; ref: string } {
-  return { kind: 'command', ref: step.stepId };
-}
-
-function artifactRuntimeRefs(ref: string | null): Array<{ kind: 'artifact'; ref: string }> {
-  return ref ? [{ kind: 'artifact', ref }] : [];
-}
-
-function summarizeEvidenceCoverage(acceptanceCoverage: AcceptanceEvidenceCoverage[]): EvidenceCoverageStatus {
-  if (acceptanceCoverage.length === 0) {
-    return 'missing';
-  }
-  if (acceptanceCoverage.every((coverage) => coverage.status === 'complete')) {
-    return 'complete';
-  }
-  if (acceptanceCoverage.some((coverage) => coverage.status === 'complete' || coverage.status === 'partial')) {
-    return 'partial';
-  }
-  return 'missing';
-}
-
-function derivePolicyJudgment(commandStatus: TestEvidenceStatus, evidenceCoverage: EvidenceCoverageStatus): SddTestStatus {
-  if (commandStatus === 'FAIL') {
-    return 'FAIL';
-  }
-  if (commandStatus === 'BLOCKED' || evidenceCoverage !== 'complete') {
-    return 'BLOCKED';
-  }
-  return 'PASS';
-}
-
-async function resolveTestRuntimeDurableGap(
-  projectRoot: string,
-  branch: string,
-  runId: string,
-  taskId: string,
-  validationStatus: SddTestStatus,
-  gaps: string[]
-): Promise<void> {
-  if (validationStatus !== 'PASS' || gaps.length > 0) {
-    return;
-  }
-  await updateRuntimeDurableGapStatus(projectRoot, {
-    gapId: testRuntimeGapId(branch, runId, taskId),
-    status: 'resolved',
-    source: 'gate_policy',
-    payload: { validationStatus, gaps }
-  });
-}
-
-async function recordTestRuntimeDurableGap(
-  projectRoot: string,
-  branch: string,
-  runId: string,
-  taskId: string,
-  status: SddTestStatus,
-  validationStatus: SddTestStatus,
-  runtimeJudgment: WorkflowGateStatus,
-  gaps: string[],
-  evidenceRefs: string[]
-): Promise<void> {
-  if (status === 'PASS' && gaps.length === 0) {
-    return;
-  }
-  const message = gaps[0] ?? (runtimeJudgment === 'PASS' ? `Validation status is ${validationStatus}.` : `Workflow gate status is ${runtimeJudgment}.`);
-  await recordRuntimeDurableGap(projectRoot, {
-    gapId: testRuntimeGapId(branch, runId, taskId),
-    partition: branch,
-    taskId,
-    runId,
-    stage: 'test',
-    gate: 'test',
-    source: 'runtime',
-    category: runtimeJudgment === 'PASS' ? 'validation' : 'workflow_gate',
-    severity: 'blocking',
-    status: 'open',
-    message,
-    recommendation: `Resolve test runtime gaps for ${taskId}, then rerun ${testValidationUnitCommand(branch, taskId)}.`,
-    evidenceRefs,
-    proposalRefs: [],
-    sourceRefs: [],
-    payload: { status, validationStatus, runtimeJudgment, gaps }
-  });
-}
-
-function testRuntimeGapId(branch: string, _runId: string, taskId: string): string {
-  return runtimeScopedId(branch, taskId, 'test-runtime-gap');
-}
-
-function finalStatusForTest(validationStatus: SddTestStatus, runtimeJudgment: WorkflowGateStatus): SddTestStatus {
-  if (validationStatus !== 'PASS') {
-    return validationStatus;
-  }
-  return runtimeJudgment === 'PASS' || runtimeJudgment === 'WARN' ? 'PASS' : 'BLOCKED';
-}
-
-function buildUnifiedTestEvidenceRun(id: string, branch: string, runId: string, taskId: string, commandStatus: TestEvidenceStatus, evidenceCoverage: EvidenceCoverageStatus, policyJudgment: TestEvidenceStatus, status: SddTestStatus, runtimeJudgment: WorkflowGateStatus, steps: SddTestCommandStep[], acceptanceCoverage: AcceptanceEvidenceCoverage[], capabilityEvidence: CapabilityEvidenceClassification[], gaps: string[], gateNextAction: string | null, gateDecision: WorkflowGateDecision | null): UnifiedTestEvidenceRun {
-  return {
-    contract: TEST_EVIDENCE_RUN_CONTRACT_VERSION,
-    id,
-    scope: { branch, taskId, runId },
-    commandStatus,
-    evidenceCoverage,
-    policyJudgment,
-    commands: steps.map((step) => ({
-      command: step.command,
-      status: step.status === 'pass' ? 'PASS' : step.status === 'fail' ? 'FAIL' : 'BLOCKED',
-      outputRef: step.outputArtifact ? { kind: 'artifact', ref: step.outputArtifact } : undefined,
-      evidenceRefs: [commandStepRuntimeRef(step), ...artifactRuntimeRefs(step.outputArtifact)],
-      acceptanceRefs: step.acceptanceRefs,
-      startedAt: new Date(Date.now() - step.durationMs).toISOString(),
-      completedAt: new Date().toISOString()
-    })),
-    acceptanceCoverage,
-    capabilityEvidence,
-    gaps: [...gaps, ...acceptanceCoverage.flatMap((coverage) => coverage.gaps)],
-    next: nextForTestResult(status, runtimeJudgment, branch, taskId, gateNextAction, gateDecision),
-    generatedAt: new Date().toISOString()
-  };
-}
-
-function buildCapabilityEvidenceClassification(decision: AgentCapabilityRouteDecision | null, steps: SddTestCommandStep[]): CapabilityEvidenceClassification[] {
-  if (!decision) {
-    return [{
-      class: 'diagnostic',
-      source: 'runtime_diagnostic',
-      domainOrSourceId: 'capability-routing',
-      evidenceRefs: [],
-      acceptanceRefs: [],
-      provenanceRefs: [],
-      reason: 'Capability routing did not run; no capability output is accepted as test evidence.'
-    }];
-  }
-  const acceptanceRefs = [...new Set(steps.flatMap((step) => step.acceptanceRefs))];
-  const professionalEvidence = decision.selectedDomains.map((domain) => ({
-    class: 'candidate' as const,
-    source: 'professional_capability' as const,
-    domainOrSourceId: domain.domain,
-    evidenceRefs: [],
-    acceptanceRefs,
-    provenanceRefs: [{ kind: 'projection' as const, ref: `capability:${domain.capabilityId}` }],
-    reason: `${domain.reason}; capability output is advisory candidate evidence until accepted by command evidence and policy refs.`
-  }));
-  const externalEvidence = decision.rejectedExternalSources.map((source) => ({
-    class: capabilityClassForRejectedSource(source.quarantineStatus) as CapabilityEvidenceClassification['class'],
-    source: 'external_source' as const,
-    domainOrSourceId: source.sourceId,
-    evidenceRefs: [],
-    acceptanceRefs: [],
-    provenanceRefs: [{ kind: 'external' as const, ref: source.sourceId }],
-    reason: source.reason
-  }));
-  return [...professionalEvidence, ...externalEvidence];
-}
-
-function capabilityClassForRejectedSource(status: AgentCapabilityRouteDecision['rejectedExternalSources'][number]['quarantineStatus']): CapabilityEvidenceClassification['class'] {
-  if (status === 'denied') {
-    return 'blocked';
-  }
-  if (status === 'required' || status === 'quarantined') {
-    return 'quarantined';
-  }
-  return 'diagnostic';
-}
-
-
-function capabilityEvidenceSummary(items: CapabilityEvidenceClassification[]): string {
-  if (items.length === 0) {
-    return 'none';
-  }
-  const counts = new Map<CapabilityEvidenceClassification['class'], number>();
-  for (const item of items) {
-    counts.set(item.class, (counts.get(item.class) ?? 0) + 1);
-  }
-  return [...counts.entries()].map(([kind, count]) => `${kind}:${count}`).join(',');
-}
-
-function nextForTestResult(status: SddTestStatus, runtimeJudgment: WorkflowGateStatus, branch: string, taskId: string, gateNextAction: string | null, gateDecision: WorkflowGateDecision | null): string {
-  const inspectHint = `Inspect runtime test read model for ${taskId}`;
-  if (status === 'PASS') {
-    return `sdd test close --branch ${branch} --target goal-verify --compact-json`;
-  }
-  if (gateNextAction) {
-    return gateNextAction;
-  }
-  if (runtimeJudgment === 'HUMAN_REQUIRED') {
-    return gateDecision ? `Create a decision card for workflow gate ${gateDecision.decisionId}, then rerun ${testValidationUnitCommand(branch, taskId)}.` : `Create a decision card, then rerun ${testValidationUnitCommand(branch, taskId)}.`;
-  }
-  if (runtimeJudgment === 'WARN') {
-    return gateDecision ? `Review workflow gate ${gateDecision.decisionId} warnings, then rerun ${testValidationUnitCommand(branch, taskId)} or proceed only with explicit review.` : `Review workflow gate warnings, then rerun ${testValidationUnitCommand(branch, taskId)}.`;
-  }
-  if (runtimeJudgment === 'ADVISORY_ONLY') {
-    return `Inspect advisor assessments for ${taskId}; advisory output cannot satisfy the test gate.`;
-  }
-  if (status === 'FAIL') {
-    return `${inspectHint}, fix failing validation commands, then rerun ${testValidationUnitCommand(branch, taskId)}.`;
-  }
-  return gateDecision ? `${inspectHint} and workflow gate ${gateDecision.decisionId}, resolve blockers, then rerun ${testValidationUnitCommand(branch, taskId)}.` : `${inspectHint}, fix command/evidence gaps, then rerun ${testValidationUnitCommand(branch, taskId)}.`;
-}
-
-
-function testValidationUnitCommand(branch: string, taskId: string): string {
-  return `sdd test task-${taskId} --branch ${branch}`;
-}
-
-function resultSentenceForTest(result: SddTestResult): string {
-  if (result.status === 'PASS') {
-    return 'Validation and workflow gate passed; proceed to goal verification and truthAlignment before release readiness.';
-  }
-  if (result.validationStatus === 'PASS' && result.workflowGateStatus !== 'PASS') {
-    return `Validation passed, but workflow gate returned ${result.workflowGateStatus}.`;
-  }
-  if (result.commandStatus === 'BLOCKED') {
-    return 'Blocked before validation commands ran.';
-  }
-  return result.status === 'FAIL' ? 'Validation failed.' : 'Validation did not produce complete evidence.';
-}
-
-function renderEvidenceBlocks(task: SddTask, status: SddTestStatus, sourceArtifact: string, steps: SddTestCommandStep[]): string {
-  const acceptances = task.acceptanceRefs.length > 0 ? task.acceptanceRefs : task.acceptance;
-  if (acceptances.length === 0) {
-    return 'No acceptance targets declared.';
-  }
-  const mappedEvidence = acceptances
-    .map((acceptance) => ({ acceptance, steps: steps.filter((step) => step.acceptanceRefs.includes(acceptance)) }))
-    .filter((item) => item.steps.length > 0);
-  if (mappedEvidence.length === 0) {
-    return 'No acceptance evidence emitted; validation commands are not explicitly mapped to acceptance refs.';
-  }
-  return mappedEvidence.map(({ acceptance, steps: mappedSteps }) => {
-    const evidenceStatus = evidenceStatusForMappedSteps(status, mappedSteps);
-    return `\`\`\`sdd-evidence\ncontract: ${SDD_EVIDENCE_CONTRACT}\nversion: ${SDD_EVIDENCE_VERSION}\ntask: ${task.id}\nacceptance: ${acceptance}\nstatus: ${evidenceStatus}\nclaim: Explicit validation mapping ${mappedSteps.map((step) => step.command).join(' && ')} produced ${evidenceStatus} for ${acceptance}.\nsource_artifact: ${sourceArtifact}\nevidence_refs:\n${mappedSteps.map(renderStepEvidenceRefs).join('\n')}\nprovenance_refs:\n  - artifact:${sourceArtifact}\n${mappedSteps.map((step) => `  - command:${step.command}`).join('\n')}\npolicy_refs:\n  - ${ACCEPTANCE_POLICY_RULESET_VERSION}:require-source-evidence\n  - ${ACCEPTANCE_POLICY_RULESET_VERSION}:require-provenance\n  - ${ACCEPTANCE_POLICY_RULESET_VERSION}:require-policy-rule\n\`\`\``;
-  }).join('\n\n');
-}
-
-function normalizeTestCommandInputs(commandInputs: SddTestCommandInput[] | undefined, commands: string[] | undefined, taskValidation: string[]): NormalizedSddTestCommand[] {
-  if (commandInputs && commandInputs.length > 0) {
-    return commandInputs.map(normalizeTestCommandInput);
-  }
-  return (commands && commands.length > 0 ? commands : taskValidation).map((command) => ({ command, argv: null, shell: true }));
-}
-
-function normalizeTestCommandInput(input: SddTestCommandInput): NormalizedSddTestCommand {
-  if (input.argv) {
-    const argv = input.argv.filter((item) => item.length > 0);
-    if (argv.length === 0) {
-      throw new Error('Command argv input must include an executable.');
-    }
-    return { command: argv.join(' '), argv, shell: false };
-  }
-  if (input.command) {
-    return { command: input.command, argv: null, shell: true };
-  }
-  throw new Error('Command input must include command or argv.');
-}
-
-function acceptanceRefsForCommand(task: SddTask | null, command: string, acceptanceRefsOverride: string[] | undefined): string[] {
-  if (acceptanceRefsOverride && acceptanceRefsOverride.length > 0) {
-    return [...new Set(acceptanceRefsOverride)];
-  }
-  return [...new Set((task?.validationCommands ?? [])
-    .filter((entry) => entry.command === command)
-    .flatMap((entry) => entry.acceptanceRefs))];
-}
-
-function taskAcceptanceRefs(task: SddTask): string[] {
-  const refs = task.acceptanceRefs.length > 0 ? task.acceptanceRefs : task.acceptance;
-  return [...new Set(refs)];
-}
-
-function evidenceStatusForMappedSteps(status: SddTestStatus, steps: SddTestCommandStep[]): SddTestStatus {
-  if (steps.some((step) => step.status === 'fail')) {
-    return 'FAIL';
-  }
-  if (status === 'BLOCKED' || steps.some((step) => step.status === 'blocked')) {
-    return 'BLOCKED';
-  }
-  return 'PASS';
-}
-
-function renderCommandOutput(commandInput: NormalizedSddTestCommand, status: SddTestStepStatus, executed: { exitCode: number | null; signal: string | null; stdout: string; stderr: string; truncated: boolean; timedOut: boolean; error: string | null }, durationMs: number, cacheStatus: 'hit' | 'miss' | 'unsafe' = 'unsafe', cacheKey: string | null = null, cacheSourceTestRunId: string | null = null, cacheUnsafeReasons: ValidationCacheUnsafeReason[] = []): string {
-  return `# Test Command Output\n\n- command: ${commandInput.command}\n- shell: ${commandInput.shell}\n- argv: ${commandInput.argv ? JSON.stringify(commandInput.argv) : 'none'}\n- status: ${status}\n- exit_code: ${executed.exitCode ?? 'none'}\n- signal: ${executed.signal ?? 'none'}\n- duration_ms: ${durationMs}\n- timed_out: ${executed.timedOut}\n- truncated: ${executed.truncated}\n- error: ${executed.error ?? 'none'}\n- cache_status: ${cacheStatus}\n- cache_key: ${cacheKey ?? 'none'}\n- cache_source_test_run: ${cacheSourceTestRunId ?? 'none'}\n- cache_unsafe_reasons: ${cacheUnsafeReasons.join(',') || 'none'}\n\n## stdout\n\n\`\`\`text\n${executed.stdout}\n\`\`\`\n\n## stderr\n\n\`\`\`text\n${executed.stderr}\n\`\`\`\n`;
-}
-
-function shouldPersistCommandOutputArtifact(status: SddTestStepStatus, executed: { truncated: boolean; timedOut: boolean; error: string | null }, cacheStatus: 'hit' | 'miss' | 'unsafe', cacheUnsafeReasons: ValidationCacheUnsafeReason[]): boolean {
-  return status !== 'pass' || executed.truncated || executed.timedOut || Boolean(executed.error) || cacheStatus === 'unsafe' || cacheUnsafeReasons.length > 0;
-}
-
-function renderStepEvidenceRefs(step: SddTestCommandStep): string {
-  const refs = [`  - command:${step.stepId}`];
-  if (step.outputArtifact) {
-    refs.push(`  - artifact:${step.outputArtifact}`);
-  }
-  return refs.join('\n');
-}
-
-
-function summarizeCommandOutput(executed: { exitCode: number | null; signal: string | null; stdout: string; stderr: string; stdoutBytes: number; stderrBytes: number; truncated: boolean; timedOut: boolean; error: string | null }): string {
-  const parts = [
-    `exit=${executed.exitCode ?? 'none'}`,
-    `signal=${executed.signal ?? 'none'}`,
-    `stdout_bytes=${executed.stdoutBytes}`,
-    `stderr_bytes=${executed.stderrBytes}`,
-    `truncated=${executed.truncated}`,
-    `timed_out=${executed.timedOut}`
-  ];
-  if (executed.error) {
-    parts.push(`error=${executed.error}`);
-  }
-  return parts.join(' ');
-}
-
-
-function hashDocumentContent(raw: string): string {
-  return createHash('sha256').update(raw.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
-}
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { appendEvent } from '../run-state/events.js';
+import { appendArtifactHashLedgerEntry, appendInvocationLedgerEntry } from '../run-state/invocation-ledger.js';
+import type { RunState, RunStateTaskRuntime } from '../run-state/model.js';
+import { createRun, readAllRunStates, readRunState, writeRunState } from '../run-state/run-state.js';
+import { recordRuntimeOnlyArtifact, recordStageEvidenceArtifact } from '../run-state/artifacts.js';
+import { toBranchStageEvidenceRef } from '../runtime-paths.js';
+import { resolveSddContext } from '../sdd-docs/context.js';
+import { bindRunStateToTask } from '../sdd-docs/run-binding.js';
+import { parseSddBranch, type SddTask, type SddTaskModel } from '../sdd-docs/task-parser.js';
+import { inspectSddTask } from '../sdd-docs/task-inspection.js';
+import { listRuntimeArtifactPayloads, readRuntimeValidationCacheEntry, recordRuntimeAcceptanceEvidenceMap, recordRuntimeDurableGap, recordRuntimeProjection, recordRuntimeTestRun, recordRuntimeTestStep, recordRuntimeValidationCacheEntry, recordRuntimeValidationCacheUse, recordRuntimeValidationEnvironmentSession, recordRuntimeValidationWaveRun, runtimeScopedId, updateRuntimeDurableGapStatus, type RuntimeValidationCacheEntryRecord } from '../storage/runtime-store.js';
+import { ACCEPTANCE_POLICY_RULESET_VERSION, SDD_EVIDENCE_CONTRACT, SDD_EVIDENCE_VERSION, SDD_RESULT_CONTRACT, SDD_RESULT_VERSION, TEST_EVIDENCE_RUN_CONTRACT_VERSION, WORKFLOW_HANDOFF_CONTRACT_VERSION } from '../contracts.js';
+import type { LifecycleRiskDecision } from '../risk/contracts.js';
+import { inspectVerifyContract, type VerifyContractInspection } from './verify-contract.js';
+import type { AcceptanceEvidenceCoverage, CapabilityEvidenceClassification, EvidenceCoverageStatus, TestEvidenceStatus, UnifiedTestEvidenceRun } from '../evidence-runtime.js';
+import { ensureTaskOrchestration, inspectOrchestrationGate } from '../orchestration/runtime.js';
+import { recordStageRunProjection, recordWorkflowHandoffProjection, validateWorkflowHandoff } from '../stage-runtime/runtime.js';
+import type { StageRun, WorkflowHandoff } from '../stage-runtime/contracts.js';
+import { evaluateTaskWorkflowGate, verifyContractBlockedGate, type ApprovalPolicy, type LifecycleRiskProfile, type LifecycleWorkflowGate } from '../risk.js';
+import { validateSddResultArtifact } from '../artifacts/sdd-result.js';
+import { dependencyBlockingReasonsForTask } from '../workflow-state/dependencies.js';
+import { selectLatestEligibleRunsByTask } from '../workflow-state/latest-eligible-run.js';
+import { latestRuntimeTaskStates } from '../workflow-state/resolve.js';
+import { routeSddTask } from '../router/route-sdd-task.js';
+import type { AgentCapabilityRouteDecision } from '../router/agent-runtime.js';
+import { evaluateAndRecordWorkflowGateDecision } from '../workflow-gate/evidence-packet.js';
+import type { WorkflowGateDecision, WorkflowGateStatus } from '../workflow-gate/types.js';
+import { buildValidationCachePlan, type ValidationCacheUnsafeReason } from './validation-cache.js';
+
+const DEFAULT_TEST_TIMEOUT_MS = 120_000;
+const MAX_CAPTURE_BYTES = 256 * 1024;
+
+export type SddTestStatus = 'PASS' | 'FAIL' | 'BLOCKED';
+export type SddTestStepStatus = 'pass' | 'fail' | 'blocked';
+
+export interface SddTestCommandInput {
+  command?: string;
+  argv?: string[];
+}
+
+export interface SddTestCommandStep {
+  stepId: string;
+  command: string;
+  argv: string[] | null;
+  shell: boolean;
+  acceptanceRefs: string[];
+  status: SddTestStepStatus;
+  exitCode: number | null;
+  signal: string | null;
+  durationMs: number;
+  outputArtifact: string | null;
+  stdoutBytes: number;
+  stderrBytes: number;
+  truncated: boolean;
+  startedAt: string;
+  endedAt: string;
+  cwd: string;
+  stdoutDigest: string;
+  stderrDigest: string;
+  outputSummary: string;
+  cacheStatus: 'hit' | 'miss' | 'unsafe';
+  cacheKey: string | null;
+  cacheSourceTestRunId: string | null;
+  cacheUnsafeReasons: ValidationCacheUnsafeReason[];
+}
+
+interface NormalizedSddTestCommand {
+  command: string;
+  argv: string[] | null;
+  shell: boolean;
+}
+
+type VerifyContractAction = 'none' | 'created' | 'refreshed' | 'blocked';
+
+type RuntimeTestJudgment = WorkflowGateStatus;
+
+export interface SddTestResult {
+  contract: 'sdd-test-runtime-v1';
+  runId: string;
+  testRunId: string;
+  validationWaveRunId: string;
+  validationEnvironmentSessionId: string;
+  branch: string;
+  taskId: string;
+  status: SddTestStatus;
+  validationStatus: SddTestStatus;
+  workflowGateStatus: WorkflowGateStatus;
+  runtimeJudgment: RuntimeTestJudgment;
+  workflowGateDecision: WorkflowGateDecision;
+  verifyContractStatus: string;
+  verifyContractAction: VerifyContractAction;
+  lifecycleGate: LifecycleWorkflowGate;
+  lifecycleProfile: LifecycleRiskProfile | null;
+  approvalPolicy: ApprovalPolicy | null;
+  requiredStages: string[];
+  primaryReason: string;
+  commandStatus: TestEvidenceStatus;
+  evidenceCoverage: EvidenceCoverageStatus;
+  policyJudgment: TestEvidenceStatus;
+  acceptanceCoverage: AcceptanceEvidenceCoverage[];
+  capabilityEvidence: CapabilityEvidenceClassification[];
+  commands: string[];
+  steps: SddTestCommandStep[];
+  validationArtifact: string | null;
+  indexArtifact: string | null;
+  gaps: string[];
+  next: string;
+}
+
+export interface RunSddTestOptions {
+  taskId: string;
+  branch?: string | null;
+  runId?: string | null;
+  commands?: string[];
+  commandInputs?: SddTestCommandInput[];
+  timeoutMs?: number;
+  approved?: boolean;
+  validationWave?: { waveRunId: string; environmentSessionId: string; taskIds: string[]; acceptanceRefsByTask?: Record<string, string[]> };
+}
+
+export async function runSddTest(projectRoot: string, options: RunSddTestOptions): Promise<SddTestResult> {
+  const context = await resolveSddContext(projectRoot, { branch: options.branch ?? undefined, branchSource: options.branch ? 'cli_option' : undefined });
+  const model = await parseSddBranch(projectRoot, context.partition);
+  const inspected = inspectSddTask(model, options.taskId);
+  const task = inspected.task;
+  const verifyContract = await ensureVerifyContractForTest(projectRoot, context.partition);
+  const verifyInspection = verifyContract.inspection;
+  const initialState = options.runId ? await readRunState(projectRoot, options.runId) : await createRun(projectRoot);
+  const state = await bindRunStateToTask(projectRoot, initialState, context, model, task, options.taskId);
+  const testRunId = runtimeScopedId(state.runId, options.taskId, new Date().toISOString(), 'sdd-test');
+  const commandInputs = normalizeTestCommandInputs(options.commandInputs, options.commands, task?.validation ?? []);
+  const commands = commandInputs.map((input) => input.command);
+  const gaps: string[] = [];
+  const startedAt = new Date().toISOString();
+  const ownsValidationWave = !options.validationWave;
+  const validationWaveRunId = options.validationWave?.waveRunId ?? runtimeScopedId(context.partition, options.taskId, state.runId, testRunId, 'validation-wave');
+  const validationEnvironmentSessionId = options.validationWave?.environmentSessionId ?? runtimeScopedId(context.partition, validationWaveRunId, 'validation-env');
+  const validationWaveTaskIds = options.validationWave?.taskIds ?? [options.taskId];
+  const validationWaveAcceptanceRefs = options.validationWave?.acceptanceRefsByTask?.[options.taskId];
+  const validationWaveScopeAcceptanceRefs = [...new Set(Object.values(options.validationWave?.acceptanceRefsByTask ?? { [options.taskId]: task?.acceptanceRefs ?? [] }).flat())].sort();
+  if (ownsValidationWave) {
+    await recordRuntimeValidationEnvironmentSession(projectRoot, {
+      sessionId: validationEnvironmentSessionId,
+      partition: context.partition,
+      runId: state.runId,
+      waveRunId: validationWaveRunId,
+      status: 'active',
+      reuseKey: `${context.partition}:${options.taskId}`,
+      createdAt: startedAt,
+      updatedAt: startedAt,
+      payload: { contract: 'phase-8.17-validation-wave-runtime-v1', mode: 'single-task' }
+    });
+    await recordRuntimeValidationWaveRun(projectRoot, {
+      waveRunId: validationWaveRunId,
+      partition: context.partition,
+      runId: state.runId,
+      taskIds: validationWaveTaskIds,
+      status: 'RUNNING',
+      environmentSessionId: validationEnvironmentSessionId,
+      startedAt,
+      completedAt: startedAt,
+      payload: { contract: 'phase-8.17-validation-wave-runtime-v1', mode: 'single-task', taskId: options.taskId }
+    });
+  }
+
+  await appendEvent(projectRoot, state.runId, {
+    event: 'test_runtime_started',
+    runId: state.runId,
+    summary: `SDD test runtime started for ${options.taskId}`,
+    data: { taskId: options.taskId, branch: context.partition, testRunId, commands }
+  });
+
+  const states = await readAllRunStates(projectRoot);
+  const latestEligibleRunsByTask = selectLatestEligibleRunsByTask({ states, model, partition: context.partition, currentGitBranch: context.currentGitBranch });
+  const runtimeByTask = latestRuntimeTaskStates(latestEligibleRunsByTask, states);
+
+  if (!task) {
+    gaps.push(`Task ${options.taskId} was not found in specs/${context.partition}/tasks.md.`);
+  }
+  if (task) {
+    gaps.push(...inspected.gaps.filter((gap) => gap.severity === 'blocking').map((gap) => `${gap.field}: ${gap.message}`));
+    gaps.push(...dependencyBlockingReasonsForTask(model, options.taskId, { runtimeByTask }));
+  }
+  if (verifyContract.action === 'blocked') {
+    gaps.push(verifyContractBlocker(verifyInspection));
+  }
+  if (commands.length === 0) {
+    gaps.push(`Task ${options.taskId} has no validation commands.`);
+  }
+  const orchestration = await ensureTaskOrchestration(projectRoot, model, task, {
+    branch: context.partition,
+    runId: state.runId,
+    taskId: options.taskId,
+    agent: 'validator',
+    stage: 'execute',
+    status: 'active'
+  });
+  const orchestrationGate = await inspectOrchestrationGate(projectRoot, {
+    branch: context.partition,
+    runId: state.runId,
+    taskId: options.taskId,
+    target: 'execution',
+    riskDecision: orchestration.riskDecision,
+    stageRun: orchestration.stageRun,
+    contextLoadSignal: orchestration.contextLoadSignal,
+    contextOffloadDecision: orchestration.contextOffloadDecision
+  });
+  const reviewerCheckpointSatisfied = await hasReviewerCheckpoint(projectRoot, state, options.taskId);
+  const workflowGate = verifyContract.action === 'blocked'
+    ? verifyContractBlockedGate(options.taskId)
+    : evaluateTaskWorkflowGate({ task, taskId: options.taskId, riskDecision: orchestration.riskDecision, approved: options.approved, reviewerCheckpointSatisfied });
+  if (workflowGate.blocksTest) {
+    gaps.push(workflowGate.primaryReason);
+  }
+  gaps.push(...orchestrationGate.blockingReasons);
+
+  await recordRuntimeTestRun(projectRoot, {
+    testRunId,
+    runId: state.runId,
+    partition: context.partition,
+    taskId: options.taskId,
+    status: 'RUNNING',
+    startedAt,
+    completedAt: startedAt,
+    payload: { verifyContractStatus: verifyInspection.status, verifyContractAction: verifyContract.action, lifecycleGate: workflowGate.lifecycleGate, lifecycleProfile: workflowGate.lifecycleProfile, approvalPolicy: workflowGate.approvalPolicy, requiredStages: workflowGate.requiredStages, primaryReason: workflowGate.primaryReason, commands, commandInputs, evidence: [], gaps }
+  });
+
+  const steps: SddTestCommandStep[] = [];
+  if (gaps.length === 0) {
+    for (const [index, commandInput] of commandInputs.entries()) {
+      const step = await runCommandStep(projectRoot, state.runId, context.partition, options.taskId, testRunId, index + 1, commandInput, acceptanceRefsForCommand(task, commandInput.command, validationWaveAcceptanceRefs), options.timeoutMs ?? DEFAULT_TEST_TIMEOUT_MS, model, task!, validationWaveTaskIds, validationWaveScopeAcceptanceRefs);
+      steps.push(step);
+      await appendEvent(projectRoot, state.runId, {
+        event: 'test_step_completed',
+        runId: state.runId,
+        summary: `SDD test step ${step.status}: ${step.command}`,
+        data: { taskId: options.taskId, testRunId, step }
+      });
+    }
+  }
+
+  const commandStatus = deriveCommandStatus(gaps, steps);
+  const acceptanceCoverage = buildAcceptanceCoverage(task, steps, commandStatus, validationWaveAcceptanceRefs);
+  const evidenceCoverage = summarizeEvidenceCoverage(acceptanceCoverage);
+  const policyJudgment = derivePolicyJudgment(commandStatus, evidenceCoverage);
+  await recordAcceptanceEvidenceMaps(projectRoot, validationWaveRunId, testRunId, context.partition, state.runId, options.taskId, acceptanceCoverage);
+  const validationStatus = policyJudgment;
+  const capabilityRoute = task ? await routeSddTask(projectRoot, { taskId: options.taskId, branch: context.partition, approved: options.approved }) : null;
+  const capabilityEvidence = buildCapabilityEvidenceClassification(capabilityRoute?.capabilityDecision ?? null, steps);
+  const validationArtifact = task ? await writeValidationArtifact(projectRoot, state.runId, context.partition, task, validationStatus, steps, gaps, capabilityEvidence) : null;
+  const evidenceBeforeGate = runtimeEvidenceRefs(validationArtifact?.runRelativePath ?? null, steps);
+  await persistTestRunState(projectRoot, state, options.taskId, validationStatus, commands, evidenceBeforeGate, validationArtifact?.runRelativePath ?? null);
+  await resolveTestRuntimeDurableGap(projectRoot, context.partition, state.runId, options.taskId, validationStatus, gaps);
+
+  const gateDecision = (await evaluateAndRecordWorkflowGateDecision(projectRoot, {
+    branch: context.partition,
+    taskId: options.taskId,
+    runId: state.runId,
+    decisionKind: 'test'
+  })).decision;
+  const runtimeJudgment = gateDecision.status;
+  const status = finalStatusForTest(validationStatus, runtimeJudgment);
+  await recordTestRuntimeDurableGap(projectRoot, context.partition, state.runId, options.taskId, status, validationStatus, runtimeJudgment, gaps, evidenceBeforeGate);
+  const unifiedEvidence = buildUnifiedTestEvidenceRun(testRunId, context.partition, state.runId, options.taskId, commandStatus, evidenceCoverage, policyJudgment, status, runtimeJudgment, steps, acceptanceCoverage, capabilityEvidence, gaps, workflowGate.nextAction, gateDecision);
+  const completedAt = new Date().toISOString();
+  const evidence = runtimeEvidenceRefs(validationArtifact?.runRelativePath ?? null, steps);
+
+  await recordRuntimeTestRun(projectRoot, {
+    testRunId,
+    runId: state.runId,
+    partition: context.partition,
+    taskId: options.taskId,
+    status,
+    startedAt,
+    completedAt,
+    payload: { verifyContractStatus: verifyInspection.status, verifyContractAction: verifyContract.action, lifecycleGate: workflowGate.lifecycleGate, lifecycleProfile: workflowGate.lifecycleProfile, approvalPolicy: workflowGate.approvalPolicy, requiredStages: workflowGate.requiredStages, primaryReason: workflowGate.primaryReason, commandStatus, evidenceCoverage, policyJudgment, validationStatus, workflowGateStatus: gateDecision.status, runtimeJudgment, workflowGateDecision: gateDecision, acceptanceCoverage, capabilityEvidence, commands, commandInputs, evidence, gaps }
+  });
+  await recordRuntimeProjection(projectRoot, 'test_runtime', `${context.partition}:${options.taskId}:${state.runId}`, {
+    contract: 'sdd-test-runtime-v1',
+    testRunId,
+    runId: state.runId,
+    taskId: options.taskId,
+    status,
+    validationStatus,
+    workflowGateStatus: gateDecision.status,
+    runtimeJudgment,
+    lifecycleGate: workflowGate.lifecycleGate,
+    primaryReason: workflowGate.primaryReason,
+    evidence,
+    gaps
+  });
+  await recordRuntimeProjection(projectRoot, 'test_evidence_run', `${context.partition}:${options.taskId}:${state.runId}`, unifiedEvidence);
+  await recordTestWorkflowProjection(projectRoot, {
+    taskId: options.taskId,
+    stageRun: orchestration.stageRun,
+    status,
+    completedAt,
+    evidence,
+    gaps,
+    riskDecision: orchestration.riskDecision
+  });
+  await persistTestGateOutcome(projectRoot, state.runId, options.taskId, status, validationStatus, commands, evidence, validationArtifact?.runRelativePath ?? null, gateDecision);
+  if (ownsValidationWave) {
+    await recordRuntimeValidationWaveRun(projectRoot, {
+      waveRunId: validationWaveRunId,
+      partition: context.partition,
+      runId: state.runId,
+      taskIds: validationWaveTaskIds,
+      status,
+      environmentSessionId: validationEnvironmentSessionId,
+      startedAt,
+      completedAt,
+      payload: { contract: 'phase-8.17-validation-wave-runtime-v1', mode: 'single-task', taskId: options.taskId, testRunId, evidence, gaps, workflowGateDecision: gateDecision }
+    });
+    await recordRuntimeValidationEnvironmentSession(projectRoot, {
+      sessionId: validationEnvironmentSessionId,
+      partition: context.partition,
+      runId: state.runId,
+      waveRunId: validationWaveRunId,
+      status: status === 'PASS' ? 'completed' : status === 'FAIL' ? 'failed' : 'blocked',
+      reuseKey: `${context.partition}:${options.taskId}`,
+      createdAt: startedAt,
+      updatedAt: completedAt,
+      payload: { contract: 'phase-8.17-validation-wave-runtime-v1', mode: 'single-task', taskId: options.taskId, validationStatus, workflowGateStatus: gateDecision.status, status }
+    });
+  }
+
+  await appendEvent(projectRoot, state.runId, {
+    event: status === 'PASS' ? 'test_runtime_passed' : 'test_runtime_blocked',
+    runId: state.runId,
+    summary: `SDD test runtime ${status} for ${options.taskId}`,
+    data: { taskId: options.taskId, testRunId, status, validationStatus, evidence, gaps, gateDecisionId: gateDecision.decisionId, gateStatus: gateDecision.status }
+  });
+
+  return {
+    contract: 'sdd-test-runtime-v1',
+    runId: state.runId,
+    testRunId,
+    validationWaveRunId,
+    validationEnvironmentSessionId,
+    branch: context.partition,
+    taskId: options.taskId,
+    status,
+    validationStatus,
+    workflowGateStatus: gateDecision.status,
+    runtimeJudgment,
+    workflowGateDecision: gateDecision,
+    verifyContractStatus: verifyInspection.status,
+    verifyContractAction: verifyContract.action,
+    lifecycleGate: workflowGate.lifecycleGate,
+    lifecycleProfile: workflowGate.lifecycleProfile,
+    approvalPolicy: workflowGate.approvalPolicy,
+    requiredStages: workflowGate.requiredStages,
+    primaryReason: workflowGate.primaryReason,
+    commandStatus,
+    evidenceCoverage,
+    policyJudgment,
+    acceptanceCoverage,
+    capabilityEvidence,
+    commands,
+    steps,
+    validationArtifact: validationArtifact?.runRelativePath ?? null,
+    indexArtifact: null,
+    gaps,
+    next: nextForTestResult(status, runtimeJudgment, context.partition, options.taskId, workflowGate.nextAction, gateDecision)
+  };
+}
+
+async function recordAcceptanceEvidenceMaps(projectRoot: string, waveRunId: string, testRunId: string, partition: string, runId: string, taskId: string, acceptanceCoverage: AcceptanceEvidenceCoverage[]): Promise<void> {
+  const createdAt = new Date().toISOString();
+  for (const coverage of acceptanceCoverage) {
+    await recordRuntimeAcceptanceEvidenceMap(projectRoot, {
+      mapId: runtimeScopedId(waveRunId, testRunId, taskId, coverage.acceptanceRef),
+      waveRunId,
+      testRunId,
+      partition,
+      runId,
+      taskId,
+      acceptanceRef: coverage.acceptanceRef,
+      status: coverage.status,
+      evidenceRefs: coverage.evidenceRefs.map((ref) => ref.ref),
+      gaps: coverage.gaps,
+      createdAt,
+      payload: coverage
+    });
+  }
+}
+
+async function recordTestWorkflowProjection(projectRoot: string, input: { taskId: string; stageRun: StageRun; status: SddTestStatus; completedAt: string; evidence: string[]; gaps: string[]; riskDecision: LifecycleRiskDecision }): Promise<void> {
+  const outputRefs = input.evidence.map((ref) => ({ kind: 'artifact' as const, ref }));
+  const completedStage: StageRun = {
+    ...input.stageRun,
+    status: input.status === 'PASS' ? 'completed' : input.status === 'FAIL' ? 'failed' : 'blocked',
+    outputRefs,
+    blockingReasons: input.status === 'PASS' ? [] : input.gaps.length > 0 ? input.gaps : [`SDD test ${input.status}.`],
+    updatedAt: input.completedAt
+  };
+  await recordStageRunProjection(projectRoot, completedStage);
+
+  const handoff: WorkflowHandoff = {
+    contract: WORKFLOW_HANDOFF_CONTRACT_VERSION,
+    id: `${completedStage.id}:handoff:ship`,
+    scope: completedStage.scope,
+    fromStage: 'execute',
+    toStage: 'ship',
+    fromAgent: 'validator',
+    toAgent: 'ship-manager',
+    status: input.status === 'PASS' ? 'proposed' : 'blocked',
+    outputRefs,
+    requiredInputRefs: [{ kind: 'task', ref: input.taskId }],
+    riskDecisionRef: input.stageRun.decisionRefs[0] ?? { kind: 'task', ref: input.taskId },
+    evidenceRefs: outputRefs,
+    openQuestions: [],
+    blockingGaps: input.status === 'PASS' ? [] : completedStage.blockingReasons,
+    createdAt: input.completedAt,
+    decidedAt: input.completedAt
+  };
+  const validation = validateWorkflowHandoff({ handoff, sourceStageRun: completedStage, lifecycleRiskDecision: input.riskDecision });
+  await recordWorkflowHandoffProjection(projectRoot, validation.valid ? handoff : { ...handoff, status: 'blocked', blockingGaps: validation.issues, decidedAt: input.completedAt });
+}
+
+
+async function ensureVerifyContractForTest(projectRoot: string, branch: string): Promise<{ inspection: VerifyContractInspection; action: VerifyContractAction }> {
+  const inspection = await inspectVerifyContract(projectRoot, { branch, branchSource: 'cli_option' });
+  return { inspection, action: inspection.status === 'PASS' ? 'none' : 'blocked' };
+}
+
+function verifyContractBlocker(inspection: VerifyContractInspection): string {
+  const issueSummary = inspection.issues.map((issue) => `${issue.field}: ${issue.message}`).join(' ');
+  return `verify.md contract is ${inspection.status}; ${issueSummary || 'inspect verify.md before executing tests.'}`;
+}
+
+async function hasReviewerCheckpoint(projectRoot: string, state: RunState, taskId: string): Promise<boolean> {
+  const artifactPaths = new Set(state.artifacts
+    .filter((artifact) => artifact.task === taskId && (artifact.agent === 'reviewer' || artifact.kind === 'review'))
+    .map((artifact) => artifact.path));
+  const branch = state.partition ?? state.gitBranch ?? 'unscoped';
+  const payloads = await listRuntimeArtifactPayloads(projectRoot, { runId: state.runId, taskId });
+  for (const payload of payloads) {
+    const fileName = payload.logicalRef.replace(/\\/g, '/').split('/').filter(Boolean).pop();
+    if (fileName && (payload.artifactRole === 'review' || /review/i.test(fileName))) {
+      artifactPaths.add(toBranchStageEvidenceRef(branch, 'execute', fileName));
+    }
+  }
+
+  for (const artifactPath of artifactPaths) {
+    const report = await validateSddResultArtifact(projectRoot, state.runId, artifactPath, { expectedTask: taskId, expectedAgent: 'reviewer' });
+    if (report.valid && report.result?.status === 'PASS') {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export function renderSddTestResult(result: SddTestResult): string {
+  return [
+    `SDD test ${result.taskId}`,
+    '',
+    resultSentenceForTest(result),
+    '',
+    'Decision:',
+    `- validation_status=${result.validationStatus}`,
+    `- workflow_gate_status=${result.workflowGateStatus}`,
+    `- workflow_gate_decision=${result.workflowGateDecision.decisionId}`,
+    '',
+    'Why:',
+    `- ${result.primaryReason}`,
+    `- capability_evidence=${capabilityEvidenceSummary(result.capabilityEvidence)}`,
+    '',
+    'Next:',
+    `- ${result.next}`
+  ].join('\n');
+}
+
+
+async function runCommandStep(projectRoot: string, runId: string, branch: string, taskId: string, testRunId: string, sequence: number, commandInput: NormalizedSddTestCommand, acceptanceRefs: string[], timeoutMs: number, model: SddTaskModel, task: SddTask, validationScopeTaskIds: string[], validationScopeAcceptanceRefs: string[]): Promise<SddTestCommandStep> {
+  const cachePlan = buildValidationCachePlan({ branch, model, task, command: commandInput.command, argv: commandInput.argv, shell: commandInput.shell, validationScopeTaskIds, acceptanceRefs: validationScopeAcceptanceRefs });
+  const cached = cachePlan.eligible ? await readRuntimeValidationCacheEntry(projectRoot, { branchSlug: branch, cacheKey: cachePlan.cacheKey }) : null;
+  if (cached) {
+    return recordCachedCommandStep(projectRoot, runId, branch, taskId, testRunId, sequence, commandInput, acceptanceRefs, cachePlan.cacheKey, cached);
+  }
+
+  const started = Date.now();
+  const startedAt = new Date(started).toISOString();
+  const executed = await executeCommand(projectRoot, commandInput, timeoutMs);
+  const ended = Date.now();
+  const endedAt = new Date(ended).toISOString();
+  const durationMs = ended - started;
+  const status: SddTestStepStatus = executed.timedOut || executed.error ? 'blocked' : executed.exitCode === 0 ? 'pass' : 'fail';
+  const stepId = `${testRunId}-${String(sequence).padStart(3, '0')}`;
+  const cacheStatus = cachePlan.eligible ? 'miss' : 'unsafe';
+  const shouldPersistOutputArtifact = shouldPersistCommandOutputArtifact(status, executed, cacheStatus, cachePlan.unsafeReasons);
+  const outputFileName = shouldPersistOutputArtifact ? `test-${taskId}-${String(sequence).padStart(3, '0')}.log` : null;
+  const outputRef = outputFileName ? toBranchStageEvidenceRef(branch, 'execute', outputFileName) : null;
+  const output = outputFileName ? renderCommandOutput(commandInput, status, executed, durationMs, cacheStatus, cachePlan.cacheKey, null, cachePlan.unsafeReasons) : null;
+  if (outputFileName && outputRef && output) {
+    await recordRuntimeOnlyArtifact(projectRoot, runId, outputFileName, output, { logicalRef: outputRef, branch, taskId, artifactRole: 'test-command-output' });
+    await appendArtifactHashLedgerEntry(projectRoot, {
+      runId,
+      taskId,
+      branch,
+      artifactPath: outputRef,
+      content: output,
+      status: 'recorded'
+    });
+  }
+  const stdoutDigest = hashDocumentContent(executed.stdout);
+  const stderrDigest = hashDocumentContent(executed.stderr);
+  const outputSummary = summarizeCommandOutput(executed);
+  await appendInvocationLedgerEntry(projectRoot, {
+    runId,
+    taskId,
+    branch,
+    kind: 'command',
+    ref: commandInput.command,
+    status,
+    artifactPath: outputRef,
+    outputHash: output ? hashDocumentContent(output) : null,
+    materialRefs: outputRef ? [outputRef] : [],
+    metadata: {
+      stepId,
+      source: 'sdd-test',
+      exitCode: executed.exitCode,
+      durationMs,
+      stdoutBytes: executed.stdoutBytes,
+      stderrBytes: executed.stderrBytes,
+      truncated: executed.truncated,
+      acceptanceRefs: acceptanceRefs.join(','),
+      shell: commandInput.shell,
+      argv: commandInput.argv ? JSON.stringify(commandInput.argv) : null,
+      stdoutDigest,
+      stderrDigest,
+      cacheKey: cachePlan.cacheKey,
+      cacheStatus,
+      cacheUnsafeReasons: cachePlan.unsafeReasons.join(',')
+    }
+  });
+  const step: SddTestCommandStep = {
+    stepId,
+    command: commandInput.command,
+    argv: commandInput.argv,
+    shell: commandInput.shell,
+    acceptanceRefs,
+    status,
+    exitCode: executed.exitCode,
+    signal: executed.signal,
+    durationMs,
+    outputArtifact: outputRef,
+    stdoutBytes: executed.stdoutBytes,
+    stderrBytes: executed.stderrBytes,
+    truncated: executed.truncated,
+    startedAt,
+    endedAt,
+    cwd: projectRoot,
+    stdoutDigest,
+    stderrDigest,
+    outputSummary,
+    cacheStatus,
+    cacheKey: cachePlan.cacheKey,
+    cacheSourceTestRunId: null,
+    cacheUnsafeReasons: cachePlan.unsafeReasons
+  };
+  await recordRuntimeTestStep(projectRoot, {
+    stepId,
+    testRunId,
+    runId,
+    taskId,
+    command: commandInput.command,
+    status,
+    exitCode: executed.exitCode,
+    durationMs,
+    outputArtifact: outputRef,
+    payload: step
+  });
+  if (status === 'pass' && cachePlan.eligible) {
+    const now = new Date().toISOString();
+    await recordRuntimeValidationCacheEntry(projectRoot, {
+      cacheKey: cachePlan.cacheKey,
+      branchSlug: branch,
+      command: commandInput.command,
+      status: 'valid',
+      sourceTestRunId: testRunId,
+      sourceRunId: runId,
+      sourceEvidenceSetId: null,
+      outputArtifact: outputRef,
+      stdoutDigest,
+      stderrDigest,
+      createdAt: now,
+      lastUsedAt: now,
+      payload: { cachePlan, step }
+    });
+  }
+  return step;
+}
+
+async function recordCachedCommandStep(projectRoot: string, runId: string, branch: string, taskId: string, testRunId: string, sequence: number, commandInput: NormalizedSddTestCommand, acceptanceRefs: string[], cacheKey: string, cached: RuntimeValidationCacheEntryRecord): Promise<SddTestCommandStep> {
+  const now = new Date().toISOString();
+  const stepId = `${testRunId}-${String(sequence).padStart(3, '0')}`;
+  const step: SddTestCommandStep = {
+    stepId,
+    command: commandInput.command,
+    argv: commandInput.argv,
+    shell: commandInput.shell,
+    acceptanceRefs,
+    status: 'pass',
+    exitCode: 0,
+    signal: null,
+    durationMs: 0,
+    outputArtifact: null,
+    stdoutBytes: 0,
+    stderrBytes: 0,
+    truncated: false,
+    startedAt: now,
+    endedAt: now,
+    cwd: projectRoot,
+    stdoutDigest: cached.stdoutDigest,
+    stderrDigest: cached.stderrDigest,
+    outputSummary: `cache_hit source_test_run=${cached.sourceTestRunId} source_artifact=${cached.outputArtifact ?? 'none'}`,
+    cacheStatus: 'hit',
+    cacheKey,
+    cacheSourceTestRunId: cached.sourceTestRunId,
+    cacheUnsafeReasons: []
+  };
+  await appendInvocationLedgerEntry(projectRoot, {
+    runId,
+    taskId,
+    branch,
+    kind: 'command',
+    ref: commandInput.command,
+    status: 'pass',
+    artifactPath: null,
+    outputHash: null,
+    materialRefs: cached.outputArtifact ? [cached.outputArtifact] : [],
+    metadata: { source: 'sdd-test-cache', stepId, cacheKey, sourceTestRunId: cached.sourceTestRunId, sourceEvidenceSetId: cached.sourceEvidenceSetId, acceptanceRefs: acceptanceRefs.join(',') }
+  });
+  await recordRuntimeTestStep(projectRoot, {
+    stepId,
+    testRunId,
+    runId,
+    taskId,
+    command: commandInput.command,
+    status: 'pass',
+    exitCode: 0,
+    durationMs: 0,
+    outputArtifact: null,
+    payload: step
+  });
+  await recordRuntimeValidationCacheUse(projectRoot, {
+    useId: runtimeScopedId(cacheKey, testRunId, taskId, stepId),
+    cacheKey,
+    branchSlug: branch,
+    testRunId,
+    runId,
+    taskId,
+    sourceTestRunId: cached.sourceTestRunId,
+    sourceEvidenceSetId: cached.sourceEvidenceSetId,
+    reusedAt: now,
+    mappedTaskIds: [taskId],
+    reason: 'same validation cache key within compatible branch contract scope',
+    payload: { sourceRunId: cached.sourceRunId, sourceArtifact: cached.outputArtifact }
+  });
+  return step;
+}
+
+function executeCommand(projectRoot: string, commandInput: NormalizedSddTestCommand, timeoutMs: number): Promise<{ exitCode: number | null; signal: string | null; stdout: string; stderr: string; stdoutBytes: number; stderrBytes: number; truncated: boolean; timedOut: boolean; error: string | null }> {
+  return new Promise((resolve) => {
+    const child = commandInput.argv
+      ? spawn(commandInput.argv[0], commandInput.argv.slice(1), { cwd: projectRoot, shell: false, windowsHide: true, env: process.env })
+      : spawn(commandInput.command, { cwd: projectRoot, shell: true, windowsHide: true, env: process.env });
+    let stdout = '';
+    let stderr = '';
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let truncated = false;
+    let settled = false;
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill();
+    }, timeoutMs);
+    const finish = (result: { exitCode: number | null; signal: string | null; error: string | null }) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      resolve({ ...result, stdout, stderr, stdoutBytes, stderrBytes, truncated, timedOut });
+    };
+    child.stdout?.on('data', (chunk: Buffer) => {
+      stdoutBytes += chunk.length;
+      const next = chunk.toString('utf8');
+      if (Buffer.byteLength(stdout, 'utf8') < MAX_CAPTURE_BYTES) {
+        stdout += next;
+      } else {
+        truncated = true;
+      }
+    });
+    child.stderr?.on('data', (chunk: Buffer) => {
+      stderrBytes += chunk.length;
+      const next = chunk.toString('utf8');
+      if (Buffer.byteLength(stderr, 'utf8') < MAX_CAPTURE_BYTES) {
+        stderr += next;
+      } else {
+        truncated = true;
+      }
+    });
+    child.on('error', (error) => finish({ exitCode: null, signal: null, error: error.message }));
+    child.on('close', (code, signal) => finish({ exitCode: code, signal, error: null }));
+  });
+}
+
+async function writeValidationArtifact(projectRoot: string, runId: string, branch: string, task: SddTask, status: SddTestStatus, steps: SddTestCommandStep[], gaps: string[], _capabilityEvidence: CapabilityEvidenceClassification[]): Promise<{ absolutePath: string; runRelativePath: string }> {
+  const artifactPath = validationArtifactPath(task);
+  const stageEvidenceRef = toBranchStageEvidenceRef(branch, 'execute', artifactPath);
+  const resultStatus = status === 'PASS' ? 'PASS' : status === 'FAIL' ? 'FAIL' : 'BLOCKED';
+  const content = `# Test Validation ${task.id}\n\n\`\`\`sdd-result\ncontract: ${SDD_RESULT_CONTRACT}\nversion: ${SDD_RESULT_VERSION}\nagent: validator\ntask: ${task.id}\nstatus: ${resultStatus}\nartifacts:\n  - ${stageEvidenceRef}\n\`\`\`\n\n## Test Runtime\n\n- status: ${status}\n- commands:\n${steps.length > 0 ? steps.map((step) => `  - [${step.status}] ${step.command}`).join('\n') : '  - none'}\n- gaps:\n${gaps.length > 0 ? gaps.map((gap) => `  - ${gap}`).join('\n') : '  - none'}\n\n## Acceptance Evidence\n\n${renderEvidenceBlocks(task, status, stageEvidenceRef, steps)}\n`;
+  const written = await recordStageEvidenceArtifact(projectRoot, runId, stageEvidenceRef, content, { taskId: task.id, artifactRole: 'test-validation' });
+  return { ...written, runRelativePath: stageEvidenceRef };
+}
+
+function validationArtifactPath(task: SddTask): string {
+  return `test-validation-${task.id}.md`;
+}
+
+
+
+async function persistTestRunState(projectRoot: string, state: RunState, taskId: string, validationStatus: SddTestStatus, commands: string[], evidence: string[], validationArtifact: string | null): Promise<void> {
+  const latest = await readRunState(projectRoot, state.runId);
+  const knownArtifacts = new Set(latest.artifacts.map((artifact) => artifact.path));
+  const now = new Date().toISOString();
+  const nextArtifacts = evidence
+    .filter((artifactPath) => !knownArtifacts.has(artifactPath))
+    .map((artifactPath) => ({ path: artifactPath, kind: testArtifactKind(artifactPath), task: taskId, agent: 'test-runtime', createdAt: now }));
+  const existingTaskState = latest.tasks[taskId];
+  await writeRunState(projectRoot, {
+    ...latest,
+    status: validationStatus === 'PASS' ? 'running' : validationStatus === 'FAIL' ? 'failed' : 'blocked',
+    phase: 'test',
+    currentTask: taskId,
+    tasks: {
+      ...latest.tasks,
+      [taskId]: {
+        ...baseRuntimeTaskState(existingTaskState),
+        status: validationStatus === 'PASS' ? 'validation_passed_pending_gate' : validationStatus === 'FAIL' ? 'validation_failed' : 'validation_blocked',
+        implementationStatus: existingTaskState?.implementationStatus ?? 'not_started',
+        verificationStatus: verificationStatusFromTest(validationStatus),
+        testStatus: validationStatus,
+        evidence
+      }
+    },
+    artifacts: [...latest.artifacts, ...nextArtifacts],
+    validation: {
+      status: validationStatus === 'PASS' ? 'pass' : validationStatus === 'FAIL' ? 'fail' : 'blocked',
+      commands,
+      evidence
+    }
+  });
+}
+
+async function persistTestGateOutcome(projectRoot: string, runId: string, taskId: string, status: SddTestStatus, validationStatus: SddTestStatus, commands: string[], evidence: string[], validationArtifact: string | null, gateDecision: WorkflowGateDecision): Promise<void> {
+  const latest = await readRunState(projectRoot, runId);
+  const knownArtifacts = new Set(latest.artifacts.map((artifact) => artifact.path));
+  const now = new Date().toISOString();
+  const nextArtifacts = evidence
+    .filter((artifactPath) => !knownArtifacts.has(artifactPath))
+    .map((artifactPath) => ({ path: artifactPath, kind: testArtifactKind(artifactPath), task: taskId, agent: 'test-runtime', createdAt: now }));
+  const existingTaskState = latest.tasks[taskId];
+  await writeRunState(projectRoot, {
+    ...latest,
+    status: status === 'PASS' ? 'completed' : status === 'FAIL' ? 'failed' : 'blocked',
+    phase: 'test',
+    currentTask: taskId,
+    tasks: {
+      ...latest.tasks,
+      [taskId]: {
+        ...baseRuntimeTaskState(existingTaskState),
+        status: runtimeTaskStatusAfterGate(status, validationStatus),
+        implementationStatus: existingTaskState?.implementationStatus ?? 'not_started',
+        verificationStatus: verificationStatusFromTest(validationStatus),
+        testStatus: status,
+        validationStatus,
+        workflowGateStatus: gateDecision.status,
+        workflowGateDecisionId: gateDecision.decisionId,
+        evidence
+      }
+    },
+    artifacts: [...latest.artifacts, ...nextArtifacts],
+    validation: {
+      status: validationStatus === 'PASS' ? 'pass' : validationStatus === 'FAIL' ? 'fail' : 'blocked',
+      commands,
+      evidence
+    }
+  });
+}
+
+function testArtifactKind(artifactPath: string): string {
+  const fileName = artifactPath.split('/').pop() ?? artifactPath;
+  if (fileName.startsWith('test-validation-')) {
+    return 'test-validation';
+  }
+  return 'test';
+}
+
+function baseRuntimeTaskState(existing: RunStateTaskRuntime | undefined): RunStateTaskRuntime {
+  return {
+    status: existing?.status ?? 'not_started',
+    implementationStatus: existing?.implementationStatus ?? 'not_started',
+    verificationStatus: existing?.verificationStatus ?? 'not_run',
+    validationBatch: existing?.validationBatch ?? null,
+    validationTiming: existing?.validationTiming ?? 'task_end',
+    requiresVerifyBeforeNext: existing?.requiresVerifyBeforeNext ?? true,
+    gaps: existing?.gaps,
+    artifacts: existing?.artifacts,
+    testStatus: existing?.testStatus,
+    workflowGateStatus: existing?.workflowGateStatus,
+    workflowGateDecisionId: existing?.workflowGateDecisionId,
+    evidence: existing?.evidence
+  };
+}
+
+function verificationStatusFromTest(validationStatus: SddTestStatus): RunStateTaskRuntime['verificationStatus'] {
+  if (validationStatus === 'PASS') {
+    return 'pass';
+  }
+  return validationStatus === 'FAIL' ? 'failed' : 'blocked';
+}
+
+function runtimeTaskStatusAfterGate(status: SddTestStatus, validationStatus: SddTestStatus): string {
+  if (status === 'PASS') {
+    return 'implemented_verified';
+  }
+  if (validationStatus === 'PASS') {
+    return 'workflow_gate_blocked';
+  }
+  return validationStatus === 'FAIL' ? 'validation_failed' : 'validation_blocked';
+}
+
+function deriveCommandStatus(gaps: string[], steps: SddTestCommandStep[]): TestEvidenceStatus {
+  if (gaps.length > 0 || steps.some((step) => step.status === 'blocked')) {
+    return 'BLOCKED';
+  }
+  if (steps.some((step) => step.status === 'fail')) {
+    return 'FAIL';
+  }
+  return 'PASS';
+}
+
+function buildAcceptanceCoverage(task: SddTask | null, steps: SddTestCommandStep[], commandStatus: TestEvidenceStatus, acceptanceRefsOverride: string[] | undefined): AcceptanceEvidenceCoverage[] {
+  const acceptanceRefs = acceptanceRefsOverride && acceptanceRefsOverride.length > 0 ? [...new Set(acceptanceRefsOverride)] : task ? taskAcceptanceRefs(task) : [];
+  return acceptanceRefs.map((acceptanceRef) => {
+    const mappedSteps = steps.filter((step) => step.acceptanceRefs.includes(acceptanceRef));
+    const hasPassingEvidence = mappedSteps.some((step) => step.status === 'pass');
+    const hasFailingEvidence = mappedSteps.some((step) => step.status === 'fail' || step.status === 'blocked');
+    const status: EvidenceCoverageStatus = hasPassingEvidence && !hasFailingEvidence && commandStatus === 'PASS'
+      ? 'complete'
+      : mappedSteps.length > 0
+        ? 'partial'
+        : 'missing';
+    return {
+      acceptanceRef,
+      status,
+      evidenceRefs: mappedSteps.map(commandStepRuntimeRef),
+      gaps: status === 'complete' ? [] : [`Acceptance ${acceptanceRef} has no complete non-stale execute validation evidence.`]
+    };
+  });
+}
+
+function runtimeEvidenceRefs(validationArtifact: string | null, steps: SddTestCommandStep[]): string[] {
+  return [validationArtifact, ...steps.map((step) => step.outputArtifact)].filter((item): item is string => Boolean(item));
+}
+
+function commandStepRuntimeRef(step: SddTestCommandStep): { kind: 'command'; ref: string } {
+  return { kind: 'command', ref: step.stepId };
+}
+
+function artifactRuntimeRefs(ref: string | null): Array<{ kind: 'artifact'; ref: string }> {
+  return ref ? [{ kind: 'artifact', ref }] : [];
+}
+
+function summarizeEvidenceCoverage(acceptanceCoverage: AcceptanceEvidenceCoverage[]): EvidenceCoverageStatus {
+  if (acceptanceCoverage.length === 0) {
+    return 'missing';
+  }
+  if (acceptanceCoverage.every((coverage) => coverage.status === 'complete')) {
+    return 'complete';
+  }
+  if (acceptanceCoverage.some((coverage) => coverage.status === 'complete' || coverage.status === 'partial')) {
+    return 'partial';
+  }
+  return 'missing';
+}
+
+function derivePolicyJudgment(commandStatus: TestEvidenceStatus, evidenceCoverage: EvidenceCoverageStatus): SddTestStatus {
+  if (commandStatus === 'FAIL') {
+    return 'FAIL';
+  }
+  if (commandStatus === 'BLOCKED' || evidenceCoverage !== 'complete') {
+    return 'BLOCKED';
+  }
+  return 'PASS';
+}
+
+async function resolveTestRuntimeDurableGap(
+  projectRoot: string,
+  branch: string,
+  runId: string,
+  taskId: string,
+  validationStatus: SddTestStatus,
+  gaps: string[]
+): Promise<void> {
+  if (validationStatus !== 'PASS' || gaps.length > 0) {
+    return;
+  }
+  await updateRuntimeDurableGapStatus(projectRoot, {
+    gapId: testRuntimeGapId(branch, runId, taskId),
+    status: 'resolved',
+    source: 'gate_policy',
+    payload: { validationStatus, gaps }
+  });
+}
+
+async function recordTestRuntimeDurableGap(
+  projectRoot: string,
+  branch: string,
+  runId: string,
+  taskId: string,
+  status: SddTestStatus,
+  validationStatus: SddTestStatus,
+  runtimeJudgment: WorkflowGateStatus,
+  gaps: string[],
+  evidenceRefs: string[]
+): Promise<void> {
+  if (status === 'PASS' && gaps.length === 0) {
+    return;
+  }
+  const message = gaps[0] ?? (runtimeJudgment === 'PASS' ? `Validation status is ${validationStatus}.` : `Workflow gate status is ${runtimeJudgment}.`);
+  await recordRuntimeDurableGap(projectRoot, {
+    gapId: testRuntimeGapId(branch, runId, taskId),
+    partition: branch,
+    taskId,
+    runId,
+    stage: 'execute',
+    gate: 'execute',
+    source: 'runtime',
+    category: runtimeJudgment === 'PASS' ? 'validation' : 'workflow_gate',
+    severity: 'blocking',
+    status: 'open',
+    message,
+    recommendation: `Resolve execute runtime gaps for ${taskId}, then rerun ${testValidationUnitCommand(branch)}.`,
+    evidenceRefs,
+    proposalRefs: [],
+    sourceRefs: [],
+    payload: { status, validationStatus, runtimeJudgment, gaps }
+  });
+}
+
+function testRuntimeGapId(branch: string, _runId: string, taskId: string): string {
+  return runtimeScopedId(branch, taskId, 'test-runtime-gap');
+}
+
+function finalStatusForTest(validationStatus: SddTestStatus, runtimeJudgment: WorkflowGateStatus): SddTestStatus {
+  if (validationStatus !== 'PASS') {
+    return validationStatus;
+  }
+  return runtimeJudgment === 'PASS' || runtimeJudgment === 'WARN' ? 'PASS' : 'BLOCKED';
+}
+
+function buildUnifiedTestEvidenceRun(id: string, branch: string, runId: string, taskId: string, commandStatus: TestEvidenceStatus, evidenceCoverage: EvidenceCoverageStatus, policyJudgment: TestEvidenceStatus, status: SddTestStatus, runtimeJudgment: WorkflowGateStatus, steps: SddTestCommandStep[], acceptanceCoverage: AcceptanceEvidenceCoverage[], capabilityEvidence: CapabilityEvidenceClassification[], gaps: string[], gateNextAction: string | null, gateDecision: WorkflowGateDecision | null): UnifiedTestEvidenceRun {
+  return {
+    contract: TEST_EVIDENCE_RUN_CONTRACT_VERSION,
+    id,
+    scope: { branch, taskId, runId },
+    commandStatus,
+    evidenceCoverage,
+    policyJudgment,
+    commands: steps.map((step) => ({
+      command: step.command,
+      status: step.status === 'pass' ? 'PASS' : step.status === 'fail' ? 'FAIL' : 'BLOCKED',
+      outputRef: step.outputArtifact ? { kind: 'artifact', ref: step.outputArtifact } : undefined,
+      evidenceRefs: [commandStepRuntimeRef(step), ...artifactRuntimeRefs(step.outputArtifact)],
+      acceptanceRefs: step.acceptanceRefs,
+      startedAt: new Date(Date.now() - step.durationMs).toISOString(),
+      completedAt: new Date().toISOString()
+    })),
+    acceptanceCoverage,
+    capabilityEvidence,
+    gaps: [...gaps, ...acceptanceCoverage.flatMap((coverage) => coverage.gaps)],
+    next: nextForTestResult(status, runtimeJudgment, branch, taskId, gateNextAction, gateDecision),
+    generatedAt: new Date().toISOString()
+  };
+}
+
+function buildCapabilityEvidenceClassification(decision: AgentCapabilityRouteDecision | null, steps: SddTestCommandStep[]): CapabilityEvidenceClassification[] {
+  if (!decision) {
+    return [{
+      class: 'diagnostic',
+      source: 'runtime_diagnostic',
+      domainOrSourceId: 'capability-routing',
+      evidenceRefs: [],
+      acceptanceRefs: [],
+      provenanceRefs: [],
+      reason: 'Capability routing did not run; no capability output is accepted as test evidence.'
+    }];
+  }
+  const acceptanceRefs = [...new Set(steps.flatMap((step) => step.acceptanceRefs))];
+  const professionalEvidence = decision.selectedDomains.map((domain) => ({
+    class: 'candidate' as const,
+    source: 'professional_capability' as const,
+    domainOrSourceId: domain.domain,
+    evidenceRefs: [],
+    acceptanceRefs,
+    provenanceRefs: [{ kind: 'projection' as const, ref: `capability:${domain.capabilityId}` }],
+    reason: `${domain.reason}; capability output is advisory candidate evidence until accepted by command evidence and policy refs.`
+  }));
+  const externalEvidence = decision.rejectedExternalSources.map((source) => ({
+    class: capabilityClassForRejectedSource(source.quarantineStatus) as CapabilityEvidenceClassification['class'],
+    source: 'external_source' as const,
+    domainOrSourceId: source.sourceId,
+    evidenceRefs: [],
+    acceptanceRefs: [],
+    provenanceRefs: [{ kind: 'external' as const, ref: source.sourceId }],
+    reason: source.reason
+  }));
+  return [...professionalEvidence, ...externalEvidence];
+}
+
+function capabilityClassForRejectedSource(status: AgentCapabilityRouteDecision['rejectedExternalSources'][number]['quarantineStatus']): CapabilityEvidenceClassification['class'] {
+  if (status === 'denied') {
+    return 'blocked';
+  }
+  if (status === 'required' || status === 'quarantined') {
+    return 'quarantined';
+  }
+  return 'diagnostic';
+}
+
+
+function capabilityEvidenceSummary(items: CapabilityEvidenceClassification[]): string {
+  if (items.length === 0) {
+    return 'none';
+  }
+  const counts = new Map<CapabilityEvidenceClassification['class'], number>();
+  for (const item of items) {
+    counts.set(item.class, (counts.get(item.class) ?? 0) + 1);
+  }
+  return [...counts.entries()].map(([kind, count]) => `${kind}:${count}`).join(',');
+}
+
+function nextForTestResult(status: SddTestStatus, runtimeJudgment: WorkflowGateStatus, branch: string, taskId: string, gateNextAction: string | null, gateDecision: WorkflowGateDecision | null): string {
+  const inspectHint = `Inspect runtime test read model for ${taskId}`;
+  if (status === 'PASS') {
+    return `sdd execute close --branch ${branch} --compact-json`;
+  }
+  if (gateNextAction) {
+    return gateNextAction;
+  }
+  if (runtimeJudgment === 'HUMAN_REQUIRED') {
+    return gateDecision ? `Create a decision card for workflow gate ${gateDecision.decisionId}, then rerun ${testValidationUnitCommand(branch)}.` : `Create a decision card, then rerun ${testValidationUnitCommand(branch)}.`;
+  }
+  if (runtimeJudgment === 'WARN') {
+    return gateDecision ? `Review workflow gate ${gateDecision.decisionId} warnings, then rerun ${testValidationUnitCommand(branch)} or proceed only with explicit review.` : `Review workflow gate warnings, then rerun ${testValidationUnitCommand(branch)}.`;
+  }
+  if (runtimeJudgment === 'ADVISORY_ONLY') {
+    return `Inspect advisor assessments for ${taskId}; advisory output cannot satisfy the test gate.`;
+  }
+  if (status === 'FAIL') {
+    return `${inspectHint}, fix failing validation commands, then rerun ${testValidationUnitCommand(branch)}.`;
+  }
+  return gateDecision ? `${inspectHint} and workflow gate ${gateDecision.decisionId}, resolve blockers, then rerun ${testValidationUnitCommand(branch)}.` : `${inspectHint}, fix command/evidence gaps, then rerun ${testValidationUnitCommand(branch)}.`;
+}
+
+
+function testValidationUnitCommand(branch: string): string {
+  return `sdd execute --branch ${branch} --json`;
+}
+
+function resultSentenceForTest(result: SddTestResult): string {
+  if (result.status === 'PASS') {
+    return 'Validation and workflow gate passed; proceed to execute evidence judgment and truthAlignment before release readiness.';
+  }
+  if (result.validationStatus === 'PASS' && result.workflowGateStatus !== 'PASS') {
+    return `Validation passed, but workflow gate returned ${result.workflowGateStatus}.`;
+  }
+  if (result.commandStatus === 'BLOCKED') {
+    return 'Blocked before validation commands ran.';
+  }
+  return result.status === 'FAIL' ? 'Validation failed.' : 'Validation did not produce complete evidence.';
+}
+
+function renderEvidenceBlocks(task: SddTask, status: SddTestStatus, sourceArtifact: string, steps: SddTestCommandStep[]): string {
+  const acceptances = task.acceptanceRefs.length > 0 ? task.acceptanceRefs : task.acceptance;
+  if (acceptances.length === 0) {
+    return 'No acceptance targets declared.';
+  }
+  const mappedEvidence = acceptances
+    .map((acceptance) => ({ acceptance, steps: steps.filter((step) => step.acceptanceRefs.includes(acceptance)) }))
+    .filter((item) => item.steps.length > 0);
+  if (mappedEvidence.length === 0) {
+    return 'No acceptance evidence emitted; validation commands are not explicitly mapped to acceptance refs.';
+  }
+  return mappedEvidence.map(({ acceptance, steps: mappedSteps }) => {
+    const evidenceStatus = evidenceStatusForMappedSteps(status, mappedSteps);
+    return `\`\`\`sdd-evidence\ncontract: ${SDD_EVIDENCE_CONTRACT}\nversion: ${SDD_EVIDENCE_VERSION}\ntask: ${task.id}\nacceptance: ${acceptance}\nstatus: ${evidenceStatus}\nclaim: Explicit validation mapping ${mappedSteps.map((step) => step.command).join(' && ')} produced ${evidenceStatus} for ${acceptance}.\nsource_artifact: ${sourceArtifact}\nevidence_refs:\n${mappedSteps.map(renderStepEvidenceRefs).join('\n')}\nprovenance_refs:\n  - artifact:${sourceArtifact}\n${mappedSteps.map((step) => `  - command:${step.command}`).join('\n')}\npolicy_refs:\n  - ${ACCEPTANCE_POLICY_RULESET_VERSION}:require-source-evidence\n  - ${ACCEPTANCE_POLICY_RULESET_VERSION}:require-provenance\n  - ${ACCEPTANCE_POLICY_RULESET_VERSION}:require-policy-rule\n\`\`\``;
+  }).join('\n\n');
+}
+
+function normalizeTestCommandInputs(commandInputs: SddTestCommandInput[] | undefined, commands: string[] | undefined, taskValidation: string[]): NormalizedSddTestCommand[] {
+  if (commandInputs && commandInputs.length > 0) {
+    return commandInputs.map(normalizeTestCommandInput);
+  }
+  return (commands && commands.length > 0 ? commands : taskValidation).map((command) => ({ command, argv: null, shell: true }));
+}
+
+function normalizeTestCommandInput(input: SddTestCommandInput): NormalizedSddTestCommand {
+  if (input.argv) {
+    const argv = input.argv.filter((item) => item.length > 0);
+    if (argv.length === 0) {
+      throw new Error('Command argv input must include an executable.');
+    }
+    return { command: argv.join(' '), argv, shell: false };
+  }
+  if (input.command) {
+    return { command: input.command, argv: null, shell: true };
+  }
+  throw new Error('Command input must include command or argv.');
+}
+
+function acceptanceRefsForCommand(task: SddTask | null, command: string, acceptanceRefsOverride: string[] | undefined): string[] {
+  if (acceptanceRefsOverride && acceptanceRefsOverride.length > 0) {
+    return [...new Set(acceptanceRefsOverride)];
+  }
+  return [...new Set((task?.validationCommands ?? [])
+    .filter((entry) => entry.command === command)
+    .flatMap((entry) => entry.acceptanceRefs))];
+}
+
+function taskAcceptanceRefs(task: SddTask): string[] {
+  const refs = task.acceptanceRefs.length > 0 ? task.acceptanceRefs : task.acceptance;
+  return [...new Set(refs)];
+}
+
+function evidenceStatusForMappedSteps(status: SddTestStatus, steps: SddTestCommandStep[]): SddTestStatus {
+  if (steps.some((step) => step.status === 'fail')) {
+    return 'FAIL';
+  }
+  if (status === 'BLOCKED' || steps.some((step) => step.status === 'blocked')) {
+    return 'BLOCKED';
+  }
+  return 'PASS';
+}
+
+function renderCommandOutput(commandInput: NormalizedSddTestCommand, status: SddTestStepStatus, executed: { exitCode: number | null; signal: string | null; stdout: string; stderr: string; truncated: boolean; timedOut: boolean; error: string | null }, durationMs: number, cacheStatus: 'hit' | 'miss' | 'unsafe' = 'unsafe', cacheKey: string | null = null, cacheSourceTestRunId: string | null = null, cacheUnsafeReasons: ValidationCacheUnsafeReason[] = []): string {
+  return `# Test Command Output\n\n- command: ${commandInput.command}\n- shell: ${commandInput.shell}\n- argv: ${commandInput.argv ? JSON.stringify(commandInput.argv) : 'none'}\n- status: ${status}\n- exit_code: ${executed.exitCode ?? 'none'}\n- signal: ${executed.signal ?? 'none'}\n- duration_ms: ${durationMs}\n- timed_out: ${executed.timedOut}\n- truncated: ${executed.truncated}\n- error: ${executed.error ?? 'none'}\n- cache_status: ${cacheStatus}\n- cache_key: ${cacheKey ?? 'none'}\n- cache_source_test_run: ${cacheSourceTestRunId ?? 'none'}\n- cache_unsafe_reasons: ${cacheUnsafeReasons.join(',') || 'none'}\n\n## stdout\n\n\`\`\`text\n${executed.stdout}\n\`\`\`\n\n## stderr\n\n\`\`\`text\n${executed.stderr}\n\`\`\`\n`;
+}
+
+function shouldPersistCommandOutputArtifact(status: SddTestStepStatus, executed: { truncated: boolean; timedOut: boolean; error: string | null }, cacheStatus: 'hit' | 'miss' | 'unsafe', cacheUnsafeReasons: ValidationCacheUnsafeReason[]): boolean {
+  return status !== 'pass' || executed.truncated || executed.timedOut || Boolean(executed.error) || cacheStatus === 'unsafe' || cacheUnsafeReasons.length > 0;
+}
+
+function renderStepEvidenceRefs(step: SddTestCommandStep): string {
+  const refs = [`  - command:${step.stepId}`];
+  if (step.outputArtifact) {
+    refs.push(`  - artifact:${step.outputArtifact}`);
+  }
+  return refs.join('\n');
+}
+
+
+function summarizeCommandOutput(executed: { exitCode: number | null; signal: string | null; stdout: string; stderr: string; stdoutBytes: number; stderrBytes: number; truncated: boolean; timedOut: boolean; error: string | null }): string {
+  const parts = [
+    `exit=${executed.exitCode ?? 'none'}`,
+    `signal=${executed.signal ?? 'none'}`,
+    `stdout_bytes=${executed.stdoutBytes}`,
+    `stderr_bytes=${executed.stderrBytes}`,
+    `truncated=${executed.truncated}`,
+    `timed_out=${executed.timedOut}`
+  ];
+  if (executed.error) {
+    parts.push(`error=${executed.error}`);
+  }
+  return parts.join(' ');
+}
+
+
+function hashDocumentContent(raw: string): string {
+  return createHash('sha256').update(raw.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+}