sdd-agent-platform 0.4.0 → 0.4.1

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

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 
@@ -8,17 +8,17 @@ import { validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js'
 import { inspectVerifyContract, writeVerifyContract } from './verify-contract.js';
 
 
-test('inspectVerifyContract warns when verify document is missing', async () => {
+test('inspectVerifyContract blocks when verify document is missing', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-missing-'));
   try {
     await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
 
     const inspection = await inspectVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
 
-    assert.equal(inspection.status, 'WARN');
+    assert.equal(inspection.status, 'BLOCKED');
     assert.equal(inspection.exists, false);
     assert.equal(inspection.taskCount, 1);
-    assert.equal(inspection.issues.some((issue) => issue.field === 'verify.md' && issue.level === 'WARN'), true);
+    assert.equal(inspection.issues.some((issue) => issue.field === 'verify.md' && issue.level === 'FAIL'), true);
   } finally {
     await rm(root, { recursive: true, force: true });
   }
@@ -34,6 +34,9 @@ test('writeVerifyContract creates task-derived verify contract', async () => {
 
     assert.equal(written.status, 'created');
     assert.match(written.content, /contract: sdd-verify-doc-v1/);
+    assert.match(written.content, /verification_batches:/);
+    assert.match(written.content, /id: \"task-T1\"/);
+    assert.match(written.content, /failure_policy:\n      repair_flow: deferred/);
     assert.match(written.content, /\| T1 \|/);
     assert.match(written.content, /author_role: verification-designer/);
     assert.match(written.content, /independent_from_roles:\n  - task-planner\n  - implementer/);
@@ -47,6 +50,87 @@ test('writeVerifyContract creates task-derived verify contract', async () => {
   }
 });
 
+test('writeVerifyContract groups tasks by validation_batch', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-batch-'));
+  try {
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+### T1: UI copy
+
+\`\`\`sdd-task
+id: T1
+status: pending
+wave: 1
+depends_on: []
+acceptance_refs:
+  - AC-T1-copy
+affected_files:
+  - app/src/main/webapp/index.jsp
+change_surface: frontend_only
+implementation_wave: ui-wave-1
+validation_batch: ui-render-wave-1
+validation_timing: batch_end
+requires_verify_before_next: false
+validation:
+  - browser/manual check copy => AC-T1-copy
+required_artifacts:
+  - artifacts/ui-render-wave-1.md
+risk: []
+\`\`\`
+
+#### Boundary
+
+Only UI copy.
+
+#### Acceptance
+
+- Copy renders.
+
+### T2: UI image
+
+\`\`\`sdd-task
+id: T2
+status: pending
+wave: 1
+depends_on: []
+acceptance_refs:
+  - AC-T2-image
+affected_files:
+  - app/src/main/webapp/assets/banner.svg
+change_surface: frontend_only
+implementation_wave: ui-wave-1
+validation_batch: ui-render-wave-1
+validation_timing: batch_end
+requires_verify_before_next: false
+validation:
+  - browser/manual check image => AC-T2-image
+required_artifacts:
+  - artifacts/ui-render-wave-1.md
+risk: []
+\`\`\`
+
+#### Boundary
+
+Only UI image.
+
+#### Acceptance
+
+- Image renders.
+`);
+
+    const written = await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    assert.match(written.content, /id: \"ui-render-wave-1\"/);
+    assert.match(written.content, /timing: batch_end/);
+    assert.match(written.content, /change_surface: frontend_only/);
+    assert.match(written.content, /forbidden_validation:\n      - \"maven_compile\"\n      - \"gradle_build\"/);
+    assert.match(written.content, /T1:\n        - \"AC-T1-copy\"/);
+    assert.match(written.content, /T2:\n        - \"AC-T2-image\"/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test('inspectVerifyContract warns when verify document is stale', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-stale-'));
   try {
@@ -57,9 +141,64 @@ test('inspectVerifyContract warns when verify document is stale', async () => {
     const inspection = await inspectVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
 
     assert.equal(inspection.status, 'WARN');
-    assert.equal(inspection.issues.some((issue) => issue.field === 'based_on_tasks_hash'), true);
+    assert.equal(inspection.issues.some((issue) => issue.field === 'based_on_tasks_contract_hash'), true);
     assert.equal(inspection.issues.some((issue) => issue.field === 'tasks' && /T2/.test(issue.message)), true);
   } finally {
     await rm(root, { recursive: true, force: true });
   }
 });
+
+test('inspectVerifyContract blocks legacy verify documents without tasks contract hash', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-legacy-'));
+  try {
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const written = await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    await writeFile(path.join(root, 'specs', 'feature', 'verify.md'), written.content.replace(/^based_on_tasks_contract_hash: .+\n/m, ''), 'utf8');
+
+    const inspection = await inspectVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    assert.equal(inspection.status, 'BLOCKED');
+    assert.equal(inspection.issues.some((issue) => issue.field === 'based_on_tasks_contract_hash' && issue.level === 'FAIL'), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('writeVerifyContract upgrades legacy verify documents without force', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-upgrade-'));
+  try {
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const written = await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    await writeFile(path.join(root, 'specs', 'feature', 'verify.md'), written.content.replace(/^based_on_tasks_contract_hash: .+\n/m, ''), 'utf8');
+
+    const upgraded = await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    const inspection = await inspectVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    assert.equal(upgraded.status, 'updated');
+    assert.match(upgraded.content, /based_on_tasks_contract_hash: /);
+    assert.equal(inspection.status, 'PASS');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('writeVerifyContract preserves stale bound verify documents without force', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-preserve-stale-'));
+  try {
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const written = await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    const verifyPath = path.join(root, 'specs', 'feature', 'verify.md');
+    const initial = await readFile(verifyPath, 'utf8');
+    await writeFile(path.join(root, 'specs', 'feature', 'tasks.md'), validTaskMarkdown('T2', []), 'utf8');
+
+    const preserved = await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    const inspection = await inspectVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    assert.equal(written.status, 'created');
+    assert.equal(preserved.status, 'unchanged');
+    assert.equal(preserved.content, initial);
+    assert.equal(inspection.status, 'WARN');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/node_modules/@sdd-agent-platform/core/src/verification/verify-contract.ts

@@ -27,6 +27,8 @@ export interface VerifyContractInspection {
   status: VerifyContractStatus;
   basedOnTasksHash: string | null;
   currentTasksHash: string | null;
+  basedOnTasksContractHash: string | null;
+  currentTasksContractHash: string | null;
   issues: VerifyContractIssue[];
   taskCount: number;
   authorRole: VerifyContractAuthorRole | null;
@@ -58,10 +60,10 @@ export async function inspectVerifyContract(projectRoot: string, options: { bran
 
   if (!model.documents.verifyExists || raw === null) {
     issues.push({
-      level: 'WARN',
+      level: 'FAIL',
       field: 'verify.md',
       message: 'Verification contract document is missing.',
-      action: `Run sdd verifies write --branch ${context.partition} to create specs/${context.partition}/verify.md.`
+      action: `Run /sdd:tasks or sdd verifies write --branch ${context.partition} to create specs/${context.partition}/verify.md before /sdd:test.`
     });
   } else {
     if (!raw.includes(`contract: ${VERIFY_DOCUMENT_CONTRACT_VERSION}`)) {
@@ -72,12 +74,23 @@ export async function inspectVerifyContract(projectRoot: string, options: { bran
         action: 'Regenerate verify.md with sdd verifies write or update the frontmatter contract.'
       });
     }
+    if (!model.documents.verifyBasedOnTasksContractHash) {
+      issues.push({
+        level: 'FAIL',
+        field: 'based_on_tasks_contract_hash',
+        message: 'verify.md does not bind to the frozen tasks contract hash.',
+        action: `Run /sdd:tasks or sdd verifies write --branch ${context.partition} --force to regenerate verify.md from the current tasks contract.`
+      });
+    }
+
     if (model.documents.verifyStale) {
       issues.push({
-        level: 'WARN',
-        field: 'based_on_tasks_hash',
-        message: `verify.md is stale for current tasks hash ${model.documents.tasksHash}.`,
-        action: `Run sdd verifies write --branch ${context.partition} --force after reviewing task contract changes.`
+        level: model.documents.verifyBasedOnTasksContractHash ? 'WARN' : 'FAIL',
+        field: 'based_on_tasks_contract_hash',
+        message: model.documents.verifyBasedOnTasksContractHash
+          ? `verify.md is stale for current tasks contract hash ${model.documents.tasksContractHash}.`
+          : 'verify.md cannot be proven current because based_on_tasks_contract_hash is missing.',
+        action: `Run /sdd:tasks or sdd verifies write --branch ${context.partition} --force after reviewing task contract changes.`
       });
     }
     const authorRole = readDocumentScalar(raw, 'author_role');
@@ -86,7 +99,7 @@ export async function inspectVerifyContract(projectRoot: string, options: { bran
         level: 'WARN',
         field: 'author_role',
         message: `verify.md must be owned by ${VERIFY_CONTRACT_AUTHOR_ROLE}, not ${authorRole ?? 'missing'}.`,
-        action: 'Regenerate verify.md with a verification-designer role before running /sdd:test.'
+        action: 'Regenerate verify.md with a verification-designer role before running sdd test task.'
       });
     }
     const independentFromRoles = readDocumentList(raw, 'independent_from_roles');
@@ -100,6 +113,14 @@ export async function inspectVerifyContract(projectRoot: string, options: { bran
         });
       }
     }
+    if (!/^verification_batches:\s*$/m.test(raw)) {
+      issues.push({
+        level: 'FAIL',
+        field: 'verification_batches',
+        message: 'verify.md does not declare verification_batches from the frozen tasks contract.',
+        action: `Run /sdd:tasks or sdd verifies write --branch ${context.partition} --force to regenerate verify.md as a batch/wave validation plan.`
+      });
+    }
     for (const task of model.tasks) {
       if (!new RegExp(`\\b${escapeRegex(task.id)}\\b`).test(raw)) {
         issues.push({
@@ -120,6 +141,8 @@ export async function inspectVerifyContract(projectRoot: string, options: { bran
     status: issues.some((issue) => issue.level === 'FAIL') ? 'BLOCKED' : issues.length > 0 ? 'WARN' : 'PASS',
     basedOnTasksHash: model.documents.verifyBasedOnTasksHash ?? null,
     currentTasksHash: model.documents.tasksHash ?? null,
+    basedOnTasksContractHash: model.documents.verifyBasedOnTasksContractHash ?? null,
+    currentTasksContractHash: model.documents.tasksContractHash ?? null,
     issues,
     taskCount: model.tasks.length,
     authorRole: raw ? readDocumentScalar(raw, 'author_role') as VerifyContractAuthorRole | null : null,
@@ -134,13 +157,18 @@ export async function writeVerifyContract(projectRoot: string, options: { branch
   const existed = await exists(model.verifyPath);
   if (existed && !options.force) {
     const current = await readFile(model.verifyPath, 'utf8');
-    return {
-      branch: context.partition,
-      verifyPath: model.verifyPath,
-      relativePath: `specs/${context.partition}/verify.md`,
-      status: current === content ? 'unchanged' : 'unchanged',
-      content: current
-    };
+    const currentTasksContractHash = readDocumentScalar(current, 'based_on_tasks_contract_hash');
+    const hasCurrentBatchPlan = /^verification_batches:\s*$/m.test(current);
+    const hasContractBinding = Boolean(currentTasksContractHash && currentTasksContractHash !== 'missing');
+    if (current === content || (hasContractBinding && hasCurrentBatchPlan)) {
+      return {
+        branch: context.partition,
+        verifyPath: model.verifyPath,
+        relativePath: `specs/${context.partition}/verify.md`,
+        status: 'unchanged',
+        content: current
+      };
+    }
   }
   await mkdir(path.dirname(model.verifyPath), { recursive: true });
   await writeFile(model.verifyPath, content, 'utf8');
@@ -158,6 +186,7 @@ export function renderVerifyContractDocument(model: SddTaskModel, timestamp: str
 contract: ${VERIFY_DOCUMENT_CONTRACT_VERSION}
 version: 1.0.0
 branch: ${model.branch}
+based_on_tasks_contract_hash: ${model.documents.tasksContractHash ?? 'missing'}
 based_on_tasks_hash: ${model.documents.tasksHash ?? 'missing'}
 author_role: ${VERIFY_CONTRACT_AUTHOR_ROLE}
 independent_from_roles:
@@ -172,13 +201,18 @@ updated_at: ${timestamp}
 
 This document maps executable SDD tasks to verification expectations. It is derived from specs/${model.branch}/tasks.md and is not runtime evidence. It is owned by the verification-designer role and must remain independent from task planning and implementation authority.
 
-## 2. Task Verification Matrix
+## 2. Verification Batches
+
+verification_batches:
+${model.tasks.length > 0 ? renderVerificationBatches(model.tasks) : '  []'}
+
+## 3. Task Verification Matrix
 
 | Task | Acceptance refs | Validation commands | Required artifacts | Verification availability |
 |---|---|---|---|---|
 ${model.tasks.length > 0 ? model.tasks.map(renderTaskMatrixRow).join('\n') : '| none | none | none | none | none |'}
 
-## 3. Verification Rules
+## 4. Verification Rules
 
 - The agent that creates tasks.md must not be the same authority that owns verify.md.
 - The implementer must not own verify.md or perform authoritative goal verification.
@@ -186,15 +220,92 @@ ${model.tasks.length > 0 ? model.tasks.map(renderTaskMatrixRow).join('\n') : '|
 - Physical evidence files live under branch evidence .sdd/runs/<branchSlug>/evidence/artifacts/.
 - Goal-level verify must resolve the latest eligible run by branch and task unless --run is explicitly supplied for replay.
 - PASS requires policy-backed acceptance evidence, not mention-only acceptance text.
-- Sync-back must inspect the generated proposal before applying task status changes.
+- \`/sdd:test\` consumes this contract and must not create or refresh it.
+- Low-level sync-back may inspect or replay the generated proposal for diagnostic/recovery use, but normal workflow completion proceeds through test judgment and ship readiness.
 
-## 4. Out of Scope
+## 5. Out of Scope
 
 - This document does not replace runtime.sqlite, branch evidence artifacts, validator reports, or sync-back proposals.
 - This document does not authorize publish, push, tag, release, or source changes outside the selected task boundary.
 `;
 }
 
+interface VerificationBatch {
+  id: string;
+  tasks: SddTask[];
+}
+
+function renderVerificationBatches(tasks: SddTask[]): string {
+  const batches = new Map<string, VerificationBatch>();
+  for (const task of tasks) {
+    const id = task.validationBatch ?? `task-${task.id}`;
+    const existing = batches.get(id);
+    if (existing) {
+      existing.tasks.push(task);
+    } else {
+      batches.set(id, { id, tasks: [task] });
+    }
+  }
+  return Array.from(batches.values()).map(renderVerificationBatch).join('\n');
+}
+
+function renderVerificationBatch(batch: VerificationBatch): string {
+  const timing = batch.tasks.some((task) => task.validationTiming === 'wave_end') ? 'wave_end' : batch.tasks.some((task) => task.validationTiming === 'batch_end') ? 'batch_end' : 'task_end';
+  const changeSurface = unique(batch.tasks.map((task) => task.changeSurface)).length === 1 ? batch.tasks[0].changeSurface : 'mixed';
+  const requiredArtifacts = unique(batch.tasks.flatMap((task) => task.requiredArtifacts));
+  const forbiddenValidation = changeSurface === 'frontend_only' ? ['maven_compile', 'gradle_build'] : [];
+  return [
+    `  - id: ${quoteYaml(batch.id)}`,
+    `    timing: ${timing}`,
+    `    tasks:`,
+    ...batch.tasks.map((task) => `      - ${quoteYaml(task.id)}`),
+    `    change_surface: ${changeSurface}`,
+    `    checks:`,
+    ...renderBatchChecks(batch.tasks),
+    `    forbidden_validation:${renderInlineOrNestedList(forbiddenValidation, 6)}`,
+    `    required_artifacts:${renderInlineOrNestedList(requiredArtifacts, 6)}`,
+    `    acceptance_mapping:`,
+    ...renderAcceptanceMapping(batch.tasks),
+    `    failure_policy:`,
+    `      repair_flow: deferred`,
+    `      rerun_scope: pending_design`
+  ].join('\n');
+}
+
+function renderBatchChecks(tasks: SddTask[]): string[] {
+  const checks = unique(tasks.flatMap((task) => task.validation));
+  return checks.length > 0 ? checks.map((check) => `      - ${quoteYaml(check)}`) : ['      []'];
+}
+
+function renderAcceptanceMapping(tasks: SddTask[]): string[] {
+  const lines: string[] = [];
+  for (const task of tasks) {
+    lines.push(`      ${task.id}:`);
+    if (task.acceptanceRefs.length > 0) {
+      lines.push(...task.acceptanceRefs.map((ref) => `        - ${quoteYaml(ref)}`));
+    } else {
+      lines.push('        []');
+    }
+  }
+  return lines;
+}
+
+function renderInlineOrNestedList(values: string[], indent: number): string {
+  if (values.length === 0) {
+    return ' []';
+  }
+  const spaces = ' '.repeat(indent);
+  return `\n${values.map((value) => `${spaces}- ${quoteYaml(value)}`).join('\n')}`;
+}
+
+function unique(values: string[]): string[] {
+  return Array.from(new Set(values.filter(Boolean)));
+}
+
+function quoteYaml(value: string): string {
+  return JSON.stringify(value);
+}
+
 function renderTaskMatrixRow(task: SddTask): string {
   return `| ${task.id} | ${cell(task.acceptanceRefs)} | ${cell(task.validation)} | ${cell(task.requiredArtifacts)} | ${cell(task.verificationAvailability)} |`;
 }

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

@@ -4,3 +4,5 @@ export type { GoalVerifyResultLike, SingleTaskLoopResultLike } from './verificat
 export * from './verification/single-task-loop.js';
 export * from './verification/verify-contract.js';
 export * from './verification/test-runtime.js';
+export * from './verification/validation-wave.js';
+export * from './verification/review-gate.js';

package/node_modules/@sdd-agent-platform/core/src/workflow-gate/evidence-packet.ts

@@ -0,0 +1,196 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { WORKFLOW_GATE_RUNTIME_CONTRACT_VERSION } from '../contracts.js';
+import { listRuntimeArtifactPayloads, listRuntimeDurableGaps, listRuntimeFanInEvidenceSets, listRuntimeLlmAdvisorAssessments, listRuntimeSyncBackDecisions, recordRuntimeWorkflowGateDecision, runtimeScopedId, type RuntimeArtifactPayloadRecord } from '../storage/runtime-store.js';
+import { getEvidenceAttachmentPath } from '../runtime-paths.js';
+import { readAllRunStates } from '../run-state/run-state.js';
+import { affectedFileConflictsForSelectedRuns } from '../workflow-state/affected-file-conflicts.js';
+import { resolveWorkflowState } from '../workflow-state/resolve.js';
+import { evaluateWorkflowGateHardChecks } from './hard-checks.js';
+import { synthesizeWorkflowGateDecision } from './policy.js';
+import type { WorkflowGateDecision, WorkflowGateDecisionKind, WorkflowGateEvidencePacket } from './types.js';
+
+export async function buildWorkflowGateEvidencePacket(projectRoot: string, input: { branch?: string | null; taskId?: string | null; runId?: string | null; decisionKind: WorkflowGateDecisionKind; waveRunId?: string | null; taskIds?: string[]; runIds?: string[]; evidenceRefs?: string[] }): Promise<WorkflowGateEvidencePacket> {
+  const workflow = await resolveWorkflowState(projectRoot, { branch: input.branch, branchSource: input.branch ? 'cli_option' : undefined, taskId: input.taskId ?? null });
+  const taskId = input.taskId ?? workflow.latestRun?.taskId ?? workflow.model.tasks[0]?.id ?? null;
+  const selection = taskId ? workflow.latestEligibleRunsByTask.find((candidate) => candidate.taskId === taskId) ?? null : null;
+  const runId = input.runId ?? selection?.selected?.runId ?? workflow.latestRun?.runId ?? null;
+  const scopedTaskIds = sortedUnique(input.taskIds ?? (taskId ? [taskId] : []));
+  const scopedLatestEligibleSelections = scopedTaskIds.length > 0
+    ? scopedTaskIds.map((scopedTaskId) => workflow.latestEligibleRunsByTask.find((candidate) => candidate.taskId === scopedTaskId) ?? emptyLatestEligibleSelection(workflow.branch, scopedTaskId))
+    : (selection ? [selection] : []);
+  const scopedRunIds = sortedUnique(input.runIds ?? scopedLatestEligibleSelections.flatMap((candidate) => candidate.selected ? [candidate.selected.runId] : []));
+  const workflowScope = {
+    waveRunId: input.waveRunId ?? null,
+    taskIds: scopedTaskIds,
+    runIds: scopedRunIds.length > 0 ? scopedRunIds : sortedUnique(runId ? [runId] : []),
+    evidenceRefs: sortedUnique(input.evidenceRefs ?? [])
+  };
+  const scopedTasks = workflowScope.taskIds.length > 0
+    ? workflow.model.tasks.filter((candidate) => workflowScope.taskIds.includes(candidate.id))
+    : workflow.model.tasks.filter((candidate) => candidate.id === taskId);
+  const runtimeInputs = await loadRuntimeGateInputs(projectRoot, workflow.branch, workflowScope.taskIds, workflowScope.runIds);
+  const scopedAffectedFileConflicts = await loadScopedAffectedFileConflicts(projectRoot, workflow.affectedFileConflicts, workflowScope.runIds);
+  const packetBase = {
+    packetId: runtimeScopedId(WORKFLOW_GATE_RUNTIME_CONTRACT_VERSION, workflow.branch, taskId ?? 'none', runId ?? 'none', input.decisionKind),
+    generatedAt: new Date().toISOString(),
+    decisionKind: input.decisionKind,
+    partition: workflow.branch,
+    taskId,
+    runId,
+    documents: workflow.documents,
+    latestEligibleSelection: selection,
+    latestEligibleSelections: scopedLatestEligibleSelections,
+    workflowScope,
+    runtimeHealth: runtimeInputs.runtimeHealth,
+    durableGaps: runtimeInputs.durableGaps,
+    dependencyBlockers: workflow.dependencyBlockers,
+    affectedFileConflicts: scopedAffectedFileConflicts,
+    syncBackDecision: runtimeInputs.syncBackDecisions[0] ?? null,
+    syncBackDecisions: runtimeInputs.syncBackDecisions,
+    fanInEvidenceSets: runtimeInputs.fanInEvidenceSets,
+    advisorAssessments: runtimeInputs.advisorAssessments,
+    canonicalEvidenceRefs: sortedUnique([...workflowScope.evidenceRefs, ...runtimeInputs.payloads.filter((payload) => payload.status === 'active').map((payload) => payload.logicalRef)]),
+    requiredArtifactRefs: sortedUnique(scopedTasks.flatMap((task) => task.requiredArtifacts)),
+    artifactPayloadHealth: await inspectArtifactPayloadHealth(projectRoot, runtimeInputs.payloads.filter((payload) => payload.status === 'active'))
+  };
+  return {
+    ...packetBase,
+    hardChecks: evaluateWorkflowGateHardChecks(packetBase)
+  };
+}
+
+function emptyLatestEligibleSelection(partition: string, taskId: string): WorkflowGateEvidencePacket['latestEligibleSelections'][number] {
+  return {
+    partition,
+    taskId,
+    selected: null,
+    candidates: [],
+    rejected: []
+  };
+}
+
+async function loadScopedAffectedFileConflicts(projectRoot: string, fallback: WorkflowGateEvidencePacket['affectedFileConflicts'], runIds: string[]): Promise<WorkflowGateEvidencePacket['affectedFileConflicts']> {
+  if (runIds.length === 0) {
+    return fallback;
+  }
+  const states = await readAllRunStates(projectRoot);
+  const selectedRuns = states.filter((state) => runIds.includes(state.runId));
+  return affectedFileConflictsForSelectedRuns(states, selectedRuns);
+}
+
+async function loadRuntimeGateInputs(projectRoot: string, partition: string, taskIds: string[], runIds: string[]): Promise<{
+  runtimeHealth: WorkflowGateEvidencePacket['runtimeHealth'];
+  durableGaps: WorkflowGateEvidencePacket['durableGaps'];
+  syncBackDecisions: NonNullable<WorkflowGateEvidencePacket['syncBackDecision']>[];
+  fanInEvidenceSets: WorkflowGateEvidencePacket['fanInEvidenceSets'];
+  advisorAssessments: WorkflowGateEvidencePacket['advisorAssessments'];
+  payloads: RuntimeArtifactPayloadRecord[];
+}> {
+  try {
+    const runtimeScopes = scopedRuntimeQueries(taskIds, runIds);
+    const [durableGapResults, syncBackDecisionResults, fanInEvidenceSetResults, advisorAssessmentResults, payloadResults] = await Promise.all([
+      Promise.all(runtimeScopes.map((scope) => listRuntimeDurableGaps(projectRoot, { partition, taskId: scope.taskId, runId: scope.runId, status: 'open_terminal' }))),
+      Promise.all(runIds.map((scopedRunId) => listRuntimeSyncBackDecisions(projectRoot, scopedRunId))),
+      Promise.all(runtimeScopes.map((scope) => listRuntimeFanInEvidenceSets(projectRoot, { partition, taskId: scope.taskId, runId: scope.runId }))),
+      Promise.all(runtimeScopes.map((scope) => listRuntimeLlmAdvisorAssessments(projectRoot, { partition, taskId: scope.taskId, runId: scope.runId }))),
+      Promise.all(runIds.map((scopedRunId) => listRuntimeArtifactPayloads(projectRoot, { runId: scopedRunId })))
+    ]);
+    return {
+      runtimeHealth: { status: 'ok', issues: [] },
+      durableGaps: uniqueBy(durableGapResults.flat(), (gap) => gap.gapId),
+      syncBackDecisions: uniqueBy(syncBackDecisionResults.flat(), (decision) => decision.decisionId),
+      fanInEvidenceSets: uniqueBy(fanInEvidenceSetResults.flat(), (evidenceSet) => evidenceSet.fanInId),
+      advisorAssessments: uniqueBy(advisorAssessmentResults.flat(), (assessment) => assessment.assessmentId),
+      payloads: uniqueBy(payloadResults.flat(), (payload) => payload.payloadId)
+    };
+  } catch (error) {
+    return {
+      runtimeHealth: { status: 'unavailable', issues: [messageFromError(error)] },
+      durableGaps: [],
+      syncBackDecisions: [],
+      fanInEvidenceSets: [],
+      advisorAssessments: [],
+      payloads: []
+    };
+  }
+}
+
+function scopedRuntimeQueries(taskIds: string[], runIds: string[]): Array<{ taskId: string | null; runId: string | null }> {
+  if (taskIds.length === 0 && runIds.length === 0) {
+    return [{ taskId: null, runId: null }];
+  }
+  if (taskIds.length === 0) {
+    return runIds.map((scopedRunId) => ({ taskId: null, runId: scopedRunId }));
+  }
+  if (runIds.length === 0) {
+    return taskIds.map((scopedTaskId) => ({ taskId: scopedTaskId, runId: null }));
+  }
+  return uniqueBy([
+    ...taskIds.flatMap((scopedTaskId) => runIds.map((scopedRunId) => ({ taskId: scopedTaskId, runId: scopedRunId }))),
+    ...taskIds.map((scopedTaskId) => ({ taskId: scopedTaskId, runId: null })),
+    ...runIds.map((scopedRunId) => ({ taskId: null, runId: scopedRunId }))
+  ], (scope) => `${scope.taskId ?? 'none'}:${scope.runId ?? 'none'}`);
+}
+
+function uniqueBy<T>(items: T[], keyOf: (item: T) => string): T[] {
+  const seen = new Set<string>();
+  return items.filter((item) => {
+    const key = keyOf(item);
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+}
+
+async function inspectArtifactPayloadHealth(projectRoot: string, payloads: RuntimeArtifactPayloadRecord[]): Promise<WorkflowGateEvidencePacket['artifactPayloadHealth']> {
+  return Promise.all(payloads.map(async (payload) => {
+    try {
+      const raw = await readFile(getEvidenceAttachmentPath(projectRoot, payload.branchSlug, payload.physicalPayloadPath), 'utf8');
+      const actualDigest = hashDocumentContent(raw);
+      return {
+        payloadId: payload.payloadId,
+        logicalRef: payload.logicalRef,
+        physicalPayloadPath: payload.physicalPayloadPath,
+        expectedDigest: payload.digest,
+        actualDigest,
+        status: actualDigest === payload.digest ? 'ok' as const : 'digest_drift' as const
+      };
+    } catch {
+      return {
+        payloadId: payload.payloadId,
+        logicalRef: payload.logicalRef,
+        physicalPayloadPath: payload.physicalPayloadPath,
+        expectedDigest: payload.digest,
+        actualDigest: null,
+        status: 'missing' as const
+      };
+    }
+  }));
+}
+
+function hashDocumentContent(raw: string): string {
+  return createHash('sha256').update(raw.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+}
+
+export async function evaluateAndRecordWorkflowGateDecision(projectRoot: string, input: { branch?: string | null; taskId?: string | null; runId?: string | null; decisionKind: WorkflowGateDecisionKind; waveRunId?: string | null; taskIds?: string[]; runIds?: string[]; evidenceRefs?: string[] }): Promise<{ packet: WorkflowGateEvidencePacket; decision: WorkflowGateDecision }> {
+  const packet = await buildWorkflowGateEvidencePacket(projectRoot, input);
+  const decision = synthesizeWorkflowGateDecision(packet);
+  try {
+    await recordRuntimeWorkflowGateDecision(projectRoot, decision);
+  } catch (error) {
+    if (packet.runtimeHealth.status === 'ok') {
+      throw error;
+    }
+  }
+  return { packet, decision };
+}
+function sortedUnique(values: string[]): string[] {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+function messageFromError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}