sdd-agent-platform 0.4.1 → 0.4.2

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

@@ -1,15 +1,16 @@
 import { createHash } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { appendEvent } from '../run-state/events.js';
-import { appendInvocationLedgerEntry } from '../run-state/invocation-ledger.js';
+import { appendArtifactHashLedgerEntry, appendInvocationLedgerEntry } from '../run-state/invocation-ledger.js';
 import type { RunState, RunStateTaskRuntime } from '../run-state/model.js';
-import { createRun, readRunState, writeRunState } from '../run-state/run-state.js';
-import { writeArtifact } from '../run-state/artifacts.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 } from '../sdd-docs/task-parser.js';
+import { parseSddBranch, type SddTask, type SddTaskModel } from '../sdd-docs/task-parser.js';
 import { inspectSddTask } from '../sdd-docs/task-inspection.js';
-import { recordRuntimeAcceptanceEvidenceMap, recordRuntimeDurableGap, recordRuntimeProjection, recordRuntimeTestRun, recordRuntimeTestStep, recordRuntimeValidationEnvironmentSession, recordRuntimeValidationWaveRun, runtimeScopedId, updateRuntimeDurableGapStatus } from '../storage/runtime-store.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';
@@ -20,10 +21,13 @@ 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;
@@ -46,10 +50,20 @@ export interface SddTestCommandStep {
   exitCode: number | null;
   signal: string | null;
   durationMs: number;
-  outputArtifact: string;
+  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 {
@@ -87,7 +101,6 @@ export interface SddTestResult {
   policyJudgment: TestEvidenceStatus;
   acceptanceCoverage: AcceptanceEvidenceCoverage[];
   capabilityEvidence: CapabilityEvidenceClassification[];
-  syncBackReady: boolean;
   commands: string[];
   steps: SddTestCommandStep[];
   validationArtifact: string | null;
@@ -126,6 +139,7 @@ export async function runSddTest(projectRoot: string, options: RunSddTestOptions
   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,
@@ -158,12 +172,16 @@ export async function runSddTest(projectRoot: string, options: RunSddTestOptions
     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));
+    gaps.push(...dependencyBlockingReasonsForTask(model, options.taskId, { runtimeByTask }));
   }
   if (verifyContract.action === 'blocked') {
     gaps.push(verifyContractBlocker(verifyInspection));
@@ -212,7 +230,7 @@ export async function runSddTest(projectRoot: string, options: RunSddTestOptions
   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);
+      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',
@@ -229,12 +247,11 @@ export async function runSddTest(projectRoot: string, options: RunSddTestOptions
   const policyJudgment = derivePolicyJudgment(commandStatus, evidenceCoverage);
   await recordAcceptanceEvidenceMaps(projectRoot, validationWaveRunId, testRunId, context.partition, state.runId, options.taskId, acceptanceCoverage);
   const validationStatus = policyJudgment;
-  const syncBackReady = false;
   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, task, validationStatus, steps, gaps, capabilityEvidence) : null;
-  const evidenceBeforeIndex = [validationArtifact?.runRelativePath, ...steps.map((step) => step.outputArtifact)].filter((item): item is string => Boolean(item));
-  await persistTestRunState(projectRoot, state, options.taskId, validationStatus, commands, evidenceBeforeIndex, validationArtifact?.runRelativePath ?? null);
+  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, {
@@ -245,39 +262,10 @@ export async function runSddTest(projectRoot: string, options: RunSddTestOptions
   })).decision;
   const runtimeJudgment = gateDecision.status;
   const status = finalStatusForTest(validationStatus, runtimeJudgment);
-  await recordTestRuntimeDurableGap(projectRoot, context.partition, state.runId, options.taskId, status, validationStatus, runtimeJudgment, gaps, evidenceBeforeIndex);
-  const unifiedEvidence = buildUnifiedTestEvidenceRun(testRunId, context.partition, state.runId, options.taskId, commandStatus, evidenceCoverage, policyJudgment, status, runtimeJudgment, steps, acceptanceCoverage, capabilityEvidence, syncBackReady, gaps, workflowGate.nextAction, gateDecision);
-  const indexArtifact = await writeIndexArtifact(projectRoot, 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,
-    syncBackReady,
-    commands,
-    steps,
-    validationArtifact: validationArtifact?.runRelativePath ?? null,
-    gaps
-  });
+  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 = [validationArtifact?.runRelativePath, indexArtifact.runRelativePath, ...steps.map((step) => step.outputArtifact)].filter((item): item is string => Boolean(item));
+  const evidence = runtimeEvidenceRefs(validationArtifact?.runRelativePath ?? null, steps);
 
   await recordRuntimeTestRun(projectRoot, {
     testRunId,
@@ -287,7 +275,7 @@ export async function runSddTest(projectRoot: string, options: RunSddTestOptions
     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, syncBackReady, commands, commandInputs, evidence, gaps }
+    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',
@@ -371,13 +359,12 @@ export async function runSddTest(projectRoot: string, options: RunSddTestOptions
     policyJudgment,
     acceptanceCoverage,
     capabilityEvidence,
-    syncBackReady,
     commands,
     steps,
     validationArtifact: validationArtifact?.runRelativePath ?? null,
-    indexArtifact: indexArtifact.runRelativePath,
+    indexArtifact: null,
     gaps,
-    next: nextForTestResult(status, runtimeJudgment, context.partition, options.taskId, state.runId, indexArtifact.runRelativePath, workflowGate.nextAction, gateDecision)
+    next: nextForTestResult(status, runtimeJudgment, context.partition, options.taskId, workflowGate.nextAction, gateDecision)
   };
 }
 
@@ -446,12 +433,17 @@ function verifyContractBlocker(inspection: VerifyContractInspection): string {
 }
 
 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),
-    `artifacts/review-${taskId}.md`
-  ]);
+  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' });
@@ -484,14 +476,40 @@ export function renderSddTestResult(result: SddTestResult): string {
 }
 
 
