sdd-agent-platform 0.4.0 → 0.4.2

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

@@ -0,0 +1,106 @@
+import { createHash } from 'node:crypto';
+import type { SddTask, SddTaskModel } from '../sdd-docs/task-parser.js';
+
+export type ValidationCacheUnsafeReason = 'env_unknown' | 'tool_version_unknown' | 'non_deterministic_command' | 'external_service_dependency' | 'source_closure_unknown';
+
+export interface ValidationCacheKeyInput {
+  branch: string;
+  model: SddTaskModel;
+  task: SddTask;
+  command: string;
+  argv: string[] | null;
+  shell: boolean;
+  validationScopeTaskIds: string[];
+  acceptanceRefs: string[];
+}
+
+export interface ValidationCachePlan {
+  cacheKey: string;
+  normalizedCommand: string;
+  cwd: string;
+  envFingerprint: string;
+  toolFingerprint: string;
+  verifyContractHash: string | null;
+  tasksContractHash: string | null;
+  sourceClosureHash: string;
+  targetClosureHash: string;
+  unsafeReasons: ValidationCacheUnsafeReason[];
+  eligible: boolean;
+}
+
+export function buildValidationCachePlan(input: ValidationCacheKeyInput): ValidationCachePlan {
+  const normalizedCommand = normalizeCommand(input.command, input.argv);
+  const envFingerprint = runtimeEnvFingerprint();
+  const toolFingerprint = runtimeToolFingerprint();
+  const sourceClosureHash = stableHash({
+    branch: input.branch,
+    sourceTaskIds: input.validationScopeTaskIds.slice().sort(),
+    spec: input.model.documents.specContractHash ?? input.model.documents.specHash ?? null,
+    plan: input.model.documents.planContractHash ?? input.model.documents.planHash ?? null,
+    tasks: input.model.documents.tasksContractHash ?? input.model.documents.tasksHash ?? null,
+    verify: input.model.documents.verifyContractHash ?? input.model.documents.verifyHash ?? null
+  });
+  const targetClosureHash = stableHash({
+    acceptanceRefs: input.acceptanceRefs.slice().sort(),
+    taskIds: input.validationScopeTaskIds.slice().sort()
+  });
+  const unsafeReasons = unsafeReasonsForCommand(input.command, input.task);
+  const cacheKey = stableHash({
+    contract: 'phase-8.26-validation-cache-key-v1',
+    command: normalizedCommand,
+    cwd: '.',
+    envFingerprint,
+    toolFingerprint,
+    verifyContractHash: input.model.documents.verifyContractHash ?? null,
+    tasksContractHash: input.model.documents.tasksContractHash ?? null,
+    sourceClosureHash,
+    targetClosureHash
+  });
+  return {
+    cacheKey,
+    normalizedCommand,
+    cwd: '.',
+    envFingerprint,
+    toolFingerprint,
+    verifyContractHash: input.model.documents.verifyContractHash ?? null,
+    tasksContractHash: input.model.documents.tasksContractHash ?? null,
+    sourceClosureHash,
+    targetClosureHash,
+    unsafeReasons,
+    eligible: unsafeReasons.length === 0
+  };
+}
+
+function unsafeReasonsForCommand(command: string, task: SddTask): ValidationCacheUnsafeReason[] {
+  const normalized = command.trim().toLowerCase();
+  const reasons: ValidationCacheUnsafeReason[] = [];
+  if (!normalized || task.affectedFiles.length === 0) {
+    reasons.push('source_closure_unknown');
+  }
+  if (/\b(date|time|random|uuid|sleep)\b/.test(normalized)) {
+    reasons.push('non_deterministic_command');
+  }
+  if (/\b(curl|wget|ssh|scp|docker\s+pull|npm\s+install|pnpm\s+install|yarn\s+install)\b|https?:\/\//.test(normalized)) {
+    reasons.push('external_service_dependency');
+  }
+  if (normalized.startsWith('manual:')) {
+    reasons.push('non_deterministic_command');
+  }
+  return [...new Set(reasons)];
+}
+
+function normalizeCommand(command: string, argv: string[] | null): string {
+  return argv ? JSON.stringify(argv) : command.trim().replace(/\s+/g, ' ');
+}
+
+function runtimeEnvFingerprint(): string {
+  return stableHash({ platform: process.platform, arch: process.arch, nodeEnv: process.env.NODE_ENV ?? null });
+}
+
+function runtimeToolFingerprint(): string {
+  return stableHash({ node: process.version });
+}
+
+function stableHash(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value), 'utf8').digest('hex');
+}

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

