sdd-agent-platform 0.4.0 → 0.4.2

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 });
   }
@@ -31,9 +31,13 @@ test('writeVerifyContract creates task-derived verify contract', async () => {
 
     const written = await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
     const inspection = await inspectVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
-
     assert.equal(written.status, 'created');
     assert.match(written.content, /contract: sdd-verify-doc-v1/);
+    assert.doesNotMatch(written.content, /based_on_tasks_/);
+    assert.doesNotMatch(written.content, /created_at:/);
+    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,8 +51,89 @@ test('writeVerifyContract creates task-derived verify contract', async () => {
   }
 });
 
-test('inspectVerifyContract warns when verify document is stale', async () => {
-  const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-stale-'));
+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 matrix no longer mentions current tasks', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-task-drift-'));
   try {
     await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
     await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
@@ -57,9 +142,47 @@ 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'), false);
     assert.equal(inspection.issues.some((issue) => issue.field === 'tasks' && /T2/.test(issue.message)), true);
   } finally {
     await rm(root, { recursive: true, force: true });
   }
 });
+
+test('inspectVerifyContract ignores legacy based_on metadata', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-legacy-ignored-'));
+  try {
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const written = await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    const legacy = written.content.replace('author_role: verification-designer', 'based_on_tasks_contract_hash: legacy\nbased_on_tasks_hash: legacy\nauthor_role: verification-designer');
+    await writeFile(path.join(root, 'specs', 'feature', 'verify.md'), legacy, 'utf8');
+
+    const inspection = await inspectVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    assert.equal(inspection.status, 'PASS');
+    assert.equal(inspection.issues.some((issue) => issue.field === 'based_on_tasks_contract_hash'), false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('writeVerifyContract preserves current verify documents without based_on metadata', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-verify-contract-preserve-current-'));
+  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');
+
+    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.doesNotMatch(preserved.content, /based_on_tasks_/);
+    assert.equal(inspection.status, 'PASS');
+  } 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,21 +74,13 @@ export async function inspectVerifyContract(projectRoot: string, options: { bran
         action: 'Regenerate verify.md with sdd verifies write or update the frontmatter 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.`
-      });
-    }
     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.'
+        action: 'Regenerate verify.md with a verification-designer role before running sdd test <validation_unit_id-or-validation_text>.'
       });
     }
     const independentFromRoles = readDocumentList(raw, 'independent_from_roles');
@@ -100,6 +94,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 +122,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,
@@ -130,17 +134,21 @@ export async function inspectVerifyContract(projectRoot: string, options: { bran
 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 content = renderVerifyContractDocument(model);
   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 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');
@@ -153,17 +161,14 @@ export async function writeVerifyContract(projectRoot: string, options: { branch
   };
 }
 
-export function renderVerifyContractDocument(model: SddTaskModel, timestamp: string): string {
+export function renderVerifyContractDocument(model: SddTaskModel): string {
   return `---
 contract: ${VERIFY_DOCUMENT_CONTRACT_VERSION}
 version: 1.0.0
 branch: ${model.branch}
-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}
@@ -172,29 +177,111 @@ 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.
-- Reviewer and validator evidence must use run-relative artifacts/<file> paths.
-- Physical evidence files live under branch evidence .sdd/runs/<branchSlug>/evidence/artifacts/.
+- Reviewer and validator evidence must use .sdd/runs/<branch>/test/*.md or .sdd/runs/<branch>/do/*.md refs.
+- Physical evidence files live under branch stage evidence .sdd/runs/<branch>/<stage>/*.md.
 - 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.
+- Goal-level verification feeds runtime truth-alignment; normal workflow completion proceeds through test judgment, goal verification, 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 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)} |`;
 }

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/work-units/contracts.ts

@@ -4,7 +4,7 @@ import { WORK_UNIT_CONTRACT_VERSION } from '../contracts.js';
 export type WorkUnitType = 'main-agent' | 'co-main-agent' | 'subagent';
 export type WorkUnitStatus = 'pending' | 'running' | 'completed' | 'blocked' | 'failed' | 'cancelled';
 export type WorkUnitAuthority = 'stage-owner' | 'stage-contributor' | 'non-authoritative';
-export type WorkUnitRequiredBefore = 'stage-output' | 'handoff' | 'sync-back' | 'ship' | 'never';
+export type WorkUnitRequiredBefore = 'stage-output' | 'handoff' | 'ship' | 'never';
 
 export interface WorkUnit {
   contract: typeof WORK_UNIT_CONTRACT_VERSION;