-async function runCommandStep(projectRoot: string, runId: string, branch: string, taskId: string, testRunId: string, sequence: number, commandInput: NormalizedSddTestCommand, acceptanceRefs: string[], timeoutMs: number): Promise<SddTestCommandStep> {
+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 durationMs = Date.now() - started;
+  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 output = renderCommandOutput(commandInput, status, executed, durationMs);
-  const outputArtifact = await writeArtifact(projectRoot, runId, `test-${taskId}-${String(sequence).padStart(3, '0')}.log`, output);
+  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,
@@ -499,10 +517,11 @@ async function runCommandStep(projectRoot: string, runId: string, branch: string
     kind: 'command',
     ref: commandInput.command,
     status,
-    artifactPath: outputArtifact.runRelativePath,
-    outputHash: hashDocumentContent(output),
-    materialRefs: [outputArtifact.runRelativePath],
+    artifactPath: outputRef,
+    outputHash: output ? hashDocumentContent(output) : null,
+    materialRefs: outputRef ? [outputRef] : [],
     metadata: {
+      stepId,
       source: 'sdd-test',
       exitCode: executed.exitCode,
       durationMs,
@@ -511,7 +530,12 @@ async function runCommandStep(projectRoot: string, runId: string, branch: string
       truncated: executed.truncated,
       acceptanceRefs: acceptanceRefs.join(','),
       shell: commandInput.shell,
-      argv: commandInput.argv ? JSON.stringify(commandInput.argv) : null
+      argv: commandInput.argv ? JSON.stringify(commandInput.argv) : null,
+      stdoutDigest,
+      stderrDigest,
+      cacheKey: cachePlan.cacheKey,
+      cacheStatus,
+      cacheUnsafeReasons: cachePlan.unsafeReasons.join(',')
     }
   });
   const step: SddTestCommandStep = {
@@ -524,10 +548,20 @@ async function runCommandStep(projectRoot: string, runId: string, branch: string
     exitCode: executed.exitCode,
     signal: executed.signal,
     durationMs,
-    outputArtifact: outputArtifact.runRelativePath,
+    outputArtifact: outputRef,
     stdoutBytes: executed.stdoutBytes,
     stderrBytes: executed.stderrBytes,
-    truncated: executed.truncated
+    truncated: executed.truncated,
+    startedAt,
+    endedAt,
+    cwd: projectRoot,
+    stdoutDigest,
+    stderrDigest,
+    outputSummary,
+    cacheStatus,
+    cacheKey: cachePlan.cacheKey,
+    cacheSourceTestRunId: null,
+    cacheUnsafeReasons: cachePlan.unsafeReasons
   };
   await recordRuntimeTestStep(projectRoot, {
     stepId,
@@ -538,9 +572,96 @@ async function runCommandStep(projectRoot: string, runId: string, branch: string
     status,
     exitCode: executed.exitCode,
     durationMs,
-    outputArtifact: outputArtifact.runRelativePath,
+    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;
 }
 
@@ -591,19 +712,21 @@ function executeCommand(projectRoot: string, commandInput: NormalizedSddTestComm
   });
 }
 
-async function writeValidationArtifact(projectRoot: string, runId: string, task: SddTask, status: SddTestStatus, steps: SddTestCommandStep[], gaps: string[], capabilityEvidence: CapabilityEvidenceClassification[]): Promise<{ absolutePath: string; runRelativePath: string }> {
-  const artifactPath = `test-validation-${task.id}.md`;
-  const runRelativePath = `artifacts/${artifactPath}`;
+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  - ${runRelativePath}\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## Capability Evidence Classification\n\n${renderCapabilityEvidenceClassification(capabilityEvidence)}\n\n## Acceptance Evidence\n\n${renderEvidenceBlocks(task, status, runRelativePath, steps)}\n`;
-  return writeArtifact(projectRoot, runId, artifactPath, content);
+  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 };
 }
 
-
-async function writeIndexArtifact(projectRoot: string, runId: string, payload: Omit<SddTestResult, 'contract' | 'runId' | 'indexArtifact' | 'next'>): Promise<{ absolutePath: string; runRelativePath: string }> {
-  return writeArtifact(projectRoot, runId, `test-index-${payload.taskId}.json`, `${JSON.stringify({ contract: 'sdd-test-runtime-v1', runId, ...payload }, null, 2)}\n`);
+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));
@@ -622,7 +745,7 @@ async function persistTestRunState(projectRoot: string, state: RunState, taskId:
       [taskId]: {
         ...baseRuntimeTaskState(existingTaskState),
         status: validationStatus === 'PASS' ? 'validation_passed_pending_gate' : validationStatus === 'FAIL' ? 'validation_failed' : 'validation_blocked',
-        implementationStatus: existingTaskState?.implementationStatus ?? 'implemented',
+        implementationStatus: existingTaskState?.implementationStatus ?? 'not_started',
         verificationStatus: verificationStatusFromTest(validationStatus),
         testStatus: validationStatus,
         evidence
@@ -633,8 +756,7 @@ async function persistTestRunState(projectRoot: string, state: RunState, taskId:
       status: validationStatus === 'PASS' ? 'pass' : validationStatus === 'FAIL' ? 'fail' : 'blocked',
       commands,
       evidence
-    },
-    syncBack: latest.syncBack
+    }
   });
 }
 
