sdd-agent-platform 0.4.2 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/verification/{goal-verify.ts → task-evidence-judgment.ts}

@@ -1,619 +1,619 @@
-import { createHash } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
-import {
-  ACCEPTANCE_POLICY_RULESET_VERSION,
-  SDD_EVIDENCE_CONTRACT,
-  SDD_EVIDENCE_VERSION,
-  SDD_RESULT_CONTRACT,
-  SDD_RESULT_VERSION
-} from '../contracts.js';
-import { artifactKind, readArtifact, recordRuntimeOnlyArtifact } from '../run-state/artifacts.js';
-import { appendEvent } from '../run-state/events.js';
-import { appendArtifactHashLedgerEntry, appendDeclaredCommandLedgerEntries, appendInvocationLedgerEntry, listInvocationLedgerEntries } from '../run-state/invocation-ledger.js';
-import type { InvocationLedgerEntry, InvocationLedgerKind, RunState, RunStateTaskRuntime } from '../run-state/model.js';
-import { readRunState, writeRunState } from '../run-state/run-state.js';
-import { getBranchStageEvidencePathFromRef, isBranchStageEvidenceRef, toBranchStageEvidenceRef, toEvidencePayloadFileName } from '../runtime-paths.js';
-import { hasRuntimeEvidenceScopeViolation, readRuntimeEvidenceClaims } from '../context/evidence-summary.js';
-import type { ArtifactTrustValidationReport, EvidenceClaim, EvidenceCoverageStatus, EvidenceQualityIssue } from '../artifacts/sdd-evidence.js';
-import { validateSddResultArtifact } from '../artifacts/sdd-result.js';
-import type { SddResultStatus } from '../artifacts/sdd-result.js';
-import { taskGap } from '../sdd-docs/task-inspection.js';
-import { inspectSddTask } from '../sdd-docs/task-inspection.js';
-import type { SddTask, SddTaskGap } from '../sdd-docs/task-parser.js';
-import { resolveTaskRun } from '../workflow-state/resolve-task-run.js';
-
-export type GoalVerifyStatus = 'PASS' | 'PASS_WITH_GAPS' | 'FAIL' | 'BLOCKED';
-export type HarnessVerifyStatus = 'PASS' | 'GAPS' | 'BLOCKED' | 'HUMAN_NEEDED';
-
-export interface GoalVerifyOptions {
-  branch?: string;
-  taskId: string;
-  runId?: string;
-  reviewArtifact?: string;
-  validationArtifact?: string;
-}
-
-interface PolicyRuleSet {
-  id: typeof ACCEPTANCE_POLICY_RULESET_VERSION;
-  version: string;
-  ruleIds: string[];
-}
-
-interface PolicyDecision {
-  status: EvidenceCoverageStatus;
-  ruleSet: PolicyRuleSet;
-  passedRules: string[];
-  failedRules: string[];
-  issueCodes: EvidenceQualityIssue[];
-}
-
-export interface AcceptanceCoverageItem {
-  acceptance: string;
-  status: EvidenceCoverageStatus;
-  evidence: string;
-  policyDecision?: PolicyDecision;
-  issueCodes?: EvidenceQualityIssue[];
-}
-
-export interface GoalVerifyResult {
-  runId: string;
-  taskId: string;
-  status: GoalVerifyStatus;
-  task: SddTask | null;
-  reviewArtifact: string | null;
-  validationArtifact: string | null;
-  coverageArtifactPath: string;
-  acceptanceCoverage: AcceptanceCoverageItem[];
-  gaps: SddTaskGap[];
-  commands: string[];
-  plannedCommands: string[];
-  executedCommands: string[];
-  standardStatus: HarnessVerifyStatus;
-  message: string;
-}
-
-interface AcceptanceCoverageTarget {
-  label: string;
-  description: string | null;
-  matchTexts: string[];
-}
-
-export async function runGoalVerify(projectRoot: string, options: GoalVerifyOptions): Promise<GoalVerifyResult> {
-  const resolved = await resolveTaskRun(projectRoot, { runId: options.runId, branch: options.branch, taskId: options.taskId });
-  const branch = resolved.context.partition;
-  const model = resolved.model;
-  const inspected = { task: resolved.task, gaps: inspectSddTask(model, options.taskId).gaps };
-  const runId = resolved.runId;
-  const state = resolved.state;
-  const reviewArtifact = options.reviewArtifact ?? artifactPathForAgent(state, options.taskId, 'reviewer');
-  const validationArtifact = options.validationArtifact ?? artifactPathForAgent(state, options.taskId, 'validator');
-  const gaps: SddTaskGap[] = [...inspected.gaps];
-  const plannedCommands = inspected.task?.validation ?? [];
-  for (const reason of resolved.staleReasons) {
-    gaps.push(taskGap(options.taskId, 'run_snapshot', reason, 'Rerun sdd do task for the current partition before verify.'));
-  }
-  for (const conflict of resolved.affectedFileConflicts) {
-    gaps.push(taskGap(options.taskId, 'affected_files', `Affected file ${conflict.file} is active in run ${conflict.runId} for ${conflict.partition}/${conflict.taskId}.`, 'Resolve or archive the conflicting active run before verify.'));
-  }
-  const acceptanceCoverage: AcceptanceCoverageItem[] = [];
-  const acceptedArtifacts: string[] = [];
-  let reviewStatus: SddResultStatus | null = null;
-  let validationStatus: SddResultStatus | null = null;
-  let validationTrust: ArtifactTrustValidationReport | null = null;
-  let executedCommands: string[] = [];
-
-  await appendEvent(projectRoot, runId, {
-    event: 'phase_started',
-    runId,
-    summary: `Phase 1.9 goal-level verify started for ${options.taskId}`,
-    data: { phase: 'verify', branch, task: options.taskId }
-  });
-
-  if (!inspected.task) {
-    gaps.push(taskGap(options.taskId, 'task', `Task ${options.taskId} was not found for goal-level verification.`, 'Create the task or choose an existing task id before verify.'));
-  }
-
-  if (!reviewArtifact) {
-    gaps.push(taskGap(options.taskId, 'review_artifact', 'No reviewer evidence was supplied or selected from runtime state.', 'Author reviewer evidence under .sdd/runs/<branch>/do/code-review-vN.md and register its ref/hash before goal-level verify.'));
-  } else {
-    const reviewReport = await validateSddResultArtifact(projectRoot, runId, reviewArtifact, { expectedTask: options.taskId, expectedAgent: 'reviewer' });
-    if (!reviewReport.valid || !reviewReport.result) {
-      gaps.push(taskGap(options.taskId, 'review_artifact', `Reviewer artifact ${reviewArtifact} is invalid: ${reviewReport.issues.map((issue) => issue.message).join('; ')}`, 'Fix reviewer artifact contract before goal-level verify.'));
-    } else {
-      reviewStatus = reviewReport.result.status;
-      acceptedArtifacts.push(reviewArtifact);
-      if (reviewReport.result.status !== 'PASS') {
-        gaps.push(taskGap(options.taskId, 'review_status', `Reviewer status is ${reviewReport.result.status}, not PASS.`, 'Resolve review findings before marking verification PASS.'));
-      }
-    }
-  }
-
-  if (!validationArtifact) {
-    gaps.push(taskGap(options.taskId, 'validation_artifact', 'No validator evidence was supplied or selected from runtime state.', 'Author validator evidence under .sdd/runs/<branch>/test/validation-vN.md and register its ref/hash before goal-level verify.'));
-  } else {
-    const validationReport = await validateSddResultArtifact(projectRoot, runId, validationArtifact, { expectedTask: options.taskId, expectedAgent: 'validator' });
-    validationTrust = validationReport.trust ?? null;
-    if (!validationReport.valid || !validationReport.result) {
-      gaps.push(taskGap(options.taskId, 'validation_artifact', `Validator artifact ${validationArtifact} is invalid: ${validationReport.issues.map((issue) => issue.message).join('; ')}`, 'Fix validator artifact contract before goal-level verify.'));
-    } else {
-      validationStatus = validationReport.result.status;
-      acceptedArtifacts.push(validationArtifact);
-      if (validationReport.result.status === 'FAIL' || validationReport.result.status === 'BLOCKED') {
-        gaps.push(taskGap(options.taskId, 'validation_status', `Validator status is ${validationReport.result.status}.`, 'Do not mark task completed; inspect validation gaps and recovery proposal.'));
-      }
-    }
-  }
-
-  if (inspected.task) {
-    const validationRaw = validationArtifact ? await readArtifactIfExists(projectRoot, runId, validationArtifact) : '';
-    const reviewRaw = reviewArtifact ? await readArtifactIfExists(projectRoot, runId, reviewArtifact) : '';
-    if (reviewArtifact && reviewRaw.length > 0) {
-      await appendArtifactHashLedgerEntry(projectRoot, { runId, taskId: options.taskId, branch, artifactPath: reviewArtifact, content: reviewRaw });
-    }
-    if (validationArtifact && validationRaw.length > 0) {
-      await appendArtifactHashLedgerEntry(projectRoot, { runId, taskId: options.taskId, branch, artifactPath: validationArtifact, content: validationRaw });
-    }
-    await appendDeclaredCommandLedgerEntries(projectRoot, { runId, taskId: options.taskId, branch, commands: inspected.task.validation });
-    const invocationLedger = await listInvocationLedgerEntries(projectRoot, runId);
-    executedCommands = executedCommandsFromLedger(invocationLedger);
-    const admittedClaims = await readRuntimeEvidenceClaims(projectRoot, runId, options.taskId);
-    const scopeViolation = await hasRuntimeEvidenceScopeViolation(projectRoot, runId, options.taskId);
-    if (scopeViolation) {
-      gaps.push(taskGap(options.taskId, 'runtime_scope', 'PARTITION_SCOPE_VIOLATION: Runtime evidence claims do not match the run partition.', 'Reingest validator evidence in the correct branch/partition before verify.'));
-    }
-    for (const target of taskAcceptanceCoverageTargets(inspected.task)) {
-      const coverage = scopeViolation
-        ? acceptanceCoverageDecision(target.label, 'BLOCKED', 'Runtime evidence scope violation blocks acceptance coverage.', ['PARTITION_SCOPE_VIOLATION'], [], ['require-partition-scope'])
-        : evaluateAcceptanceCoverageTarget(target, {
-          taskId: options.taskId,
-          validationArtifact,
-          validationRaw,
-          claims: admittedClaims.length > 0 ? admittedClaims : validationTrust?.claims ?? [],
-          validationStatus,
-          invocationLedger
-        });
-      await appendInvocationLedgerEntry(projectRoot, {
-        runId,
-        taskId: options.taskId,
-        branch,
-        kind: 'policy_evaluation',
-        ref: `${ACCEPTANCE_POLICY_RULESET_VERSION}:${target.label}`,
-        status: coverage.status,
-        artifactPath: validationArtifact,
-        inputHash: validationRaw.length > 0 ? hashDocumentContent(validationRaw) : null,
-        materialRefs: [],
-        metadata: {
-          passedRules: coverage.policyDecision?.passedRules.join(',') ?? '',
-          failedRules: coverage.policyDecision?.failedRules.join(',') ?? '',
-          issueCodes: coverage.issueCodes?.join(',') ?? ''
-        }
-      });
-      acceptanceCoverage.push(coverage);
-      if (coverage.status !== 'PASS') {
-        gaps.push(taskGap(options.taskId, 'acceptance_coverage', `Acceptance target ${target.label} is ${coverage.status}: ${coverage.evidence}`, `Add ${SDD_EVIDENCE_CONTRACT} claim/evidence/provenance/policy records for ${target.label}; mention-only acceptance refs cannot pass.`));
-      }
-    }
-  }
-
-  const status = deriveGoalVerifyStatus(reviewStatus, validationStatus, gaps);
-  const standardStatus = toHarnessVerifyStatus(status, reviewStatus, validationStatus, gaps);
-  const coverageFileName = `acceptance-coverage-${options.taskId}.md`;
-  const coverageRef = toBranchStageEvidenceRef(branch, 'goal-verify', coverageFileName);
-  await recordRuntimeOnlyArtifact(projectRoot, runId, coverageFileName, renderAcceptanceCoverageArtifact(options.taskId, status, coverageRef, inspected.task, reviewArtifact, validationArtifact, acceptanceCoverage, gaps, executedCommands), { logicalRef: coverageRef, branch, taskId: options.taskId, artifactRole: 'goal-verify-acceptance-coverage' });
-  const allArtifacts = [...acceptedArtifacts, coverageRef];
-
-  await persistVerifyState(projectRoot, runId, {
-    status,
-    taskId: options.taskId,
-    taskState: buildGoalVerifyTaskState(inspected.task, status, gaps, allArtifacts, acceptanceCoverage),
-    commands: plannedCommands,
-    evidence: allArtifacts,
-    artifacts: allArtifacts.map((artifactPath) => ({ path: artifactPath, kind: artifactKind(artifactPath), task: options.taskId, agent: agentFromArtifactPath(artifactPath) }))
-  });
-  await appendEvent(projectRoot, runId, {
-    event: status === 'PASS' ? 'validation_passed' : 'validation_failed',
-    runId,
-    summary: `Phase 1.9 goal-level verify ${status} for ${options.taskId}`,
-    data: { task: options.taskId, status, coverageArtifact: coverageRef, gaps, plannedCommands, executedCommands }
-  });
-
-  return {
-    runId,
-    taskId: options.taskId,
-    status,
-    task: inspected.task,
-    reviewArtifact,
-    validationArtifact,
-    coverageArtifactPath: coverageRef,
-    acceptanceCoverage,
-    gaps,
-    commands: plannedCommands,
-    plannedCommands,
-    executedCommands,
-    standardStatus,
-    message: status === 'PASS' ? 'Goal-level verify passed with explicit acceptance coverage.' : 'Goal-level verify found gaps; inspect coverage artifact.'
-  };
-}
-
-function buildGoalVerifyTaskState(task: SddTask | null, status: GoalVerifyStatus, gaps: SddTaskGap[], artifacts: string[], acceptanceCoverage: unknown[]): RunStateTaskRuntime {
-  const verificationStatus = status === 'PASS' ? 'pass' : status === 'PASS_WITH_GAPS' ? 'pass_with_gaps' : status === 'FAIL' ? 'failed' : 'blocked';
-  return {
-    status: status === 'PASS' ? 'implemented_verified' : verificationStatus === 'pass_with_gaps' ? 'validation_blocked' : verificationStatus === 'failed' ? 'validation_failed' : 'validation_blocked',
-    implementationStatus: 'implemented',
-    verificationStatus,
-    validationBatch: task?.validationBatch ?? null,
-    validationTiming: task?.validationTiming ?? 'task_end',
-    requiresVerifyBeforeNext: task?.requiresVerifyBeforeNext ?? true,
-    verifyStatus: status,
-    gaps,
-    artifacts,
-    acceptanceCoverage
-  };
-}
-
-async function persistVerifyState(projectRoot: string, runId: string, input: {
-  status: GoalVerifyStatus;
-  taskId: string;
-  taskState: RunStateTaskRuntime;
-  commands: string[];
-  evidence: string[];
-  artifacts: Array<{ path: string; kind: string; task: string; agent: string }>;
-}): Promise<void> {
-  const state = await readRunState(projectRoot, runId);
-  const now = new Date().toISOString();
-  const knownArtifactPaths = new Set(state.artifacts.map((artifact) => artifact.path));
-  const newArtifacts = input.artifacts
-    .filter((artifact) => !knownArtifactPaths.has(artifact.path))
-    .map((artifact) => ({ ...artifact, createdAt: now }));
-  await writeRunState(projectRoot, {
-    ...state,
-    status: input.status === 'PASS' ? 'completed' : 'blocked',
-    phase: 'verify',
-    currentTask: input.taskId,
-    tasks: {
-      ...state.tasks,
-      [input.taskId]: input.taskState
-    },
-    artifacts: [...state.artifacts, ...newArtifacts],
-    validation: {
-      status: input.status === 'PASS' ? 'pass' : input.status === 'PASS_WITH_GAPS' ? 'pass_with_gaps' : input.status === 'BLOCKED' ? 'blocked' : 'fail',
-      commands: input.commands,
-      evidence: input.evidence
-    },
-  });
-}
-
-
-function renderAcceptanceCoverageArtifact(taskId: string, status: GoalVerifyStatus, coverageRef: string, task: SddTask | null, reviewArtifact: string | null, validationArtifact: string | null, coverage: AcceptanceCoverageItem[], gaps: SddTaskGap[], executedCommands: string[]): string {
-  return `# Acceptance Coverage ${taskId}\n\n\`\`\`sdd-result\ncontract: ${SDD_RESULT_CONTRACT}\nversion: ${SDD_RESULT_VERSION}\nagent: validator\ntask: ${taskId}\nstatus: ${status}\nartifacts:\n  - ${coverageRef}\n\`\`\`\n\n## Source Evidence\n\n- review_artifact: ${reviewArtifact ?? 'missing'}\n- validation_artifact: ${validationArtifact ?? 'missing'}\n- task_source: ${task ? sourceLocationEvidence(task.source) : 'missing'}\n\n## Planned Validation Commands\n\n${task && task.validation.length > 0 ? task.validation.map((command) => `- ${command}`).join('\n') : '- none'}\n\n## Executed Runtime Commands\n\n${executedCommands.length > 0 ? executedCommands.map((command) => `- ${command}`).join('\n') : '- none'}\n\n## Acceptance Mapping\n\n${coverage.length > 0 ? coverage.map((item) => `- [${item.status}] ${item.acceptance} Evidence: ${item.evidence}`).join('\n') : '- No acceptance items available.'}\n\n## Policy Decisions\n\n${coverage.length > 0 ? coverage.map((item) => `- ${item.acceptance}: status=${item.policyDecision?.status ?? item.status}; ruleset=${item.policyDecision?.ruleSet.id ?? ACCEPTANCE_POLICY_RULESET_VERSION}; passed=${item.policyDecision?.passedRules.join(',') || 'none'}; failed=${item.policyDecision?.failedRules.join(',') || 'none'}; issues=${item.issueCodes?.join(',') || 'none'}`).join('\n') : '- none'}\n\n## Gaps\n\n${gaps.length > 0 ? gaps.map((gap) => `- [${gap.severity}] ${gap.type} ${gap.field}: ${gap.message} Recommendation: ${gap.recommendation}`).join('\n') : '- none'}\n`;
-}
-
-function evaluateAcceptanceCoverageTarget(target: AcceptanceCoverageTarget, input: { taskId: string; validationArtifact: string | null; validationRaw: string; claims: EvidenceClaim[]; validationStatus: SddResultStatus | null; invocationLedger: InvocationLedgerEntry[] }): AcceptanceCoverageItem {
-  const matchingClaims = input.claims.filter((claim) => claim.task === input.taskId && acceptanceMatchesTarget(target, claim.acceptance));
-  const issueCodes: EvidenceQualityIssue[] = [];
-  const failedRules: string[] = [];
-  if (matchingClaims.length === 0) {
-    if (target.matchTexts.some((text) => text.length > 0 && input.validationRaw.toLowerCase().includes(text.toLowerCase()))) {
-      issueCodes.push('MENTION_ONLY');
-      failedRules.push('require-structured-evidence');
-      return acceptanceCoverageDecision(target.label, 'REFERENCED_ONLY', `Referenced ${target.label} in ${input.validationArtifact ?? 'validator artifact'} without policy-backed evidence.`, issueCodes, [], failedRules);
-    }
-    issueCodes.push('MISSING_ARTIFACT_REFERENCE');
-    failedRules.push('require-acceptance-claim');
-    return acceptanceCoverageDecision(target.label, 'MISSING', 'No policy-backed acceptance evidence found in validator artifact.', issueCodes, [], failedRules);
-  }
-
-  let best = matchingClaims[0];
-  let bestRank = evidenceClaimSelectionRank(best, input);
-  for (const claim of matchingClaims.slice(1)) {
-    const rank = evidenceClaimSelectionRank(claim, input);
-    if (rank > bestRank) {
-      best = claim;
-      bestRank = rank;
-    }
-  }
-
-  if (best.status === 'PASS') {
-    const ledgerDecision = evaluatePassClaimPolicy(best, input);
-    if (ledgerDecision.issueCodes.length === 0) {
-      return acceptanceCoverageDecision(target.label, 'PASS', `Policy-proven by ${SDD_EVIDENCE_CONTRACT} claim for ${best.acceptance} in ${best.sourceArtifact}; evidence=${best.evidence.map((item) => `${item.kind}:${item.ref}`).join(', ')}; provenance=${best.provenance.join(', ')}; policy=${best.policy.join(', ')}.`, [], ledgerDecision.passedRules, []);
-    }
-    return acceptanceCoverageDecision(target.label, 'BLOCKED', `PASS claim for ${best.acceptance} is missing required policy/provenance corroboration.`, ledgerDecision.issueCodes, [], ledgerDecision.failedRules);
-  }
-
-  if (best.status === 'FAIL') {
-    return acceptanceCoverageDecision(target.label, 'FAIL', `Explicit FAIL claim for ${best.acceptance}: ${best.claim}`, [], ['explicit-fail-overrides-pass'], []);
-  }
-  if (best.status === 'BLOCKED') {
-    return acceptanceCoverageDecision(target.label, 'BLOCKED', `Explicit BLOCKED claim for ${best.acceptance}: ${best.claim}`, [], ['explicit-blocked-overrides-pass'], []);
-  }
-  if (best.status === 'REFERENCED_ONLY') {
-    return acceptanceCoverageDecision(target.label, 'REFERENCED_ONLY', `Structured evidence references ${best.acceptance} but does not prove PASS.`, ['MENTION_ONLY'], [], ['require-pass-claim']);
-  }
-  return acceptanceCoverageDecision(target.label, 'MISSING', `Structured evidence marks ${best.acceptance} missing.`, ['MISSING_ARTIFACT_REFERENCE'], [], ['require-pass-claim']);
-}
-
-function evidenceClaimSelectionRank(claim: EvidenceClaim, input: { validationStatus: SddResultStatus | null; invocationLedger: InvocationLedgerEntry[] }): number {
-  if (claim.status === 'FAIL') {
-    return 500;
-  }
-  if (claim.status === 'BLOCKED') {
-    return 400;
-  }
-  if (claim.status === 'PASS') {
-    const decision = evaluatePassClaimPolicy(claim, input);
-    return decision.issueCodes.length === 0 ? 300 : 200 - decision.issueCodes.length;
-  }
-  if (claim.status === 'REFERENCED_ONLY') {
-    return 100;
-  }
-  return 0;
-}
-
-function evaluatePassClaimPolicy(claim: EvidenceClaim, input: { validationStatus: SddResultStatus | null; invocationLedger: InvocationLedgerEntry[] }): { issueCodes: EvidenceQualityIssue[]; failedRules: string[]; passedRules: string[] } {
-  const issueCodes: EvidenceQualityIssue[] = [];
-  const failedRules: string[] = [];
-  const passedRules: string[] = [];
-  const addFailure = (code: EvidenceQualityIssue, rule: string): void => {
-    if (!issueCodes.includes(code)) {
-      issueCodes.push(code);
-    }
-    if (!failedRules.includes(rule)) {
-      failedRules.push(rule);
-    }
-  };
-  const addPassed = (rule: string): void => {
-    if (!passedRules.includes(rule)) {
-      passedRules.push(rule);
-    }
-  };
-  if (claim.evidence.length === 0) {
-    addFailure('UNSOURCED_PASS', 'require-source-evidence');
-  } else {
-    addPassed('require-source-evidence');
-  }
-  if (claim.provenance.length === 0) {
-    addFailure('PROVENANCE_GAP', 'require-provenance');
-  } else {
-    addPassed('require-provenance');
-  }
-  if (claim.policy.length === 0) {
-    addFailure('POLICY_RULE_FAILED', 'require-policy-rule');
-  } else {
-    addPassed('require-policy-rule');
-  }
-  if (input.validationStatus !== 'PASS') {
-    addFailure('POLICY_RULE_FAILED', 'require-validator-pass');
-  } else {
-    addPassed('require-validator-pass');
-  }
-  const ledgerDecision = evaluateClaimLedgerCorroboration(claim, input.invocationLedger);
-  for (const issue of ledgerDecision.issueCodes) {
-    if (!issueCodes.includes(issue)) {
-      issueCodes.push(issue);
-    }
-  }
-  for (const rule of ledgerDecision.failedRules) {
-    if (!failedRules.includes(rule)) {
-      failedRules.push(rule);
-    }
-  }
-  if (ledgerDecision.failedRules.length === 0) {
-    addPassed('require-ledger-corroboration');
-  }
-  return { issueCodes, failedRules, passedRules };
-}
-
-function evaluateClaimLedgerCorroboration(claim: EvidenceClaim, entries: InvocationLedgerEntry[]): { issueCodes: EvidenceQualityIssue[]; failedRules: string[] } {
-  const issueCodes: EvidenceQualityIssue[] = [];
-  const failedRules: string[] = [];
-  const commandRefs = invocationLedgerRefs(entries, 'command');
-  const artifactRefs = invocationLedgerRefs(entries, 'artifact_hash');
-  const materialRefs = ledgerMaterialRefs(entries);
-  const addIssue = (code: EvidenceQualityIssue, rule: string): void => {
-    if (!issueCodes.includes(code)) {
-      issueCodes.push(code);
-    }
-    if (!failedRules.includes(rule)) {
-      failedRules.push(rule);
-    }
-  };
-
-  if (!artifactRefs.has(claim.sourceArtifact)) {
-    addIssue('MISSING_ARTIFACT_REFERENCE', 'require-source-artifact-hash');
-  }
-  for (const item of claim.evidence) {
-    if (item.kind === 'command' && !commandRefs.has(item.ref)) {
-      addIssue('MISSING_COMMAND_OUTPUT', 'require-command-ledger');
-    }
-    if (item.kind === 'artifact' && !artifactRefs.has(item.ref)) {
-      addIssue('MISSING_ARTIFACT_REFERENCE', 'require-artifact-hash');
-    }
-    if (item.kind === 'material' && !materialRefs.has(item.ref)) {
-      addIssue('MISSING_MATERIAL_REFERENCE', 'require-material-ledger');
-    }
-  }
-  for (const ref of claim.provenance) {
-    const typed = parseTypedLedgerRef(ref);
-    if (!typed) {
-      continue;
-    }
-    if (typed.kind === 'command' && !commandRefs.has(typed.ref)) {
-      addIssue('PROVENANCE_GAP', 'require-command-provenance-ledger');
-    }
-    if (typed.kind === 'artifact' && !artifactRefs.has(typed.ref)) {
-      addIssue('PROVENANCE_GAP', 'require-artifact-provenance-ledger');
-    }
-    if (typed.kind === 'material' && !materialRefs.has(typed.ref)) {
-      addIssue('PROVENANCE_GAP', 'require-material-provenance-ledger');
-    }
-  }
-  return { issueCodes, failedRules };
-}
-
-function invocationLedgerRefs(entries: InvocationLedgerEntry[], kind: InvocationLedgerKind): Set<string> {
-  const refs = new Set<string>();
-  for (const entry of entries) {
-    if (entry.kind === kind) {
-      refs.add(entry.ref);
-      if (entry.artifactPath) {
-        refs.add(entry.artifactPath);
-      }
-      if (kind === 'command' && typeof entry.metadata.stepId === 'string') {
-        refs.add(entry.metadata.stepId);
-      }
-    }
-  }
-  return refs;
-}
-
-function parseTypedLedgerRef(value: string): { kind: string; ref: string } | null {
-  const separator = value.indexOf(':');
-  if (separator <= 0) {
-    return null;
-  }
-  const kind = value.slice(0, separator).trim();
-  const ref = value.slice(separator + 1).trim();
-  if (!/^[A-Za-z0-9_-]+$/.test(kind) || !ref) {
-    return null;
-  }
-  return { kind, ref };
-}
-
-function acceptanceMatchesTarget(target: AcceptanceCoverageTarget, acceptance: string): boolean {
-  const normalizedAcceptance = acceptance.toLowerCase();
-  return target.matchTexts.some((text) => text.toLowerCase() === normalizedAcceptance) || target.label.toLowerCase() === normalizedAcceptance;
-}
-
-
-function acceptanceCoverageDecision(acceptance: string, status: EvidenceCoverageStatus, evidence: string, issueCodes: EvidenceQualityIssue[], passedRules: string[], failedRules: string[]): AcceptanceCoverageItem {
-  return {
-    acceptance,
-    status,
-    evidence,
-    issueCodes,
-    policyDecision: {
-      status,
-      ruleSet: {
-        id: ACCEPTANCE_POLICY_RULESET_VERSION,
-        version: SDD_EVIDENCE_VERSION,
-        ruleIds: ['require-structured-evidence', 'require-source-evidence', 'require-provenance', 'require-policy-rule']
-      },
-      passedRules,
-      failedRules,
-      issueCodes
-    }
-  };
-}
-
-function taskAcceptanceCoverageTargets(task: SddTask): AcceptanceCoverageTarget[] {
-  if (task.acceptanceRefs.length > 0) {
-    return task.acceptanceRefs.map((ref, index) => {
-      const description = task.acceptance[index] ?? null;
-      return {
-        label: ref,
-        description,
-        matchTexts: description ? [ref, description] : [ref]
-      };
-    });
-  }
-  return task.acceptance.map((acceptance) => ({
-    label: acceptance,
-    description: null,
-    matchTexts: [acceptance]
-  }));
-}
-
-function deriveGoalVerifyStatus(reviewStatus: SddResultStatus | null, validationStatus: SddResultStatus | null, gaps: SddTaskGap[]): GoalVerifyStatus {
-  if (gaps.length > 0) {
-    return validationStatus === 'PASS_WITH_GAPS' ? 'PASS_WITH_GAPS' : 'BLOCKED';
-  }
-  if (reviewStatus !== 'PASS' || !validationStatus) {
-    return 'BLOCKED';
-  }
-  if (validationStatus === 'PASS') {
-    return 'PASS';
-  }
-  if (validationStatus === 'PASS_WITH_GAPS') {
-    return 'PASS_WITH_GAPS';
-  }
-  return validationStatus === 'FAIL' ? 'FAIL' : 'BLOCKED';
-}
-
-function toHarnessVerifyStatus(status: GoalVerifyStatus, reviewStatus: SddResultStatus | null, validationStatus: SddResultStatus | null, gaps: SddTaskGap[]): HarnessVerifyStatus {
-  if (status === 'PASS') {
-    return 'PASS';
-  }
-  if (status === 'PASS_WITH_GAPS') {
-    return 'GAPS';
-  }
-  if (!reviewStatus || !validationStatus || gaps.some((gap) => gap.field === 'review_artifact' || gap.field === 'validation_artifact')) {
-    return 'HUMAN_NEEDED';
-  }
-  return 'BLOCKED';
-}
-
-async function readArtifactIfExists(projectRoot: string, runId: string, runRelativeArtifactPath: string): Promise<string> {
-  try {
-    if (isBranchStageEvidenceRef(runRelativeArtifactPath)) {
-      try {
-        return await readFile(getBranchStageEvidencePathFromRef(projectRoot, runRelativeArtifactPath), 'utf8');
-      } catch {
-        return await readArtifact(projectRoot, runId, toEvidencePayloadFileName(runRelativeArtifactPath));
-      }
-    }
-    return await readArtifact(projectRoot, runId, toEvidencePayloadFileName(runRelativeArtifactPath));
-  } catch {
-    return '';
-  }
-}
-
-function artifactPathForAgent(state: RunState, taskId: string, agent: string): string | null {
-  const delegation = Object.values(state.delegations).find((candidate) => candidate.task === taskId && candidate.agent === agent && candidate.status === 'COMPLETED');
-  if (delegation) {
-    return delegation.expectedArtifact;
-  }
-  const artifact = state.artifacts.find((candidate) => candidate.task === taskId && candidate.agent === agent);
-  return artifact?.path ?? null;
-}
-
-function agentFromArtifactPath(artifactPath: string): string {
-  const kind = artifactKind(artifactPath);
-  if (kind === 'implement') {
-    return 'implementer';
-  }
-  if (kind === 'review' || kind === 'validation' || kind === 'debug') {
-    return kind === 'debug' ? 'debugger' : kind === 'review' ? 'reviewer' : 'validator';
-  }
-  if (kind === 'gap-report') {
-    return 'runtime';
-  }
-  return 'unknown';
-}
-
-function executedCommandsFromLedger(entries: InvocationLedgerEntry[]): string[] {
-  return [...new Set(entries
-    .filter((entry) => entry.kind === 'command' && entry.status !== 'declared')
-    .map((entry) => entry.ref))];
-}
-
-function sourceLocationEvidence(source: SddTask['source']): string {
-  return `${source.filePath}:${source.lineStart}-${source.lineEnd}`;
-}
-
-function ledgerMaterialRefs(entries: InvocationLedgerEntry[]): Set<string> {
-  const refs = new Set<string>();
-  for (const entry of entries) {
-    if (entry.kind === 'material') {
-      refs.add(entry.ref);
-    }
-    for (const ref of entry.materialRefs) {
-      refs.add(ref);
-    }
-  }
-  return refs;
-}
-
-function hashDocumentContent(raw: string): string {
-  return createHash('sha256').update(raw.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
-}
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import {
+  ACCEPTANCE_POLICY_RULESET_VERSION,
+  SDD_EVIDENCE_CONTRACT,
+  SDD_EVIDENCE_VERSION,
+  SDD_RESULT_CONTRACT,
+  SDD_RESULT_VERSION
+} from '../contracts.js';
+import { artifactKind, readArtifact, recordRuntimeOnlyArtifact } from '../run-state/artifacts.js';
+import { appendEvent } from '../run-state/events.js';
+import { appendArtifactHashLedgerEntry, appendDeclaredCommandLedgerEntries, appendInvocationLedgerEntry, listInvocationLedgerEntries } from '../run-state/invocation-ledger.js';
+import type { InvocationLedgerEntry, InvocationLedgerKind, RunState, RunStateTaskRuntime } from '../run-state/model.js';
+import { readRunState, writeRunState } from '../run-state/run-state.js';
+import { getBranchStageEvidencePathFromRef, isBranchStageEvidenceRef, toBranchStageEvidenceRef, toEvidencePayloadFileName } from '../runtime-paths.js';
+import { hasRuntimeEvidenceScopeViolation, readRuntimeEvidenceClaims } from '../context/evidence-summary.js';
+import type { ArtifactTrustValidationReport, EvidenceClaim, EvidenceCoverageStatus, EvidenceQualityIssue } from '../artifacts/sdd-evidence.js';
+import { validateSddResultArtifact } from '../artifacts/sdd-result.js';
+import type { SddResultStatus } from '../artifacts/sdd-result.js';
+import { taskGap } from '../sdd-docs/task-inspection.js';
+import { inspectSddTask } from '../sdd-docs/task-inspection.js';
+import type { SddTask, SddTaskGap } from '../sdd-docs/task-parser.js';
+import { resolveTaskRun } from '../workflow-state/resolve-task-run.js';
+
+export type TaskEvidenceJudgmentStatus = 'PASS' | 'PASS_WITH_GAPS' | 'FAIL' | 'BLOCKED';
+export type HarnessVerifyStatus = 'PASS' | 'GAPS' | 'BLOCKED' | 'HUMAN_NEEDED';
+
+export interface TaskEvidenceJudgmentOptions {
+  branch?: string;
+  taskId: string;
+  runId?: string;
+  reviewArtifact?: string;
+  validationArtifact?: string;
+}
+
+interface PolicyRuleSet {
+  id: typeof ACCEPTANCE_POLICY_RULESET_VERSION;
+  version: string;
+  ruleIds: string[];
+}
+
+interface PolicyDecision {
+  status: EvidenceCoverageStatus;
+  ruleSet: PolicyRuleSet;
+  passedRules: string[];
+  failedRules: string[];
+  issueCodes: EvidenceQualityIssue[];
+}
+
+export interface AcceptanceCoverageItem {
+  acceptance: string;
+  status: EvidenceCoverageStatus;
+  evidence: string;
+  policyDecision?: PolicyDecision;
+  issueCodes?: EvidenceQualityIssue[];
+}
+
+export interface TaskEvidenceJudgmentResult {
+  runId: string;
+  taskId: string;
+  status: TaskEvidenceJudgmentStatus;
+  task: SddTask | null;
+  reviewArtifact: string | null;
+  validationArtifact: string | null;
+  coverageArtifactPath: string;
+  acceptanceCoverage: AcceptanceCoverageItem[];
+  gaps: SddTaskGap[];
+  commands: string[];
+  plannedCommands: string[];
+  executedCommands: string[];
+  standardStatus: HarnessVerifyStatus;
+  message: string;
+}
+
+interface AcceptanceCoverageTarget {
+  label: string;
+  description: string | null;
+  matchTexts: string[];
+}
+
+export async function runTaskEvidenceJudgment(projectRoot: string, options: TaskEvidenceJudgmentOptions): Promise<TaskEvidenceJudgmentResult> {
+  const resolved = await resolveTaskRun(projectRoot, { runId: options.runId, branch: options.branch, taskId: options.taskId });
+  const branch = resolved.context.partition;
+  const model = resolved.model;
+  const inspected = { task: resolved.task, gaps: inspectSddTask(model, options.taskId).gaps };
+  const runId = resolved.runId;
+  const state = resolved.state;
+  const reviewArtifact = options.reviewArtifact ?? artifactPathForAgent(state, options.taskId, 'reviewer');
+  const validationArtifact = options.validationArtifact ?? artifactPathForAgent(state, options.taskId, 'validator');
+  const gaps: SddTaskGap[] = [...inspected.gaps];
+  const plannedCommands = inspected.task?.validation ?? [];
+  for (const reason of resolved.staleReasons) {
+    gaps.push(taskGap(options.taskId, 'run_snapshot', reason, 'Rerun sdd execute for the current partition before verify.'));
+  }
+  for (const conflict of resolved.affectedFileConflicts) {
+    gaps.push(taskGap(options.taskId, 'affected_files', `Affected file ${conflict.file} is active in run ${conflict.runId} for ${conflict.partition}/${conflict.taskId}.`, 'Resolve or archive the conflicting active run before verify.'));
+  }
+  const acceptanceCoverage: AcceptanceCoverageItem[] = [];
+  const acceptedArtifacts: string[] = [];
+  let reviewStatus: SddResultStatus | null = null;
+  let validationStatus: SddResultStatus | null = null;
+  let validationTrust: ArtifactTrustValidationReport | null = null;
+  let executedCommands: string[] = [];
+
+  await appendEvent(projectRoot, runId, {
+    event: 'phase_started',
+    runId,
+    summary: `Execute evidence judgment started for ${options.taskId}`,
+    data: { phase: 'verify', branch, task: options.taskId }
+  });
+
+  if (!inspected.task) {
+    gaps.push(taskGap(options.taskId, 'task', `Task ${options.taskId} was not found for goal-level verification.`, 'Create the task or choose an existing task id before verify.'));
+  }
+
+  if (!reviewArtifact) {
+    gaps.push(taskGap(options.taskId, 'review_artifact', 'No reviewer evidence was supplied or selected from runtime state.', 'Author reviewer evidence under .sdd/runs/<branch>/execute/code-review-vN.md and register its ref/hash before execute evidence judgment.'));
+  } else {
+    const reviewReport = await validateSddResultArtifact(projectRoot, runId, reviewArtifact, { expectedTask: options.taskId, expectedAgent: 'reviewer' });
+    if (!reviewReport.valid || !reviewReport.result) {
+      gaps.push(taskGap(options.taskId, 'review_artifact', `Reviewer artifact ${reviewArtifact} is invalid: ${reviewReport.issues.map((issue) => issue.message).join('; ')}`, 'Fix reviewer artifact contract before execute evidence judgment.'));
+    } else {
+      reviewStatus = reviewReport.result.status;
+      acceptedArtifacts.push(reviewArtifact);
+      if (reviewReport.result.status !== 'PASS') {
+        gaps.push(taskGap(options.taskId, 'review_status', `Reviewer status is ${reviewReport.result.status}, not PASS.`, 'Resolve review findings before marking verification PASS.'));
+      }
+    }
+  }
+
+  if (!validationArtifact) {
+    gaps.push(taskGap(options.taskId, 'validation_artifact', 'No validator evidence was supplied or selected from runtime state.', 'Author validator evidence under .sdd/runs/<branch>/execute/validation-vN.md and register its ref/hash before execute evidence judgment.'));
+  } else {
+    const validationReport = await validateSddResultArtifact(projectRoot, runId, validationArtifact, { expectedTask: options.taskId, expectedAgent: 'validator' });
+    validationTrust = validationReport.trust ?? null;
+    if (!validationReport.valid || !validationReport.result) {
+      gaps.push(taskGap(options.taskId, 'validation_artifact', `Validator artifact ${validationArtifact} is invalid: ${validationReport.issues.map((issue) => issue.message).join('; ')}`, 'Fix validator artifact contract before execute evidence judgment.'));
+    } else {
+      validationStatus = validationReport.result.status;
+      acceptedArtifacts.push(validationArtifact);
+      if (validationReport.result.status === 'FAIL' || validationReport.result.status === 'BLOCKED') {
+        gaps.push(taskGap(options.taskId, 'validation_status', `Validator status is ${validationReport.result.status}.`, 'Do not mark task completed; inspect validation gaps and recovery proposal.'));
+      }
+    }
+  }
+
+  if (inspected.task) {
+    const validationRaw = validationArtifact ? await readArtifactIfExists(projectRoot, runId, validationArtifact) : '';
+    const reviewRaw = reviewArtifact ? await readArtifactIfExists(projectRoot, runId, reviewArtifact) : '';
+    if (reviewArtifact && reviewRaw.length > 0) {
+      await appendArtifactHashLedgerEntry(projectRoot, { runId, taskId: options.taskId, branch, artifactPath: reviewArtifact, content: reviewRaw });
+    }
+    if (validationArtifact && validationRaw.length > 0) {
+      await appendArtifactHashLedgerEntry(projectRoot, { runId, taskId: options.taskId, branch, artifactPath: validationArtifact, content: validationRaw });
+    }
+    await appendDeclaredCommandLedgerEntries(projectRoot, { runId, taskId: options.taskId, branch, commands: inspected.task.validation });
+    const invocationLedger = await listInvocationLedgerEntries(projectRoot, runId);
+    executedCommands = executedCommandsFromLedger(invocationLedger);
+    const admittedClaims = await readRuntimeEvidenceClaims(projectRoot, runId, options.taskId);
+    const scopeViolation = await hasRuntimeEvidenceScopeViolation(projectRoot, runId, options.taskId);
+    if (scopeViolation) {
+      gaps.push(taskGap(options.taskId, 'runtime_scope', 'PARTITION_SCOPE_VIOLATION: Runtime evidence claims do not match the run partition.', 'Reingest validator evidence in the correct branch/partition before verify.'));
+    }
+    for (const target of taskAcceptanceCoverageTargets(inspected.task)) {
+      const coverage = scopeViolation
+        ? acceptanceCoverageDecision(target.label, 'BLOCKED', 'Runtime evidence scope violation blocks acceptance coverage.', ['PARTITION_SCOPE_VIOLATION'], [], ['require-partition-scope'])
+        : evaluateAcceptanceCoverageTarget(target, {
+          taskId: options.taskId,
+          validationArtifact,
+          validationRaw,
+          claims: admittedClaims.length > 0 ? admittedClaims : validationTrust?.claims ?? [],
+          validationStatus,
+          invocationLedger
+        });
+      await appendInvocationLedgerEntry(projectRoot, {
+        runId,
+        taskId: options.taskId,
+        branch,
+        kind: 'policy_evaluation',
+        ref: `${ACCEPTANCE_POLICY_RULESET_VERSION}:${target.label}`,
+        status: coverage.status,
+        artifactPath: validationArtifact,
+        inputHash: validationRaw.length > 0 ? hashDocumentContent(validationRaw) : null,
+        materialRefs: [],
+        metadata: {
+          passedRules: coverage.policyDecision?.passedRules.join(',') ?? '',
+          failedRules: coverage.policyDecision?.failedRules.join(',') ?? '',
+          issueCodes: coverage.issueCodes?.join(',') ?? ''
+        }
+      });
+      acceptanceCoverage.push(coverage);
+      if (coverage.status !== 'PASS') {
+        gaps.push(taskGap(options.taskId, 'acceptance_coverage', `Acceptance target ${target.label} is ${coverage.status}: ${coverage.evidence}`, `Add ${SDD_EVIDENCE_CONTRACT} claim/evidence/provenance/policy records for ${target.label}; mention-only acceptance refs cannot pass.`));
+      }
+    }
+  }
+
+  const status = deriveTaskEvidenceJudgmentStatus(reviewStatus, validationStatus, gaps);
+  const standardStatus = toHarnessVerifyStatus(status, reviewStatus, validationStatus, gaps);
+  const coverageFileName = `acceptance-coverage-${options.taskId}.md`;
+  const coverageRef = toBranchStageEvidenceRef(branch, 'execute', coverageFileName);
+  await recordRuntimeOnlyArtifact(projectRoot, runId, coverageFileName, renderAcceptanceCoverageArtifact(options.taskId, status, coverageRef, inspected.task, reviewArtifact, validationArtifact, acceptanceCoverage, gaps, executedCommands), { logicalRef: coverageRef, branch, taskId: options.taskId, artifactRole: 'task-evidence-judgment-acceptance-coverage' });
+  const allArtifacts = [...acceptedArtifacts, coverageRef];
+
+  await persistVerifyState(projectRoot, runId, {
+    status,
+    taskId: options.taskId,
+    taskState: buildTaskEvidenceJudgmentTaskState(inspected.task, status, gaps, allArtifacts, acceptanceCoverage),
+    commands: plannedCommands,
+    evidence: allArtifacts,
+    artifacts: allArtifacts.map((artifactPath) => ({ path: artifactPath, kind: artifactKind(artifactPath), task: options.taskId, agent: agentFromArtifactPath(artifactPath) }))
+  });
+  await appendEvent(projectRoot, runId, {
+    event: status === 'PASS' ? 'validation_passed' : 'validation_failed',
+    runId,
+    summary: `Execute evidence judgment ${status} for ${options.taskId}`,
+    data: { task: options.taskId, status, coverageArtifact: coverageRef, gaps, plannedCommands, executedCommands }
+  });
+
+  return {
+    runId,
+    taskId: options.taskId,
+    status,
+    task: inspected.task,
+    reviewArtifact,
+    validationArtifact,
+    coverageArtifactPath: coverageRef,
+    acceptanceCoverage,
+    gaps,
+    commands: plannedCommands,
+    plannedCommands,
+    executedCommands,
+    standardStatus,
+    message: status === 'PASS' ? 'Task evidence judgment passed with explicit acceptance coverage.' : 'Task evidence judgment found gaps; inspect coverage artifact.'
+  };
+}
+
+function buildTaskEvidenceJudgmentTaskState(task: SddTask | null, status: TaskEvidenceJudgmentStatus, gaps: SddTaskGap[], artifacts: string[], acceptanceCoverage: unknown[]): RunStateTaskRuntime {
+  const verificationStatus = status === 'PASS' ? 'pass' : status === 'PASS_WITH_GAPS' ? 'pass_with_gaps' : status === 'FAIL' ? 'failed' : 'blocked';
+  return {
+    status: status === 'PASS' ? 'implemented_verified' : verificationStatus === 'pass_with_gaps' ? 'validation_blocked' : verificationStatus === 'failed' ? 'validation_failed' : 'validation_blocked',
+    implementationStatus: 'implemented',
+    verificationStatus,
+    validationBatch: task?.validationBatch ?? null,
+    validationTiming: task?.validationTiming ?? 'task_end',
+    requiresVerifyBeforeNext: task?.requiresVerifyBeforeNext ?? true,
+    verifyStatus: status,
+    gaps,
+    artifacts,
+    acceptanceCoverage
+  };
+}
+
+async function persistVerifyState(projectRoot: string, runId: string, input: {
+  status: TaskEvidenceJudgmentStatus;
+  taskId: string;
+  taskState: RunStateTaskRuntime;
+  commands: string[];
+  evidence: string[];
+  artifacts: Array<{ path: string; kind: string; task: string; agent: string }>;
+}): Promise<void> {
+  const state = await readRunState(projectRoot, runId);
+  const now = new Date().toISOString();
+  const knownArtifactPaths = new Set(state.artifacts.map((artifact) => artifact.path));
+  const newArtifacts = input.artifacts
+    .filter((artifact) => !knownArtifactPaths.has(artifact.path))
+    .map((artifact) => ({ ...artifact, createdAt: now }));
+  await writeRunState(projectRoot, {
+    ...state,
+    status: input.status === 'PASS' ? 'completed' : 'blocked',
+    phase: 'verify',
+    currentTask: input.taskId,
+    tasks: {
+      ...state.tasks,
+      [input.taskId]: input.taskState
+    },
+    artifacts: [...state.artifacts, ...newArtifacts],
+    validation: {
+      status: input.status === 'PASS' ? 'pass' : input.status === 'PASS_WITH_GAPS' ? 'pass_with_gaps' : input.status === 'BLOCKED' ? 'blocked' : 'fail',
+      commands: input.commands,
+      evidence: input.evidence
+    },
+  });
+}
+
+
+function renderAcceptanceCoverageArtifact(taskId: string, status: TaskEvidenceJudgmentStatus, coverageRef: string, task: SddTask | null, reviewArtifact: string | null, validationArtifact: string | null, coverage: AcceptanceCoverageItem[], gaps: SddTaskGap[], executedCommands: string[]): string {
+  return `# Acceptance Coverage ${taskId}\n\n\`\`\`sdd-result\ncontract: ${SDD_RESULT_CONTRACT}\nversion: ${SDD_RESULT_VERSION}\nagent: validator\ntask: ${taskId}\nstatus: ${status}\nartifacts:\n  - ${coverageRef}\n\`\`\`\n\n## Source Evidence\n\n- review_artifact: ${reviewArtifact ?? 'missing'}\n- validation_artifact: ${validationArtifact ?? 'missing'}\n- task_source: ${task ? sourceLocationEvidence(task.source) : 'missing'}\n\n## Planned Validation Commands\n\n${task && task.validation.length > 0 ? task.validation.map((command) => `- ${command}`).join('\n') : '- none'}\n\n## Executed Runtime Commands\n\n${executedCommands.length > 0 ? executedCommands.map((command) => `- ${command}`).join('\n') : '- none'}\n\n## Acceptance Mapping\n\n${coverage.length > 0 ? coverage.map((item) => `- [${item.status}] ${item.acceptance} Evidence: ${item.evidence}`).join('\n') : '- No acceptance items available.'}\n\n## Policy Decisions\n\n${coverage.length > 0 ? coverage.map((item) => `- ${item.acceptance}: status=${item.policyDecision?.status ?? item.status}; ruleset=${item.policyDecision?.ruleSet.id ?? ACCEPTANCE_POLICY_RULESET_VERSION}; passed=${item.policyDecision?.passedRules.join(',') || 'none'}; failed=${item.policyDecision?.failedRules.join(',') || 'none'}; issues=${item.issueCodes?.join(',') || 'none'}`).join('\n') : '- none'}\n\n## Gaps\n\n${gaps.length > 0 ? gaps.map((gap) => `- [${gap.severity}] ${gap.type} ${gap.field}: ${gap.message} Recommendation: ${gap.recommendation}`).join('\n') : '- none'}\n`;
+}
+
+function evaluateAcceptanceCoverageTarget(target: AcceptanceCoverageTarget, input: { taskId: string; validationArtifact: string | null; validationRaw: string; claims: EvidenceClaim[]; validationStatus: SddResultStatus | null; invocationLedger: InvocationLedgerEntry[] }): AcceptanceCoverageItem {
+  const matchingClaims = input.claims.filter((claim) => claim.task === input.taskId && acceptanceMatchesTarget(target, claim.acceptance));
+  const issueCodes: EvidenceQualityIssue[] = [];
+  const failedRules: string[] = [];
+  if (matchingClaims.length === 0) {
+    if (target.matchTexts.some((text) => text.length > 0 && input.validationRaw.toLowerCase().includes(text.toLowerCase()))) {
+      issueCodes.push('MENTION_ONLY');
+      failedRules.push('require-structured-evidence');
+      return acceptanceCoverageDecision(target.label, 'REFERENCED_ONLY', `Referenced ${target.label} in ${input.validationArtifact ?? 'validator artifact'} without policy-backed evidence.`, issueCodes, [], failedRules);
+    }
+    issueCodes.push('MISSING_ARTIFACT_REFERENCE');
+    failedRules.push('require-acceptance-claim');
+    return acceptanceCoverageDecision(target.label, 'MISSING', 'No policy-backed acceptance evidence found in validator artifact.', issueCodes, [], failedRules);
+  }
+
+  let best = matchingClaims[0];
+  let bestRank = evidenceClaimSelectionRank(best, input);
+  for (const claim of matchingClaims.slice(1)) {
+    const rank = evidenceClaimSelectionRank(claim, input);
+    if (rank > bestRank) {
+      best = claim;
+      bestRank = rank;
+    }
+  }
+
+  if (best.status === 'PASS') {
+    const ledgerDecision = evaluatePassClaimPolicy(best, input);
+    if (ledgerDecision.issueCodes.length === 0) {
+      return acceptanceCoverageDecision(target.label, 'PASS', `Policy-proven by ${SDD_EVIDENCE_CONTRACT} claim for ${best.acceptance} in ${best.sourceArtifact}; evidence=${best.evidence.map((item) => `${item.kind}:${item.ref}`).join(', ')}; provenance=${best.provenance.join(', ')}; policy=${best.policy.join(', ')}.`, [], ledgerDecision.passedRules, []);
+    }
+    return acceptanceCoverageDecision(target.label, 'BLOCKED', `PASS claim for ${best.acceptance} is missing required policy/provenance corroboration.`, ledgerDecision.issueCodes, [], ledgerDecision.failedRules);
+  }
+
+  if (best.status === 'FAIL') {
+    return acceptanceCoverageDecision(target.label, 'FAIL', `Explicit FAIL claim for ${best.acceptance}: ${best.claim}`, [], ['explicit-fail-overrides-pass'], []);
+  }
+  if (best.status === 'BLOCKED') {
+    return acceptanceCoverageDecision(target.label, 'BLOCKED', `Explicit BLOCKED claim for ${best.acceptance}: ${best.claim}`, [], ['explicit-blocked-overrides-pass'], []);
+  }
+  if (best.status === 'REFERENCED_ONLY') {
+    return acceptanceCoverageDecision(target.label, 'REFERENCED_ONLY', `Structured evidence references ${best.acceptance} but does not prove PASS.`, ['MENTION_ONLY'], [], ['require-pass-claim']);
+  }
+  return acceptanceCoverageDecision(target.label, 'MISSING', `Structured evidence marks ${best.acceptance} missing.`, ['MISSING_ARTIFACT_REFERENCE'], [], ['require-pass-claim']);
+}
+
+function evidenceClaimSelectionRank(claim: EvidenceClaim, input: { validationStatus: SddResultStatus | null; invocationLedger: InvocationLedgerEntry[] }): number {
+  if (claim.status === 'FAIL') {
+    return 500;
+  }
+  if (claim.status === 'BLOCKED') {
+    return 400;
+  }
+  if (claim.status === 'PASS') {
+    const decision = evaluatePassClaimPolicy(claim, input);
+    return decision.issueCodes.length === 0 ? 300 : 200 - decision.issueCodes.length;
+  }
+  if (claim.status === 'REFERENCED_ONLY') {
+    return 100;
+  }
+  return 0;
+}
+
+function evaluatePassClaimPolicy(claim: EvidenceClaim, input: { validationStatus: SddResultStatus | null; invocationLedger: InvocationLedgerEntry[] }): { issueCodes: EvidenceQualityIssue[]; failedRules: string[]; passedRules: string[] } {
+  const issueCodes: EvidenceQualityIssue[] = [];
+  const failedRules: string[] = [];
+  const passedRules: string[] = [];
+  const addFailure = (code: EvidenceQualityIssue, rule: string): void => {
+    if (!issueCodes.includes(code)) {
+      issueCodes.push(code);
+    }
+    if (!failedRules.includes(rule)) {
+      failedRules.push(rule);
+    }
+  };
+  const addPassed = (rule: string): void => {
+    if (!passedRules.includes(rule)) {
+      passedRules.push(rule);
+    }
+  };
+  if (claim.evidence.length === 0) {
+    addFailure('UNSOURCED_PASS', 'require-source-evidence');
+  } else {
+    addPassed('require-source-evidence');
+  }
+  if (claim.provenance.length === 0) {
+    addFailure('PROVENANCE_GAP', 'require-provenance');
+  } else {
+    addPassed('require-provenance');
+  }
+  if (claim.policy.length === 0) {
+    addFailure('POLICY_RULE_FAILED', 'require-policy-rule');
+  } else {
+    addPassed('require-policy-rule');
+  }
+  if (input.validationStatus !== 'PASS') {
+    addFailure('POLICY_RULE_FAILED', 'require-validator-pass');
+  } else {
+    addPassed('require-validator-pass');
+  }
+  const ledgerDecision = evaluateClaimLedgerCorroboration(claim, input.invocationLedger);
+  for (const issue of ledgerDecision.issueCodes) {
+    if (!issueCodes.includes(issue)) {
+      issueCodes.push(issue);
+    }
+  }
+  for (const rule of ledgerDecision.failedRules) {
+    if (!failedRules.includes(rule)) {
+      failedRules.push(rule);
+    }
+  }
+  if (ledgerDecision.failedRules.length === 0) {
+    addPassed('require-ledger-corroboration');
+  }
+  return { issueCodes, failedRules, passedRules };
+}
+
+function evaluateClaimLedgerCorroboration(claim: EvidenceClaim, entries: InvocationLedgerEntry[]): { issueCodes: EvidenceQualityIssue[]; failedRules: string[] } {
+  const issueCodes: EvidenceQualityIssue[] = [];
+  const failedRules: string[] = [];
+  const commandRefs = invocationLedgerRefs(entries, 'command');
+  const artifactRefs = invocationLedgerRefs(entries, 'artifact_hash');
+  const materialRefs = ledgerMaterialRefs(entries);
+  const addIssue = (code: EvidenceQualityIssue, rule: string): void => {
+    if (!issueCodes.includes(code)) {
+      issueCodes.push(code);
+    }
+    if (!failedRules.includes(rule)) {
+      failedRules.push(rule);
+    }
+  };
+
+  if (!artifactRefs.has(claim.sourceArtifact)) {
+    addIssue('MISSING_ARTIFACT_REFERENCE', 'require-source-artifact-hash');
+  }
+  for (const item of claim.evidence) {
+    if (item.kind === 'command' && !commandRefs.has(item.ref)) {
+      addIssue('MISSING_COMMAND_OUTPUT', 'require-command-ledger');
+    }
+    if (item.kind === 'artifact' && !artifactRefs.has(item.ref)) {
+      addIssue('MISSING_ARTIFACT_REFERENCE', 'require-artifact-hash');
+    }
+    if (item.kind === 'material' && !materialRefs.has(item.ref)) {
+      addIssue('MISSING_MATERIAL_REFERENCE', 'require-material-ledger');
+    }
+  }
+  for (const ref of claim.provenance) {
+    const typed = parseTypedLedgerRef(ref);
+    if (!typed) {
+      continue;
+    }
+    if (typed.kind === 'command' && !commandRefs.has(typed.ref)) {
+      addIssue('PROVENANCE_GAP', 'require-command-provenance-ledger');
+    }
+    if (typed.kind === 'artifact' && !artifactRefs.has(typed.ref)) {
+      addIssue('PROVENANCE_GAP', 'require-artifact-provenance-ledger');
+    }
+    if (typed.kind === 'material' && !materialRefs.has(typed.ref)) {
+      addIssue('PROVENANCE_GAP', 'require-material-provenance-ledger');
+    }
+  }
+  return { issueCodes, failedRules };
+}
+
+function invocationLedgerRefs(entries: InvocationLedgerEntry[], kind: InvocationLedgerKind): Set<string> {
+  const refs = new Set<string>();
+  for (const entry of entries) {
+    if (entry.kind === kind) {
+      refs.add(entry.ref);
+      if (entry.artifactPath) {
+        refs.add(entry.artifactPath);
+      }
+      if (kind === 'command' && typeof entry.metadata.stepId === 'string') {
+        refs.add(entry.metadata.stepId);
+      }
+    }
+  }
+  return refs;
+}
+
+function parseTypedLedgerRef(value: string): { kind: string; ref: string } | null {
+  const separator = value.indexOf(':');
+  if (separator <= 0) {
+    return null;
+  }
+  const kind = value.slice(0, separator).trim();
+  const ref = value.slice(separator + 1).trim();
+  if (!/^[A-Za-z0-9_-]+$/.test(kind) || !ref) {
+    return null;
+  }
+  return { kind, ref };
+}
+
+function acceptanceMatchesTarget(target: AcceptanceCoverageTarget, acceptance: string): boolean {
+  const normalizedAcceptance = acceptance.toLowerCase();
+  return target.matchTexts.some((text) => text.toLowerCase() === normalizedAcceptance) || target.label.toLowerCase() === normalizedAcceptance;
+}
+
+
+function acceptanceCoverageDecision(acceptance: string, status: EvidenceCoverageStatus, evidence: string, issueCodes: EvidenceQualityIssue[], passedRules: string[], failedRules: string[]): AcceptanceCoverageItem {
+  return {
+    acceptance,
+    status,
+    evidence,
+    issueCodes,
+    policyDecision: {
+      status,
+      ruleSet: {
+        id: ACCEPTANCE_POLICY_RULESET_VERSION,
+        version: SDD_EVIDENCE_VERSION,
+        ruleIds: ['require-structured-evidence', 'require-source-evidence', 'require-provenance', 'require-policy-rule']
+      },
+      passedRules,
+      failedRules,
+      issueCodes
+    }
+  };
+}
+
+function taskAcceptanceCoverageTargets(task: SddTask): AcceptanceCoverageTarget[] {
+  if (task.acceptanceRefs.length > 0) {
+    return task.acceptanceRefs.map((ref, index) => {
+      const description = task.acceptance[index] ?? null;
+      return {
+        label: ref,
+        description,
+        matchTexts: description ? [ref, description] : [ref]
+      };
+    });
+  }
+  return task.acceptance.map((acceptance) => ({
+    label: acceptance,
+    description: null,
+    matchTexts: [acceptance]
+  }));
+}
+
+function deriveTaskEvidenceJudgmentStatus(reviewStatus: SddResultStatus | null, validationStatus: SddResultStatus | null, gaps: SddTaskGap[]): TaskEvidenceJudgmentStatus {
+  if (gaps.length > 0) {
+    return validationStatus === 'PASS_WITH_GAPS' ? 'PASS_WITH_GAPS' : 'BLOCKED';
+  }
+  if (reviewStatus !== 'PASS' || !validationStatus) {
+    return 'BLOCKED';
+  }
+  if (validationStatus === 'PASS') {
+    return 'PASS';
+  }
+  if (validationStatus === 'PASS_WITH_GAPS') {
+    return 'PASS_WITH_GAPS';
+  }
+  return validationStatus === 'FAIL' ? 'FAIL' : 'BLOCKED';
+}
+
+function toHarnessVerifyStatus(status: TaskEvidenceJudgmentStatus, reviewStatus: SddResultStatus | null, validationStatus: SddResultStatus | null, gaps: SddTaskGap[]): HarnessVerifyStatus {
+  if (status === 'PASS') {
+    return 'PASS';
+  }
+  if (status === 'PASS_WITH_GAPS') {
+    return 'GAPS';
+  }
+  if (!reviewStatus || !validationStatus || gaps.some((gap) => gap.field === 'review_artifact' || gap.field === 'validation_artifact')) {
+    return 'HUMAN_NEEDED';
+  }
+  return 'BLOCKED';
+}
+
+async function readArtifactIfExists(projectRoot: string, runId: string, runRelativeArtifactPath: string): Promise<string> {
+  try {
+    if (isBranchStageEvidenceRef(runRelativeArtifactPath)) {
+      try {
+        return await readFile(getBranchStageEvidencePathFromRef(projectRoot, runRelativeArtifactPath), 'utf8');
+      } catch {
+        return await readArtifact(projectRoot, runId, toEvidencePayloadFileName(runRelativeArtifactPath));
+      }
+    }
+    return await readArtifact(projectRoot, runId, toEvidencePayloadFileName(runRelativeArtifactPath));
+  } catch {
+    return '';
+  }
+}
+
+function artifactPathForAgent(state: RunState, taskId: string, agent: string): string | null {
+  const delegation = Object.values(state.delegations).find((candidate) => candidate.task === taskId && candidate.agent === agent && candidate.status === 'COMPLETED');
+  if (delegation) {
+    return delegation.expectedArtifact;
+  }
+  const artifact = state.artifacts.find((candidate) => candidate.task === taskId && candidate.agent === agent);
+  return artifact?.path ?? null;
+}
+
+function agentFromArtifactPath(artifactPath: string): string {
+  const kind = artifactKind(artifactPath);
+  if (kind === 'implement') {
+    return 'implementer';
+  }
+  if (kind === 'review' || kind === 'validation' || kind === 'debug') {
+    return kind === 'debug' ? 'debugger' : kind === 'review' ? 'reviewer' : 'validator';
+  }
+  if (kind === 'gap-report') {
+    return 'runtime';
+  }
+  return 'unknown';
+}
+
+function executedCommandsFromLedger(entries: InvocationLedgerEntry[]): string[] {
+  return [...new Set(entries
+    .filter((entry) => entry.kind === 'command' && entry.status !== 'declared')
+    .map((entry) => entry.ref))];
+}
+
+function sourceLocationEvidence(source: SddTask['source']): string {
+  return `${source.filePath}:${source.lineStart}-${source.lineEnd}`;
+}
+
+function ledgerMaterialRefs(entries: InvocationLedgerEntry[]): Set<string> {
+  const refs = new Set<string>();
+  for (const entry of entries) {
+    if (entry.kind === 'material') {
+      refs.add(entry.ref);
+    }
+    for (const ref of entry.materialRefs) {
+      refs.add(ref);
+    }
+  }
+  return refs;
+}
+
+function hashDocumentContent(raw: string): string {
+  return createHash('sha256').update(raw.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+}