sdd-agent-platform 0.4.1 → 0.5.0

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

@@ -1,358 +1,334 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-import { VERIFY_DOCUMENT_CONTRACT_VERSION } from '../contracts.js';
-import { resolveSddContext, type ContextBranchSource } from '../sdd-docs/context.js';
-import { parseSddBranch, type SddTask, type SddTaskModel } from '../sdd-docs/task-parser.js';
-import { exists } from '../storage/json-io.js';
-
-export type VerifyContractStatus = 'PASS' | 'WARN' | 'BLOCKED';
-export type VerifyContractIssueLevel = 'WARN' | 'FAIL';
-export type VerifyContractAuthorRole = 'verification-designer';
-
-const VERIFY_CONTRACT_AUTHOR_ROLE: VerifyContractAuthorRole = 'verification-designer';
-const REQUIRED_INDEPENDENT_FROM_ROLES = ['task-planner', 'implementer'] as const;
-
-export interface VerifyContractIssue {
-  level: VerifyContractIssueLevel;
-  field: string;
-  message: string;
-  action: string;
-}
-
-export interface VerifyContractInspection {
-  contract: typeof VERIFY_DOCUMENT_CONTRACT_VERSION;
-  branch: string;
-  verifyPath: string;
-  exists: boolean;
-  status: VerifyContractStatus;
-  basedOnTasksHash: string | null;
-  currentTasksHash: string | null;
-  basedOnTasksContractHash: string | null;
-  currentTasksContractHash: string | null;
-  issues: VerifyContractIssue[];
-  taskCount: number;
-  authorRole: VerifyContractAuthorRole | null;
-  independentFromRoles: string[];
-}
-
-export interface WriteVerifyContractResult {
-  branch: string;
-  verifyPath: string;
-  relativePath: string;
-  status: 'created' | 'updated' | 'unchanged';
-  content: string;
-}
-
-export async function inspectVerifyContract(projectRoot: string, options: { branch?: string | null; branchSource?: ContextBranchSource } = {}): Promise<VerifyContractInspection> {
-  const context = await resolveSddContext(projectRoot, options);
-  const model = await parseSddBranch(projectRoot, context.partition);
-  const raw = model.documents.verifyExists ? await readFile(model.verifyPath, 'utf8') : null;
-  const issues: VerifyContractIssue[] = [];
-
-  if (!model.documents.tasksExists) {
-    issues.push({
-      level: 'FAIL',
-      field: 'tasks.md',
-      message: 'Cannot inspect verify.md because tasks.md is missing.',
-      action: 'Create specs/<branch>/tasks.md before generating verify.md.'
-    });
-  }
-
-  if (!model.documents.verifyExists || raw === null) {
-    issues.push({
-      level: 'FAIL',
-      field: 'verify.md',
-      message: 'Verification contract document is missing.',
-      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}`)) {
-      issues.push({
-        level: 'FAIL',
-        field: 'contract',
-        message: `verify.md does not declare contract ${VERIFY_DOCUMENT_CONTRACT_VERSION}.`,
-        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: 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');
-    if (authorRole !== VERIFY_CONTRACT_AUTHOR_ROLE) {
-      issues.push({
-        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 task.'
-      });
-    }
-    const independentFromRoles = readDocumentList(raw, 'independent_from_roles');
-    for (const role of REQUIRED_INDEPENDENT_FROM_ROLES) {
-      if (!independentFromRoles.includes(role)) {
-        issues.push({
-          level: 'WARN',
-          field: 'independent_from_roles',
-          message: `verify.md must declare independence from ${role}.`,
-          action: 'Regenerate verify.md so task planning, verification design, and implementation are separated.'
-        });
-      }
-    }
-    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({
-          level: 'WARN',
-          field: 'tasks',
-          message: `verify.md does not mention task ${task.id}.`,
-          action: 'Refresh verify.md so every executable task has verification expectations.'
-        });
-      }
-    }
-  }
-
-  return {
-    contract: VERIFY_DOCUMENT_CONTRACT_VERSION,
-    branch: context.partition,
-    verifyPath: model.verifyPath,
-    exists: model.documents.verifyExists,
-    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,
-    independentFromRoles: raw ? readDocumentList(raw, 'independent_from_roles') : []
-  };
-}
-
-export async function writeVerifyContract(projectRoot: string, options: { branch?: string | null; branchSource?: ContextBranchSource; force?: boolean } = {}): Promise<WriteVerifyContractResult> {
-  const context = await resolveSddContext(projectRoot, options);
-  const model = await parseSddBranch(projectRoot, context.partition);
-  const content = renderVerifyContractDocument(model, new Date().toISOString());
-  const existed = await exists(model.verifyPath);
-  if (existed && !options.force) {
-    const current = await readFile(model.verifyPath, 'utf8');
-    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');
-  return {
-    branch: context.partition,
-    verifyPath: model.verifyPath,
-    relativePath: `specs/${context.partition}/verify.md`,
-    status: existed ? 'updated' : 'created',
-    content
-  };
-}
-
-export function renderVerifyContractDocument(model: SddTaskModel, timestamp: string): string {
-  return `---
-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:
-${REQUIRED_INDEPENDENT_FROM_ROLES.map((role) => `  - ${role}`).join('\n')}
-created_at: ${timestamp}
-updated_at: ${timestamp}
----
-
-# Verify Contract: ${model.branch}
-
-## 1. Purpose
-
-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. 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 |'}
-
-## 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.
-- Reviewer and validator evidence must use run-relative artifacts/<file> paths.
-- 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.
-- \`/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.
-
-## 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)} |`;
-}
-
-function cell(values: string[]): string {
-  return values.length > 0 ? values.join('<br>') : 'none';
-}
-
-function readDocumentScalar(raw: string, key: string): string | null {
-  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const match = raw.match(new RegExp(`^[^\\S\\r\\n]*(?:-[^\\S\\r\\n]*)?${escapedKey}:[^\\S\\r\\n]*(.+?)[^\\S\\r\\n]*$`, 'm'));
-  return match ? cleanDocumentValue(match[1]) : null;
-}
-
-function readDocumentList(raw: string, key: string): string[] {
-  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const scalar = readDocumentScalar(raw, key);
-  if (scalar && scalar !== '[]') {
-    if (scalar.startsWith('[') && scalar.endsWith(']')) {
-      return scalar.slice(1, -1).split(',').map(cleanDocumentValue).filter(Boolean);
-    }
-    return [scalar];
-  }
-
-  const lines = raw.split(/\r?\n/);
-  const start = lines.findIndex((line) => new RegExp(`^\\s*${escapedKey}:\\s*$`).test(line));
-  if (start === -1) {
-    return [];
-  }
-
-  const values: string[] = [];
-  for (const line of lines.slice(start + 1)) {
-    if (/^\S/.test(line) || /^---\s*$/.test(line)) {
-      break;
-    }
-    const item = line.trim().match(/^-\s+(.+)$/)?.[1];
-    if (item) {
-      values.push(cleanDocumentValue(item));
-    }
-  }
-  return values;
-}
-
-function cleanDocumentValue(value: string): string {
-  return value.trim().replace(/^["'`]|["'`]$/g, '');
-}
-
-function escapeRegex(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { VERIFY_DOCUMENT_CONTRACT_VERSION } from '../contracts.js';
+import { resolveSddContext, type ContextBranchSource } from '../sdd-docs/context.js';
+import { parseSddBranch, type SddTask, type SddTaskModel } from '../sdd-docs/task-parser.js';
+import { exists } from '../storage/json-io.js';
+
+export type VerifyContractStatus = 'PASS' | 'WARN' | 'BLOCKED';
+export type VerifyContractIssueLevel = 'WARN' | 'FAIL';
+export type VerifyContractAuthorRole = 'verification-designer';
+
+const VERIFY_CONTRACT_AUTHOR_ROLE: VerifyContractAuthorRole = 'verification-designer';
+const REQUIRED_INDEPENDENT_FROM_ROLES = ['task-planner', 'implementer'] as const;
+
+export interface VerifyContractIssue {
+  level: VerifyContractIssueLevel;
+  field: string;
+  message: string;
+  action: string;
+}
+
+export interface VerifyContractInspection {
+  contract: typeof VERIFY_DOCUMENT_CONTRACT_VERSION;
+  branch: string;
+  verifyPath: string;
+  exists: boolean;
+  status: VerifyContractStatus;
+  basedOnTasksHash: string | null;
+  currentTasksHash: string | null;
+  basedOnTasksContractHash: string | null;
+  currentTasksContractHash: string | null;
+  issues: VerifyContractIssue[];
+  taskCount: number;
+  authorRole: VerifyContractAuthorRole | null;
+  independentFromRoles: string[];
+}
+
+export interface WriteVerifyContractResult {
+  branch: string;
+  verifyPath: string;
+  relativePath: string;
+  status: 'created' | 'updated' | 'unchanged';
+  content: string;
+}
+
+export async function inspectVerifyContract(projectRoot: string, options: { branch?: string | null; branchSource?: ContextBranchSource } = {}): Promise<VerifyContractInspection> {
+  const context = await resolveSddContext(projectRoot, options);
+  const model = await parseSddBranch(projectRoot, context.partition);
+  const raw = model.documents.verifyExists ? await readFile(model.verifyPath, 'utf8') : null;
+  const issues: VerifyContractIssue[] = [];
+
+  if (!model.documents.tasksExists) {
+    issues.push({
+      level: 'FAIL',
+      field: 'tasks.md',
+      message: 'Cannot inspect verify.md because tasks.md is missing.',
+      action: 'Create specs/<branch>/tasks.md before generating verify.md.'
+    });
+  }
+
+  if (!model.documents.verifyExists || raw === null) {
+    issues.push({
+      level: 'FAIL',
+      field: 'verify.md',
+      message: 'Verification contract document is missing.',
+      action: `Run /sdd:tasks or sdd tasks close --branch ${context.partition} --json to create specs/${context.partition}/verify.md before execute validation.`
+    });
+  } else {
+    if (!raw.includes(`contract: ${VERIFY_DOCUMENT_CONTRACT_VERSION}`)) {
+      issues.push({
+        level: 'FAIL',
+        field: 'contract',
+        message: `verify.md does not declare contract ${VERIFY_DOCUMENT_CONTRACT_VERSION}.`,
+        action: 'Regenerate verify.md through sdd tasks close or update the frontmatter contract.'
+      });
+    }
+    const authorRole = readDocumentScalar(raw, 'author_role');
+    if (authorRole !== VERIFY_CONTRACT_AUTHOR_ROLE) {
+      issues.push({
+        level: 'WARN',
+        field: 'author_role',
+        message: `verify.md must be owned by ${VERIFY_CONTRACT_AUTHOR_ROLE}, not ${authorRole ?? 'missing'}.`,
+        action: 'Route verification-design gaps back into tasks.md or execute lane evidence before running sdd execute.'
+      });
+    }
+    const independentFromRoles = readDocumentList(raw, 'independent_from_roles');
+    for (const role of REQUIRED_INDEPENDENT_FROM_ROLES) {
+      if (!independentFromRoles.includes(role)) {
+        issues.push({
+          level: 'WARN',
+          field: 'independent_from_roles',
+          message: `verify.md must declare independence from ${role}.`,
+          action: 'Regenerate verify.md so task planning, verification design, and implementation are separated.'
+        });
+      }
+    }
+    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 tasks close --branch ${context.partition} --json 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({
+          level: 'WARN',
+          field: 'tasks',
+          message: `verify.md does not mention task ${task.id}.`,
+          action: 'Refresh verify.md so every executable task has verification expectations.'
+        });
+      }
+    }
+  }
+
+  return {
+    contract: VERIFY_DOCUMENT_CONTRACT_VERSION,
+    branch: context.partition,
+    verifyPath: model.verifyPath,
+    exists: model.documents.verifyExists,
+    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,
+    independentFromRoles: raw ? readDocumentList(raw, 'independent_from_roles') : []
+  };
+}
+
+export async function writeVerifyContract(projectRoot: string, options: { branch?: string | null; branchSource?: ContextBranchSource; force?: boolean } = {}): Promise<WriteVerifyContractResult> {
+  const context = await resolveSddContext(projectRoot, options);
+  const model = await parseSddBranch(projectRoot, context.partition);
+  const content = renderVerifyContractDocument(model);
+  const existed = await exists(model.verifyPath);
+  if (existed && !options.force) {
+    const current = await readFile(model.verifyPath, 'utf8');
+    const hasCurrentBatchPlan = /^verification_batches:\s*$/m.test(current);
+    const hasCurrentContract = current.includes(`contract: ${VERIFY_DOCUMENT_CONTRACT_VERSION}`);
+    if (current === content || (hasCurrentContract && 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');
+  return {
+    branch: context.partition,
+    verifyPath: model.verifyPath,
+    relativePath: `specs/${context.partition}/verify.md`,
+    status: existed ? 'updated' : 'created',
+    content
+  };
+}
+
+export function renderVerifyContractDocument(model: SddTaskModel): string {
+  return `---
+contract: ${VERIFY_DOCUMENT_CONTRACT_VERSION}
+version: 1.0.0
+branch: ${model.branch}
+author_role: ${VERIFY_CONTRACT_AUTHOR_ROLE}
+independent_from_roles:
+${REQUIRED_INDEPENDENT_FROM_ROLES.map((role) => `  - ${role}`).join('\n')}
+---
+
+# Verify Contract: ${model.branch}
+
+## 1. Purpose
+
+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. 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 |'}
+
+## 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 task evidence judgment.
+- Reviewer and validator evidence must use .sdd/runs/<branch>/execute/*.md refs.
+- Physical evidence files live under branch stage evidence .sdd/runs/<branch>/<stage>/*.md.
+- Execute evidence judgment 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.
+- The execute validation lane consumes this contract and must not create or refresh it.
+- Execute evidence judgment feeds runtime truth-alignment; normal workflow completion proceeds through execute judgment and ship readiness.
+
+## 5. Out of Scope
+
+- This document does not replace runtime.sqlite, branch stage evidence artifacts, validator reports, or truth-alignment projections.
+- 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)} |`;
+}
+
+function cell(values: string[]): string {
+  return values.length > 0 ? values.join('<br>') : 'none';
+}
+
+function readDocumentScalar(raw: string, key: string): string | null {
+  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = raw.match(new RegExp(`^[^\\S\\r\\n]*(?:-[^\\S\\r\\n]*)?${escapedKey}:[^\\S\\r\\n]*(.+?)[^\\S\\r\\n]*$`, 'm'));
+  return match ? cleanDocumentValue(match[1]) : null;
+}
+
+function readDocumentList(raw: string, key: string): string[] {
+  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const scalar = readDocumentScalar(raw, key);
+  if (scalar && scalar !== '[]') {
+    if (scalar.startsWith('[') && scalar.endsWith(']')) {
+      return scalar.slice(1, -1).split(',').map(cleanDocumentValue).filter(Boolean);
+    }
+    return [scalar];
+  }
+
+  const lines = raw.split(/\r?\n/);
+  const start = lines.findIndex((line) => new RegExp(`^\\s*${escapedKey}:\\s*$`).test(line));
+  if (start === -1) {
+    return [];
+  }
+
+  const values: string[] = [];
+  for (const line of lines.slice(start + 1)) {
+    if (/^\S/.test(line) || /^---\s*$/.test(line)) {
+      break;
+    }
+    const item = line.trim().match(/^-\s+(.+)$/)?.[1];
+    if (item) {
+      values.push(cleanDocumentValue(item));
+    }
+  }
+  return values;
+}
+
+function cleanDocumentValue(value: string): string {
+  return value.trim().replace(/^["'`]|["'`]$/g, '');
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}