@@ -656,7 +778,7 @@ async function persistTestGateOutcome(projectRoot: string, runId: string, taskId
       [taskId]: {
         ...baseRuntimeTaskState(existingTaskState),
         status: runtimeTaskStatusAfterGate(status, validationStatus),
-        implementationStatus: existingTaskState?.implementationStatus ?? 'implemented',
+        implementationStatus: existingTaskState?.implementationStatus ?? 'not_started',
         verificationStatus: verificationStatusFromTest(validationStatus),
         testStatus: status,
         validationStatus,
@@ -670,8 +792,7 @@ async function persistTestGateOutcome(projectRoot: string, runId: string, taskId
       status: validationStatus === 'PASS' ? 'pass' : validationStatus === 'FAIL' ? 'fail' : 'blocked',
       commands,
       evidence
-    },
-    syncBack: latest.syncBack
+    }
   });
 }
 
@@ -680,9 +801,6 @@ function testArtifactKind(artifactPath: string): string {
   if (fileName.startsWith('test-validation-')) {
     return 'test-validation';
   }
-  if (fileName.startsWith('test-index-')) {
-    return 'test-index';
-  }
   return 'test';
 }
 
@@ -744,12 +862,24 @@ function buildAcceptanceCoverage(task: SddTask | null, steps: SddTestCommandStep
     return {
       acceptanceRef,
       status,
-      evidenceRefs: mappedSteps.map((step) => ({ kind: 'artifact', ref: step.outputArtifact })),
+      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';
@@ -819,7 +949,7 @@ async function recordTestRuntimeDurableGap(
     severity: 'blocking',
     status: 'open',
     message,
-    recommendation: `Resolve test runtime gaps for ${taskId}, then rerun sdd test task ${taskId} --branch ${branch}.`,
+    recommendation: `Resolve test runtime gaps for ${taskId}, then rerun ${testValidationUnitCommand(branch, taskId)}.`,
     evidenceRefs,
     proposalRefs: [],
     sourceRefs: [],
@@ -835,10 +965,10 @@ function finalStatusForTest(validationStatus: SddTestStatus, runtimeJudgment: Wo
   if (validationStatus !== 'PASS') {
     return validationStatus;
   }
-  return runtimeJudgment === 'PASS' ? 'PASS' : 'BLOCKED';
+  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[], syncBackReady: boolean, gaps: string[], gateNextAction: string | null, gateDecision: WorkflowGateDecision | null): UnifiedTestEvidenceRun {
+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,
@@ -849,17 +979,16 @@ function buildUnifiedTestEvidenceRun(id: string, branch: string, runId: string,
     commands: steps.map((step) => ({
       command: step.command,
       status: step.status === 'pass' ? 'PASS' : step.status === 'fail' ? 'FAIL' : 'BLOCKED',
-      outputRef: { kind: 'artifact', ref: step.outputArtifact },
-      evidenceRefs: [{ kind: 'artifact', ref: step.outputArtifact }],
+      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,
-    syncBackReady,
     gaps: [...gaps, ...acceptanceCoverage.flatMap((coverage) => coverage.gaps)],
-    next: nextForTestResult(status, runtimeJudgment, branch, taskId, runId, `artifacts/test-index-${taskId}.json`, gateNextAction, gateDecision),
+    next: nextForTestResult(status, runtimeJudgment, branch, taskId, gateNextAction, gateDecision),
     generatedAt: new Date().toISOString()
   };
 }
@@ -908,12 +1037,6 @@ function capabilityClassForRejectedSource(status: AgentCapabilityRouteDecision['
   return 'diagnostic';
 }
 
-function renderCapabilityEvidenceClassification(items: CapabilityEvidenceClassification[]): string {
-  if (items.length === 0) {
-    return '- none';
-  }
-  return items.map((item) => `- [${item.class}] ${item.source}:${item.domainOrSourceId} — ${item.reason}`).join('\n');
-}
 
 function capabilityEvidenceSummary(items: CapabilityEvidenceClassification[]): string {
   if (items.length === 0) {
@@ -926,31 +1049,37 @@ function capabilityEvidenceSummary(items: CapabilityEvidenceClassification[]): s
   return [...counts.entries()].map(([kind, count]) => `${kind}:${count}`).join(',');
 }
 
-function nextForTestResult(status: SddTestStatus, runtimeJudgment: WorkflowGateStatus, branch: string, taskId: string, _runId: string, indexArtifact: string, gateNextAction: string | null, gateDecision: WorkflowGateDecision | null): string {
+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 ship --branch ${branch} --dry-run`;
+    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 sdd test task ${taskId} --branch ${branch}.` : `Create a decision card, then rerun sdd test task ${taskId} --branch ${branch}.`;
+    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 sdd test task ${taskId} --branch ${branch} or proceed only with explicit review.` : `Review workflow gate warnings, then rerun sdd test task ${taskId} --branch ${branch}.`;
+    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 `Inspect ${indexArtifact}, fix failing validation commands, then rerun sdd test task ${taskId} --branch ${branch}.`;
+    return `${inspectHint}, fix failing validation commands, then rerun ${testValidationUnitCommand(branch, taskId)}.`;
   }
-  return gateDecision ? `Inspect ${indexArtifact} and workflow gate ${gateDecision.decisionId}, resolve blockers, then rerun sdd test task ${taskId} --branch ${branch}.` : `Inspect ${indexArtifact}, fix command/evidence gaps, then rerun sdd test task ${taskId} --branch ${branch}.`;
+  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 release readiness.';
+    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}.`;
@@ -974,7 +1103,7 @@ function renderEvidenceBlocks(task: SddTask, status: SddTestStatus, sourceArtifa
   }
   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((step) => `  - command:${step.command}\n  - artifact:${step.outputArtifact}`).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\`\`\``;
+    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');
 }
 
@@ -1023,10 +1152,39 @@ function evidenceStatusForMappedSteps(status: SddTestStatus, steps: SddTestComma
   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): 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\n## stdout\n\n\`\`\`text\n${executed.stdout}\n\`\`\`\n\n## stderr\n\n\`\`\`text\n${executed.stderr}\n\`\`\`\n`;
+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');
 }