@@ -0,0 +1,383 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { evaluateAndRecordWorkflowGateDecision } from '../workflow-gate/evidence-packet.js';
+import { initProject } from '../config/init-project.js';
+import { writeBranchDocs } from '../test-support/fixtures.js';
+import { listRuntimeAcceptanceEvidenceMaps, listRuntimeTestSteps, listRuntimeValidationCacheUses, listRuntimeValidationEnvironmentSessions, listRuntimeValidationWaveRuns, listRuntimeWorkflowGateDecisions, recordRuntimeDurableGap } from '../storage/runtime-store.js';
+import { readRunState, writeRunState } from '../run-state/run-state.js';
+import { readTaskEvidenceView } from '../run-state/task-evidence.js';
+import { writeVerifyContract } from './verify-contract.js';
+import { planValidationWave, renderValidationWaveResult, runValidationWave } from './validation-wave.js';
+import { evaluateLifecycleRiskDecisionForModel, recordLifecycleRiskDecisionProjection } from '../risk.js';
+import { parseSddBranch } from '../sdd-docs/task-parser.js';
+
+function taskMarkdown(taskId: string, command: string, wave: number): string {
+  return `### ${taskId}: Validation wave task
+
+\`\`\`sdd-task
+id: ${taskId}
+status: pending
+wave: ${wave}
+depends_on: []
+acceptance_refs:
+  - AC-${taskId}
+plan_refs:
+  - "§4 Target Design Overview"
+affected_files:
+  - docs/${taskId.toLowerCase()}.md
+validation:
+  - ${command} => AC-${taskId}
+risk: []
+\`\`\`
+
+#### Boundary
+
+Stay in validation fixtures.
+
+#### Acceptance
+
+- AC-${taskId}: Validation evidence is mapped.
+`;
+}
+
+function batchTaskMarkdown(taskId: string, command: string, batchId: string): string {
+  return `### ${taskId}: Batch validation task
+
+\`\`\`sdd-task
+id: ${taskId}
+status: pending
+wave: 1
+depends_on: []
+acceptance_refs:
+  - AC-${taskId}
+plan_refs:
+  - "§4 Target Design Overview"
+affected_files:
+  - docs/${taskId.toLowerCase()}.md
+change_surface: docs_only
+implementation_wave: docs-wave-1
+validation_batch: ${batchId}
+validation_timing: batch_end
+requires_verify_before_next: false
+validation:
+  - ${command} => AC-${taskId}
+risk: []
+\`\`\`
+
+#### Boundary
+
+Stay in validation fixtures.
+
+#### Acceptance
+
+- AC-${taskId}: Batch validation evidence is mapped.
+`;
+}
+
+test('validation wave plans multiple tasks from tasks and verify contracts', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-validation-wave-plan-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+${taskMarkdown('T1', 'node -e "process.stdout.write(\'one\')"', 1)}
+${taskMarkdown('T2', 'node -e "process.stdout.write(\'two\')"', 1)}`);
+    await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    const plan = await planValidationWave(root, { branch: 'feature', wave: 1 });
+
+    assert.equal(plan.status, 'READY');
+    assert.deepEqual(plan.taskIds, ['T1', 'T2']);
+    assert.deepEqual(plan.tasks.map((task) => task.acceptanceRefs[0]), ['AC-T1', 'AC-T2']);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('validation wave blocks explicitly requested tasks missing from verify batches', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-validation-wave-explicit-missing-verify-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+${batchTaskMarkdown('T1', 'node -e "process.stdout.write(\'one\')"', 'docs-batch-a')}
+${batchTaskMarkdown('T2', 'node -e "process.stdout.write(\'two\')"', 'docs-batch-b')}`);
+    await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    const verifyPath = path.join(root, 'specs', 'feature', 'verify.md');
+    await writeFile(verifyPath, (await readFile(verifyPath, 'utf8')).replace('      - "T2"', '      - "T-missing"'), 'utf8');
+
+    const plan = await planValidationWave(root, { branch: 'feature', taskIds: ['T1', 'T2'] });
+
+    assert.equal(plan.status, 'BLOCKED');
+    assert.deepEqual(plan.taskIds, ['T1']);
+    assert.match(plan.blockers.join('\n'), /Task T2 was requested but is not covered by verify\.md verification batches/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('validation batch plan consumes verify batch declarations', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-validation-batch-plan-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+${batchTaskMarkdown('T1', 'node -e "process.stdout.write(\'one\')"', 'docs-batch-a')}
+${batchTaskMarkdown('T2', 'node -e "process.stdout.write(\'two\')"', 'docs-batch-a')}
+${batchTaskMarkdown('T3', 'node -e "process.stdout.write(\'three\')"', 'docs-batch-b')}`);
+    await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    const plan = await planValidationWave(root, { branch: 'feature', batchId: 'docs-batch-a' });
+
+    assert.equal(plan.status, 'READY');
+    assert.equal(plan.batchId, 'docs-batch-a');
+    assert.deepEqual(plan.taskIds, ['T1', 'T2']);
+    assert.deepEqual(plan.verifyBatches.map((batch) => batch.id), ['docs-batch-a']);
+    assert.equal(plan.verifyBatches[0]?.timing, 'batch_end');
+    assert.deepEqual(plan.verifyBatches[0]?.checks, ['node -e "process.stdout.write(\'one\')"', 'node -e "process.stdout.write(\'two\')"']);
+    assert.deepEqual(plan.verifyBatches[0]?.acceptanceMapping, { T1: ['AC-T1'], T2: ['AC-T2'] });
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('validation batch plan blocks backend validation forbidden by verify batch', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-validation-batch-forbidden-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+${batchTaskMarkdown('T1', 'mvn test', 'frontend-batch').replace('change_surface: docs_only', 'change_surface: frontend_only')}`);
+    await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    const plan = await planValidationWave(root, { branch: 'feature', batchId: 'frontend-batch' });
+
+    assert.equal(plan.status, 'BLOCKED');
+    assert.equal(plan.verifyBatches[0]?.forbiddenValidation.includes('maven_compile'), true);
+    assert.equal(plan.blockers.some((blocker) => blocker.includes('backend build validation forbidden')), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('validation wave records shared environment session and acceptance maps', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-validation-wave-run-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+${taskMarkdown('T1', 'node -e "process.stdout.write(\'one\')"', 1)}
+${taskMarkdown('T2', 'node -e "process.stdout.write(\'two\')"', 1)}`);
+    await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    await seedLifecycleRiskDecision(root, 'feature');
+    const result = await runValidationWave(root, { branch: 'feature', wave: 1, approved: true });
+    const waves = await listRuntimeValidationWaveRuns(root, { partition: 'feature', waveRunId: result.waveRunId });
+    const sessions = await listRuntimeValidationEnvironmentSessions(root, { partition: 'feature', waveRunId: result.waveRunId });
+    const maps = await listRuntimeAcceptanceEvidenceMaps(root, { partition: 'feature', waveRunId: result.waveRunId });
+    const evidence = await readTaskEvidenceView(root, { branch: 'feature', taskId: 'T1' });
+
+    assert.equal(result.status, 'PASS');
+    assert.equal(result.taskResults.length, 2);
+    assert.equal(waves[0].environmentSessionId, result.environmentSessionId);
+    assert.equal(sessions[0].sessionId, result.environmentSessionId);
+    assert.equal(new Set(maps.map((map) => map.taskId)).size, 2);
+    assert.equal(maps.every((map) => map.status === 'complete'), true);
+    assert.match(renderValidationWaveResult(result), /acceptance_maps=2/);
+    assert.equal(evidence.validation.validationWaves.length, 1);
+    assert.equal(evidence.validation.environmentSessions.length, 1);
+    assert.equal(evidence.validation.acceptanceEvidenceMaps.some((map) => map.acceptanceRef === 'AC-T1'), true);
+    const workflowGateScope = (result.workflowGateDecision?.payload as { workflowScope?: { waveRunId: string | null; taskIds: string[]; runIds: string[]; evidenceRefs: string[] } } | undefined)?.workflowScope;
+    const wavePayloadScope = (waves[0].payload as { workflowScope?: unknown }).workflowScope as typeof workflowGateScope;
+    const gateDecisions = await listRuntimeWorkflowGateDecisions(root, { partition: 'feature', decisionKind: 'validation_wave' });
+    const expectedEvidenceRefs = result.taskResults.flatMap((taskResult) => [taskResult.validationArtifact].filter((ref): ref is string => Boolean(ref))).sort();
+
+    assert.equal(workflowGateScope?.waveRunId, result.waveRunId);
+    assert.deepEqual(workflowGateScope?.taskIds, ['T1', 'T2']);
+    assert.deepEqual(workflowGateScope?.runIds, result.taskResults.map((taskResult) => taskResult.runId).sort());
+    assert.deepEqual(workflowGateScope?.evidenceRefs, expectedEvidenceRefs);
+    assert.deepEqual(wavePayloadScope, workflowGateScope);
+    assert.equal(gateDecisions.some((decision) => decision.decisionId === result.workflowGateDecision?.decisionId), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('validation wave reuses identical deterministic validation command through cache', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-validation-wave-cache-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+${taskMarkdown('T1', 'node shared-cache-command.js', 1)}
+${taskMarkdown('T2', 'node shared-cache-command.js', 1)}`);
+    await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    const counterPath = path.join(root, 'validation-counter.txt');
+    const commandInput = { argv: [process.execPath, '-e', "const fs=require('fs'); const file=process.argv[1]; const count=fs.existsSync(file) ? Number(fs.readFileSync(file,'utf8')) : 0; fs.writeFileSync(file, String(count + 1)); process.stdout.write('ok');", counterPath] };
+
+    await seedLifecycleRiskDecision(root, 'feature');
+    const result = await runValidationWave(root, {
+      branch: 'feature',
+      wave: 1,
+      approved: true,
+      commandInputsByTask: { T1: [commandInput], T2: [commandInput] }
+    });
+    const steps = (await Promise.all(result.taskResults.map((taskResult) => listRuntimeTestSteps(root, { runId: taskResult.runId })))).flat();
+    const cacheUses = await listRuntimeValidationCacheUses(root, { branchSlug: 'feature' });
+
+    assert.equal(result.status, 'PASS');
+    assert.equal(await readFile(counterPath, 'utf8'), '1');
+    assert.equal(steps.some((step) => (step.payload as { cacheStatus?: string }).cacheStatus === 'miss'), true);
+    assert.equal(steps.some((step) => (step.payload as { cacheStatus?: string }).cacheStatus === 'hit'), true);
+    assert.equal(cacheUses.length, 1);
+    assert.deepEqual(cacheUses[0].mappedTaskIds, ['T2']);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('validation wave gate evaluates durable gaps across the whole wave', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-validation-wave-durable-gap-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+${taskMarkdown('T1', 'node -e "process.stdout.write(\'one\')"', 1)}
+${taskMarkdown('T2', 'node -e "process.stdout.write(\'two\')"', 1)}`);
+    await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    await seedLifecycleRiskDecision(root, 'feature');
+    const result = await runValidationWave(root, { branch: 'feature', wave: 1, approved: true });
+    const secondTask = result.taskResults.find((taskResult) => taskResult.taskId === 'T2');
+    assert.ok(result.workflowGateDecision);
+    assert.ok(secondTask);
+    await recordRuntimeDurableGap(root, {
+      gapId: 'gap-T2-blocking',
+      partition: 'feature',
+      taskId: 'T2',
+      runId: secondTask.runId,
+      stage: 'test',
+      gate: 'validation_wave',
+      source: 'runtime',
+      category: 'validation',
+      severity: 'blocking',
+      status: 'open',
+      message: 'Second task blocking gap should block the wave gate.',
+      recommendation: 'Resolve T2 before passing the wave.',
+      evidenceRefs: [],
+      proposalRefs: [],
+      sourceRefs: [],
+      payload: {}
+    });
+    await writeRunState(root, { ...await readRunState(root, secondTask.runId), status: 'blocked' });
+
+    const expectedEvidenceRefs = result.taskResults.flatMap((taskResult) => [taskResult.validationArtifact].filter((ref): ref is string => Boolean(ref)));
+    const { decision } = await evaluateAndRecordWorkflowGateDecision(root, {
+      branch: 'feature',
+      taskId: result.taskResults[0]?.taskId ?? null,
+      runId: result.taskResults[0]?.runId ?? null,
+      decisionKind: 'validation_wave',
+      waveRunId: result.waveRunId,
+      taskIds: result.plan.taskIds,
+      runIds: result.taskResults.map((taskResult) => taskResult.runId),
+      evidenceRefs: expectedEvidenceRefs
+    });
+
+    assert.equal(decision.status, 'BLOCKED');
+    assert.match(JSON.stringify(decision.hardBlocks), /durable_gap_blocking/);
+    assert.match(JSON.stringify(decision.hardBlocks), /gap-T2-blocking/);
+    assert.match(JSON.stringify(decision.hardBlocks), /run_rejected/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+
+test('validation wave blocks parser task gaps before command execution', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-validation-wave-task-gaps-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+${batchTaskMarkdown('T1', './mvnw test', 'frontend-batch').replace('affected_files:\n  - docs/t1.md', 'affected_files:\n  - app/src/main/webapp/index.jsp')}`);
+    await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    const result = await runValidationWave(root, { branch: 'feature', batchId: 'frontend-batch' });
+
+    assert.equal(result.status, 'BLOCKED');
+    assert.equal(result.taskResults.length, 0);
+    assert.match(result.gaps.join('\n'), /frontend-only but declares backend build validation/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('validation wave rerun preserves explicit wave boundary when selected tasks share a batch', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-validation-wave-rerun-wave-boundary-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+${batchTaskMarkdown('T1', 'node -e "process.stdout.write(\'one\')"', 'docs-batch-a')
+  .replace('validation_timing: batch_end', 'validation_timing: wave_end')
+  .replace('requires_verify_before_next: false', 'requires_verify_before_next: true')}`);
+    await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    const result = await runValidationWave(root, { branch: 'feature', wave: 1 });
+
+    assert.equal(result.status, 'BLOCKED');
+    assert.equal(result.plan.selectionBoundary, 'wave');
+    assert.equal(result.plan.batchId, 'docs-batch-a');
+    assert.match(result.next, /sdd test wave-1 --branch feature/);
+    assert.doesNotMatch(result.next, /sdd test batch docs-batch-a/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('validation wave uses verify acceptance mapping for runtime coverage', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-validation-wave-acceptance-mapping-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+${batchTaskMarkdown('T1', 'node -e "process.stdout.write(\'one\')"', 'docs-batch-a').replace('  - node -e "process.stdout.write(\'one\')" => AC-T1', '  - node -e "process.stdout.write(\'one\')"')}`);
+    await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+
+    await seedLifecycleRiskDecision(root, 'feature');
+    const result = await runValidationWave(root, { branch: 'feature', batchId: 'docs-batch-a', approved: true });
+
+    assert.equal(result.status, 'PASS');
+    assert.equal(result.acceptanceEvidence.some((map) => map.taskId === 'T1' && map.acceptanceRef === 'AC-T1' && map.status === 'complete'), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+async function seedLifecycleRiskDecision(root: string, branch: string): Promise<void> {
+  const model = await parseSddBranch(root, branch);
+  await recordLifecycleRiskDecisionProjection(root, evaluateLifecycleRiskDecisionForModel(branch, model));
+}
+
+test('validation wave blocks missing verify without generating runtime evidence', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-validation-wave-blocked-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+${taskMarkdown('T1', 'node -e "process.stdout.write(\'one\')"', 1)}`);
+
+    const result = await runValidationWave(root, { branch: 'feature', wave: 1 });
+
+    assert.equal(result.status, 'BLOCKED');
+    assert.equal(result.taskResults.length, 0);
+    assert.match(result.gaps.join('\n'), /verify\.md contract is BLOCKED/);
+    assert.match(result.next, /sdd test wave-1 --branch feature/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});