sdd-agent-platform 0.4.0 → 0.4.2

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

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
 import {
   ACCEPTANCE_POLICY_RULESET_VERSION,
   SDD_EVIDENCE_CONTRACT,
@@ -6,12 +7,12 @@ import {
   SDD_RESULT_CONTRACT,
   SDD_RESULT_VERSION
 } from '../contracts.js';
-import { artifactKind, readArtifact, writeArtifact } from '../run-state/artifacts.js';
+import { artifactKind, readArtifact, recordRuntimeOnlyArtifact } from '../run-state/artifacts.js';
 import { appendEvent } from '../run-state/events.js';
 import { appendArtifactHashLedgerEntry, appendDeclaredCommandLedgerEntries, appendInvocationLedgerEntry, listInvocationLedgerEntries } from '../run-state/invocation-ledger.js';
-import type { InvocationLedgerEntry, InvocationLedgerKind, RunState } from '../run-state/model.js';
+import type { InvocationLedgerEntry, InvocationLedgerKind, RunState, RunStateTaskRuntime } from '../run-state/model.js';
 import { readRunState, writeRunState } from '../run-state/run-state.js';
-import { toArtifactRootRelativePath } from '../runtime-paths.js';
+import { getBranchStageEvidencePathFromRef, isBranchStageEvidenceRef, toBranchStageEvidenceRef, toEvidencePayloadFileName } from '../runtime-paths.js';
 import { hasRuntimeEvidenceScopeViolation, readRuntimeEvidenceClaims } from '../context/evidence-summary.js';
 import type { ArtifactTrustValidationReport, EvidenceClaim, EvidenceCoverageStatus, EvidenceQualityIssue } from '../artifacts/sdd-evidence.js';
 import { validateSddResultArtifact } from '../artifacts/sdd-result.js';
@@ -19,7 +20,7 @@ import type { SddResultStatus } from '../artifacts/sdd-result.js';
 import { taskGap } from '../sdd-docs/task-inspection.js';
 import { inspectSddTask } from '../sdd-docs/task-inspection.js';
 import type { SddTask, SddTaskGap } from '../sdd-docs/task-parser.js';
-import { resolveTaskRun } from '../sync-back/inspect.js';
+import { resolveTaskRun } from '../workflow-state/resolve-task-run.js';
 
 export type GoalVerifyStatus = 'PASS' | 'PASS_WITH_GAPS' | 'FAIL' | 'BLOCKED';
 export type HarnessVerifyStatus = 'PASS' | 'GAPS' | 'BLOCKED' | 'HUMAN_NEEDED';
@@ -62,7 +63,6 @@ export interface GoalVerifyResult {
   reviewArtifact: string | null;
   validationArtifact: string | null;
   coverageArtifactPath: string;
-  syncBackProposalPath: string;
   acceptanceCoverage: AcceptanceCoverageItem[];
   gaps: SddTaskGap[];
   commands: string[];
@@ -114,7 +114,7 @@ export async function runGoalVerify(projectRoot: string, options: GoalVerifyOpti
   }
 
   if (!reviewArtifact) {
-    gaps.push(taskGap(options.taskId, 'review_artifact', 'No reviewer artifact was supplied or found in run state.', 'Run review first or pass --review-artifact artifacts/<file>.'));
+    gaps.push(taskGap(options.taskId, 'review_artifact', 'No reviewer evidence was supplied or selected from runtime state.', 'Author reviewer evidence under .sdd/runs/<branch>/do/code-review-vN.md and register its ref/hash before goal-level verify.'));
   } else {
     const reviewReport = await validateSddResultArtifact(projectRoot, runId, reviewArtifact, { expectedTask: options.taskId, expectedAgent: 'reviewer' });
     if (!reviewReport.valid || !reviewReport.result) {
@@ -129,7 +129,7 @@ export async function runGoalVerify(projectRoot: string, options: GoalVerifyOpti
   }
 
   if (!validationArtifact) {
-    gaps.push(taskGap(options.taskId, 'validation_artifact', 'No validator artifact was supplied or found in run state.', 'Run validation first or pass --validation-artifact artifacts/<file>.'));
+    gaps.push(taskGap(options.taskId, 'validation_artifact', 'No validator evidence was supplied or selected from runtime state.', 'Author validator evidence under .sdd/runs/<branch>/test/validation-vN.md and register its ref/hash before goal-level verify.'));
   } else {
     const validationReport = await validateSddResultArtifact(projectRoot, runId, validationArtifact, { expectedTask: options.taskId, expectedAgent: 'validator' });
     validationTrust = validationReport.trust ?? null;
@@ -197,31 +197,24 @@ export async function runGoalVerify(projectRoot: string, options: GoalVerifyOpti
 
   const status = deriveGoalVerifyStatus(reviewStatus, validationStatus, gaps);
   const standardStatus = toHarnessVerifyStatus(status, reviewStatus, validationStatus, gaps);
-  const coverageArtifact = await writeArtifact(projectRoot, runId, `acceptance-coverage-${options.taskId}.md`, renderAcceptanceCoverageArtifact(options.taskId, status, inspected.task, reviewArtifact, validationArtifact, acceptanceCoverage, gaps, executedCommands));
-  const allArtifacts = [...acceptedArtifacts, coverageArtifact.runRelativePath];
-  const proposal = await writeSyncBackProposal(projectRoot, runId, options.taskId, status === 'PASS' ? 'verified' : 'blocked', allArtifacts, gaps, status === 'PASS' ? 'Goal-level verify mapped validator evidence to all acceptance items.' : 'Goal-level verify found gaps; sync-back is a verification gap proposal, not task completion.');
+  const coverageFileName = `acceptance-coverage-${options.taskId}.md`;
+  const coverageRef = toBranchStageEvidenceRef(branch, 'goal-verify', coverageFileName);
+  await recordRuntimeOnlyArtifact(projectRoot, runId, coverageFileName, renderAcceptanceCoverageArtifact(options.taskId, status, coverageRef, inspected.task, reviewArtifact, validationArtifact, acceptanceCoverage, gaps, executedCommands), { logicalRef: coverageRef, branch, taskId: options.taskId, artifactRole: 'goal-verify-acceptance-coverage' });
+  const allArtifacts = [...acceptedArtifacts, coverageRef];
 
   await persistVerifyState(projectRoot, runId, {
     status,
     taskId: options.taskId,
-    taskState: { status: status === 'PASS' ? 'verified' : 'blocked', verifyStatus: status, gaps, artifacts: allArtifacts, acceptanceCoverage },
+    taskState: buildGoalVerifyTaskState(inspected.task, status, gaps, allArtifacts, acceptanceCoverage),
     commands: plannedCommands,
     evidence: allArtifacts,
-    syncBackProposalPath: proposal.runRelativePath,
-    syncBackProposalDigest: proposal.digest,
     artifacts: allArtifacts.map((artifactPath) => ({ path: artifactPath, kind: artifactKind(artifactPath), task: options.taskId, agent: agentFromArtifactPath(artifactPath) }))
   });
   await appendEvent(projectRoot, runId, {
     event: status === 'PASS' ? 'validation_passed' : 'validation_failed',
     runId,
     summary: `Phase 1.9 goal-level verify ${status} for ${options.taskId}`,
-    data: { task: options.taskId, status, coverageArtifact: coverageArtifact.runRelativePath, gaps, plannedCommands, executedCommands }
-  });
-  await appendEvent(projectRoot, runId, {
-    event: 'sync_back_proposed',
-    runId,
-    summary: `Verify sync-back proposal created for ${options.taskId}`,
-    data: { proposal: proposal.runRelativePath, status }
+    data: { task: options.taskId, status, coverageArtifact: coverageRef, gaps, plannedCommands, executedCommands }
   });
 
   return {
@@ -231,26 +224,39 @@ export async function runGoalVerify(projectRoot: string, options: GoalVerifyOpti
     task: inspected.task,
     reviewArtifact,
     validationArtifact,
-    coverageArtifactPath: coverageArtifact.runRelativePath,
-    syncBackProposalPath: proposal.runRelativePath,
+    coverageArtifactPath: coverageRef,
     acceptanceCoverage,
     gaps,
     commands: plannedCommands,
     plannedCommands,
     executedCommands,
     standardStatus,
-    message: status === 'PASS' ? 'Goal-level verify passed with explicit acceptance coverage.' : 'Goal-level verify found gaps; inspect coverage artifact and sync-back proposal.'
+    message: status === 'PASS' ? 'Goal-level verify passed with explicit acceptance coverage.' : 'Goal-level verify found gaps; inspect coverage artifact.'
+  };
+}
+
+function buildGoalVerifyTaskState(task: SddTask | null, status: GoalVerifyStatus, gaps: SddTaskGap[], artifacts: string[], acceptanceCoverage: unknown[]): RunStateTaskRuntime {
+  const verificationStatus = status === 'PASS' ? 'pass' : status === 'PASS_WITH_GAPS' ? 'pass_with_gaps' : status === 'FAIL' ? 'failed' : 'blocked';
+  return {
+    status: status === 'PASS' ? 'implemented_verified' : verificationStatus === 'pass_with_gaps' ? 'validation_blocked' : verificationStatus === 'failed' ? 'validation_failed' : 'validation_blocked',
+    implementationStatus: 'implemented',
+    verificationStatus,
+    validationBatch: task?.validationBatch ?? null,
+    validationTiming: task?.validationTiming ?? 'task_end',
+    requiresVerifyBeforeNext: task?.requiresVerifyBeforeNext ?? true,
+    verifyStatus: status,
+    gaps,
+    artifacts,
+    acceptanceCoverage
   };
 }
 
 async function persistVerifyState(projectRoot: string, runId: string, input: {
   status: GoalVerifyStatus;
   taskId: string;
-  taskState: unknown;
+  taskState: RunStateTaskRuntime;
   commands: string[];
   evidence: string[];
-  syncBackProposalPath: string;
-  syncBackProposalDigest: string;
   artifacts: Array<{ path: string; kind: string; task: string; agent: string }>;
 }): Promise<void> {
   const state = await readRunState(projectRoot, runId);
@@ -274,24 +280,12 @@ async function persistVerifyState(projectRoot: string, runId: string, input: {
       commands: input.commands,
       evidence: input.evidence
     },
-    syncBack: {
-      mode: 'proposal',
-      proposalPath: input.syncBackProposalPath,
-      proposalDigest: input.syncBackProposalDigest,
-      sourceVerifyStatus: input.status,
-      status: state.syncBack.status === 'applied' ? 'applied' : 'proposed'
-    }
   });
 }
 
-async function writeSyncBackProposal(projectRoot: string, runId: string, taskId: string, status: string, artifacts: string[], gaps: SddTaskGap[], summary: string): Promise<{ absolutePath: string; runRelativePath: string; digest: string }> {
-  const content = `# Sync-back Proposal\n\n## ${taskId}\n\n- status: ${status}\n- summary: ${summary}\n- artifacts:\n${artifacts.length > 0 ? artifacts.map((artifact) => `  - ${artifact}`).join('\n') : '  - none'}\n- gaps:\n${gaps.length > 0 ? gaps.map((gap) => `  - [${gap.severity}] ${gap.type} ${gap.field}: ${gap.message}`).join('\n') : '  - none'}\n\n## Boundaries\n\n- Proposal only; tasks.md/spec.md/plan.md were not modified by runtime.\n- Runtime modeled agent/verify steps through supplied artifacts and contract validation; no external agent API was invoked.\n`;
-  const written = await writeArtifact(projectRoot, runId, 'sync-back-proposal.md', content);
-  return { ...written, digest: hashDocumentContent(content) };
-}
 
-function renderAcceptanceCoverageArtifact(taskId: string, status: GoalVerifyStatus, task: SddTask | null, reviewArtifact: string | null, validationArtifact: string | null, coverage: AcceptanceCoverageItem[], gaps: SddTaskGap[], executedCommands: string[]): string {
-  return `# Acceptance Coverage ${taskId}\n\n\`\`\`sdd-result\ncontract: ${SDD_RESULT_CONTRACT}\nversion: ${SDD_RESULT_VERSION}\nagent: validator\ntask: ${taskId}\nstatus: ${status}\nartifacts:\n  - artifacts/acceptance-coverage-${taskId}.md\n\`\`\`\n\n## Source Evidence\n\n- review_artifact: ${reviewArtifact ?? 'missing'}\n- validation_artifact: ${validationArtifact ?? 'missing'}\n- task_source: ${task ? sourceLocationEvidence(task.source) : 'missing'}\n\n## Planned Validation Commands\n\n${task && task.validation.length > 0 ? task.validation.map((command) => `- ${command}`).join('\n') : '- none'}\n\n## Executed Runtime Commands\n\n${executedCommands.length > 0 ? executedCommands.map((command) => `- ${command}`).join('\n') : '- none'}\n\n## Acceptance Mapping\n\n${coverage.length > 0 ? coverage.map((item) => `- [${item.status}] ${item.acceptance} Evidence: ${item.evidence}`).join('\n') : '- No acceptance items available.'}\n\n## Policy Decisions\n\n${coverage.length > 0 ? coverage.map((item) => `- ${item.acceptance}: status=${item.policyDecision?.status ?? item.status}; ruleset=${item.policyDecision?.ruleSet.id ?? ACCEPTANCE_POLICY_RULESET_VERSION}; passed=${item.policyDecision?.passedRules.join(',') || 'none'}; failed=${item.policyDecision?.failedRules.join(',') || 'none'}; issues=${item.issueCodes?.join(',') || 'none'}`).join('\n') : '- none'}\n\n## Gaps\n\n${gaps.length > 0 ? gaps.map((gap) => `- [${gap.severity}] ${gap.type} ${gap.field}: ${gap.message} Recommendation: ${gap.recommendation}`).join('\n') : '- none'}\n`;
+function renderAcceptanceCoverageArtifact(taskId: string, status: GoalVerifyStatus, coverageRef: string, task: SddTask | null, reviewArtifact: string | null, validationArtifact: string | null, coverage: AcceptanceCoverageItem[], gaps: SddTaskGap[], executedCommands: string[]): string {
+  return `# Acceptance Coverage ${taskId}\n\n\`\`\`sdd-result\ncontract: ${SDD_RESULT_CONTRACT}\nversion: ${SDD_RESULT_VERSION}\nagent: validator\ntask: ${taskId}\nstatus: ${status}\nartifacts:\n  - ${coverageRef}\n\`\`\`\n\n## Source Evidence\n\n- review_artifact: ${reviewArtifact ?? 'missing'}\n- validation_artifact: ${validationArtifact ?? 'missing'}\n- task_source: ${task ? sourceLocationEvidence(task.source) : 'missing'}\n\n## Planned Validation Commands\n\n${task && task.validation.length > 0 ? task.validation.map((command) => `- ${command}`).join('\n') : '- none'}\n\n## Executed Runtime Commands\n\n${executedCommands.length > 0 ? executedCommands.map((command) => `- ${command}`).join('\n') : '- none'}\n\n## Acceptance Mapping\n\n${coverage.length > 0 ? coverage.map((item) => `- [${item.status}] ${item.acceptance} Evidence: ${item.evidence}`).join('\n') : '- No acceptance items available.'}\n\n## Policy Decisions\n\n${coverage.length > 0 ? coverage.map((item) => `- ${item.acceptance}: status=${item.policyDecision?.status ?? item.status}; ruleset=${item.policyDecision?.ruleSet.id ?? ACCEPTANCE_POLICY_RULESET_VERSION}; passed=${item.policyDecision?.passedRules.join(',') || 'none'}; failed=${item.policyDecision?.failedRules.join(',') || 'none'}; issues=${item.issueCodes?.join(',') || 'none'}`).join('\n') : '- none'}\n\n## Gaps\n\n${gaps.length > 0 ? gaps.map((gap) => `- [${gap.severity}] ${gap.type} ${gap.field}: ${gap.message} Recommendation: ${gap.recommendation}`).join('\n') : '- none'}\n`;
 }
 
 function evaluateAcceptanceCoverageTarget(target: AcceptanceCoverageTarget, input: { taskId: string; validationArtifact: string | null; validationRaw: string; claims: EvidenceClaim[]; validationStatus: SddResultStatus | null; invocationLedger: InvocationLedgerEntry[] }): AcceptanceCoverageItem {
@@ -465,6 +459,9 @@ function invocationLedgerRefs(entries: InvocationLedgerEntry[], kind: Invocation
       if (entry.artifactPath) {
         refs.add(entry.artifactPath);
       }
+      if (kind === 'command' && typeof entry.metadata.stepId === 'string') {
+        refs.add(entry.metadata.stepId);
+      }
     }
   }
   return refs;
@@ -558,7 +555,14 @@ function toHarnessVerifyStatus(status: GoalVerifyStatus, reviewStatus: SddResult
 
 async function readArtifactIfExists(projectRoot: string, runId: string, runRelativeArtifactPath: string): Promise<string> {
   try {
-    return await readArtifact(projectRoot, runId, toArtifactRootRelativePath(runRelativeArtifactPath));
+    if (isBranchStageEvidenceRef(runRelativeArtifactPath)) {
+      try {
+        return await readFile(getBranchStageEvidencePathFromRef(projectRoot, runRelativeArtifactPath), 'utf8');
+      } catch {
+        return await readArtifact(projectRoot, runId, toEvidencePayloadFileName(runRelativeArtifactPath));
+      }
+    }
+    return await readArtifact(projectRoot, runId, toEvidencePayloadFileName(runRelativeArtifactPath));
   } catch {
     return '';
   }
@@ -581,7 +585,7 @@ function agentFromArtifactPath(artifactPath: string): string {
   if (kind === 'review' || kind === 'validation' || kind === 'debug') {
     return kind === 'debug' ? 'debugger' : kind === 'review' ? 'reviewer' : 'validator';
   }
-  if (kind === 'gap-report' || kind === 'sync-back-proposal') {
+  if (kind === 'gap-report') {
     return 'runtime';
   }
   return 'unknown';

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

@@ -5,7 +5,6 @@ export type GoalVerifyStatus = 'PASS' | 'PASS_WITH_GAPS' | 'FAIL' | 'BLOCKED';
 export type HarnessVerifyStatus = 'PASS' | 'GAPS' | 'BLOCKED' | 'HUMAN_NEEDED';
 export type SingleTaskLoopStatus = 'completed' | 'blocked' | 'failed';
 
-type LoopAgent = 'implementer' | 'reviewer' | 'debugger' | 'validator';
 
 interface AcceptanceCoverageItemLike {
   acceptance: string;
@@ -22,7 +21,6 @@ export interface GoalVerifyResultLike {
   reviewArtifact: string | null;
   validationArtifact: string | null;
   coverageArtifactPath: string;
-  syncBackProposalPath: string;
   acceptanceCoverage: AcceptanceCoverageItemLike[];
   commands: string[];
   plannedCommands?: string[];
@@ -50,14 +48,12 @@ export interface SingleTaskLoopResultLike {
       costClass: string;
     };
   };
-  syncBackProposalPath: string | null;
   message: string;
 }
 
 export function renderGoalVerifyResult(result: GoalVerifyResultLike): string {
   const lines = ['SDD verify task result', 'changed'];
   lines.push(`- acceptance coverage written to ${result.coverageArtifactPath}`);
-  lines.push(`- sync-back proposal written to ${result.syncBackProposalPath}`);
   lines.push('decision');
   lines.push(`- status=${result.status}`);
   lines.push(`- standard_status=${result.standardStatus}`);
@@ -65,7 +61,7 @@ export function renderGoalVerifyResult(result: GoalVerifyResultLike): string {
   lines.push('evidence');
   lines.push(`- run=${result.runId}`);
   lines.push(`- task=${result.taskId}`);
-  lines.push('- artifact_path_scope=CLI flags use run-relative artifacts/<file>; physical files live under branch evidence .sdd/runs/<branchSlug>/evidence/artifacts/<file>');
+  lines.push('- artifact_path_scope=goal-verify consumes accepted runtime evidence refs; runtime writes runtime.sqlite only');
   lines.push(`- review_artifact=${result.reviewArtifact ?? 'none'}`);
   lines.push(`- validation_artifact=${result.validationArtifact ?? 'none'}`);
   lines.push(`- planned_commands=${(result.plannedCommands ?? result.commands).join(', ') || 'none'}`);
@@ -85,9 +81,10 @@ export function renderGoalVerifyResult(result: GoalVerifyResultLike): string {
   }
   lines.push('next');
   if (result.status === 'PASS') {
-    lines.push(`- sdd sync-back inspect ${result.runId} --task ${result.taskId}`);
+    lines.push(`- sdd test task-${result.taskId} --run ${result.runId}`);
+    lines.push('- then follow truth-alignment and ship gate readiness.');
   } else {
-    lines.push(`- update review/validator artifacts and rerun sdd test task ${result.taskId} --run ${result.runId}`);
+    lines.push(`- update review/validator artifacts and rerun sdd test task-${result.taskId} --run ${result.runId}`);
   }
   return lines.join('\n');
 }
@@ -104,12 +101,11 @@ export function renderSingleTaskLoopResult(result: SingleTaskLoopResultLike): st
   lines.push(`- router category=${result.routeDecision.category} recommended_profile=${result.routeDecision.recommendedProfile ?? 'none'} autonomy=${result.routeDecision.autonomyCeiling}`);
   lines.push(`- team_mode=${result.routeDecision.teamMode.decision} mode=${result.routeDecision.teamMode.mode} activation=${result.routeDecision.teamMode.activation} cost=${result.routeDecision.teamMode.costClass}`);
   lines.push('evidence');
-  lines.push('- artifact_path_scope=CLI flags use run-relative artifacts/<file>; physical files live under branch evidence .sdd/runs/<branchSlug>/evidence/artifacts/<file>');
+  lines.push('- artifact_path_scope=agent-authored .sdd/runs/<branch>/do/*.md evidence; runtime reads frontmatter/hashes and writes runtime.sqlite only');
   lines.push(`- required_artifacts=${result.requiredArtifacts.join(',') || 'none'}`);
   lines.push(`- accepted_artifacts=${result.acceptedArtifacts.join(',') || 'none'}`);
-  lines.push(`- sync_back_proposal=${result.syncBackProposalPath || 'none'}`);
-  lines.push(`- agent_execution_records=.sdd/runs/${result.runId}/agent-executions/`);
-  lines.push(`- team_session_records=.sdd/runs/${result.runId}/team-sessions/`);
+  lines.push('- agent_execution_records=runtime.sqlite:agent_executions');
+  lines.push('- team_session_records=runtime.sqlite:team_sessions');
   lines.push('gaps');
   if (result.gaps.length === 0) {
     lines.push('- none');
@@ -118,54 +114,24 @@ export function renderSingleTaskLoopResult(result: SingleTaskLoopResultLike): st
   }
   lines.push('next');
   if (result.status === 'completed') {
-    lines.push(`- sdd test task ${result.taskId} --run ${result.runId}`);
+    if (result.task && !requiresImmediateValidation(result.task) && result.task.validationBatch) {
+      lines.push(`- sdd status --branch <branch> to select the next safe do task or validation boundary`);
+      lines.push(`- after all tasks in validation_batch ${result.task.validationBatch} are implemented, run sdd test ${result.task.validationBatch}`);
+    } else {
+      lines.push(`- sdd test task-${result.taskId} --run ${result.runId}`);
+    }
   } else {
     const missingArtifacts = result.requiredArtifacts.filter((artifact) => !result.acceptedArtifacts.includes(artifact));
     if (missingArtifacts.length > 0) {
-      lines.push(`- create or validate missing run-relative artifacts: ${missingArtifacts.join(', ')}`);
-      lines.push('- physical artifact files belong under branch evidence .sdd/runs/<branchSlug>/evidence/artifacts/');
-    }
-    const artifactFlags = missingArtifacts
-      .map((artifact) => ({ artifact, agent: agentForLoopArtifact(artifact) }))
-      .filter((item): item is { artifact: string; agent: LoopAgent } => Boolean(item.agent));
-    for (const item of artifactFlags) {
-      lines.push(`- sdd artifact template ${item.artifact} --task ${result.taskId} --agent ${item.agent} --run ${result.runId} --write`);
+      lines.push(`- write missing do-stage evidence: ${missingArtifacts.join(', ')}`);
+      lines.push('- runtime must not author Markdown artifacts for this entrypoint');
     }
-    const rerunFlags = artifactFlags.map((item) => `${artifactOptionName(item.agent)} ${item.artifact}`).join(' ');
-    lines.push(`- sdd do task ${result.taskId} --run ${result.runId}${rerunFlags ? ` ${rerunFlags}` : ''}`);
+    lines.push(`- sdd do task ${result.taskId} --run ${result.runId} --branch <branch>`);
   }
   return lines.join('\n');
 }
 
-function agentForLoopArtifact(artifactPath: string): LoopAgent | null {
-  const filename = artifactPath.replace(/\\/g, '/').split('/').pop() ?? '';
-  if (filename.startsWith('implement-')) {
-    return 'implementer';
-  }
-  if (filename.startsWith('review-')) {
-    return 'reviewer';
-  }
-  if (filename.startsWith('debug-')) {
-    return 'debugger';
-  }
-  if (filename.startsWith('validation-')) {
-    return 'validator';
-  }
-  return null;
+function requiresImmediateValidation(task: SddTask): boolean {
+  return task.requiresVerifyBeforeNext || task.validationTiming === 'task_end';
 }
 
-function artifactOptionName(agent: string): string {
-  if (agent === 'implementer') {
-    return '--implement-artifact';
-  }
-  if (agent === 'reviewer') {
-    return '--review-artifact';
-  }
-  if (agent === 'debugger') {
-    return '--debug-artifact';
-  }
-  if (agent === 'validator') {
-    return '--validation-artifact';
-  }
-  return '--artifact';
-}

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

@@ -0,0 +1,84 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { initProject } from '../config/init-project.js';
+import { listRuntimeWorkflowGateDecisions } from '../storage/runtime-store.js';
+import { writeBranchDocs } from '../test-support/fixtures.js';
+import { writeVerifyContract } from './verify-contract.js';
+import { runValidationWave } from './validation-wave.js';
+import { renderReviewGateResult, runReviewGate } from './review-gate.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}: Review gate 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 review gate fixtures.
+
+#### Acceptance
+
+- AC-${taskId}: Review gate evidence is mapped.
+`;
+}
+
+test('review gate records a workflow gate decision with whole-wave scope', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-review-gate-'));
+  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 wave = await runValidationWave(root, { branch: 'feature', wave: 1, approved: true });
+    const expectedEvidenceRefs = wave.taskResults.flatMap((taskResult) => [taskResult.validationArtifact].filter((ref): ref is string => Boolean(ref))).sort();
+    const result = await runReviewGate(root, {
+      branch: 'feature',
+      taskId: 'T1',
+      runId: wave.taskResults[0].runId,
+      waveRunId: wave.waveRunId,
+      taskIds: wave.plan.taskIds,
+      runIds: wave.taskResults.map((taskResult) => taskResult.runId),
+      evidenceRefs: expectedEvidenceRefs
+    });
+    const decisions = await listRuntimeWorkflowGateDecisions(root, { partition: 'feature', decisionKind: 'review_gate' });
+    const workflowGateScope = (result.workflowGateDecision.payload as { workflowScope?: { waveRunId: string | null; taskIds: string[]; runIds: string[]; evidenceRefs: string[] } }).workflowScope;
+
+    assert.equal(result.status, 'PASS');
+    assert.equal(decisions.some((decision) => decision.decisionId === result.workflowGateDecision.decisionId), true);
+    assert.equal(workflowGateScope?.waveRunId, wave.waveRunId);
+    assert.deepEqual(workflowGateScope?.taskIds, ['T1', 'T2']);
+    assert.deepEqual(workflowGateScope?.runIds, wave.taskResults.map((taskResult) => taskResult.runId).sort());
+    assert.deepEqual(workflowGateScope?.evidenceRefs, expectedEvidenceRefs);
+    assert.match(renderReviewGateResult(result), /workflow_gate=PASS:/);
+  } 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));
+}

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

@@ -0,0 +1,77 @@
+import { evaluateAndRecordWorkflowGateDecision } from '../workflow-gate/evidence-packet.js';
+import type { WorkflowGateDecision, WorkflowGateStatus } from '../workflow-gate/types.js';
+
+export const REVIEW_GATE_RUNTIME_CONTRACT_VERSION = 'phase-8.17-review-gate-runtime-v1';
+
+export interface RunReviewGateOptions {
+  branch?: string | null;
+  taskId?: string | null;
+  runId?: string | null;
+  waveRunId?: string | null;
+  taskIds?: string[];
+  runIds?: string[];
+  evidenceRefs?: string[];
+}
+
+export interface ReviewGateRunResult {
+  contract: typeof REVIEW_GATE_RUNTIME_CONTRACT_VERSION;
+  branch: string;
+  taskId: string | null;
+  runId: string | null;
+  status: WorkflowGateStatus;
+  workflowGateDecision: WorkflowGateDecision;
+  next: string;
+}
+
+export async function runReviewGate(projectRoot: string, options: RunReviewGateOptions = {}): Promise<ReviewGateRunResult> {
+  const { decision } = await evaluateAndRecordWorkflowGateDecision(projectRoot, {
+    branch: options.branch,
+    taskId: options.taskId,
+    runId: options.runId,
+    decisionKind: 'review_gate',
+    waveRunId: options.waveRunId,
+    taskIds: options.taskIds,
+    runIds: options.runIds,
+    evidenceRefs: options.evidenceRefs
+  });
+  return {
+    contract: REVIEW_GATE_RUNTIME_CONTRACT_VERSION,
+    branch: decision.partition,
+    taskId: decision.taskId,
+    runId: decision.runId,
+    status: decision.status,
+    workflowGateDecision: decision,
+    next: nextForReviewGate(decision)
+  };
+}
+
+export function renderReviewGateResult(result: ReviewGateRunResult): string {
+  return [
+    'SDD review gate',
+    '',
+    `status=${result.status}`,
+    `branch=${result.branch}`,
+    `task=${result.taskId ?? 'none'}`,
+    `run=${result.runId ?? 'none'}`,
+    `workflow_gate=${result.workflowGateDecision.status}:${result.workflowGateDecision.decisionId}`,
+    '',
+    'Next:',
+    `- ${result.next}`
+  ].join('\n');
+}
+
+function nextForReviewGate(decision: WorkflowGateDecision): string {
+  if (decision.status === 'PASS') {
+    return `Continue workflow after review gate ${decision.decisionId}.`;
+  }
+  if (decision.status === 'WARN') {
+    return `Inspect review gate ${decision.decisionId} warnings before continuing.`;
+  }
+  if (decision.status === 'HUMAN_REQUIRED') {
+    return `Create a decision card for review gate ${decision.decisionId}.`;
+  }
+  if (decision.status === 'ADVISORY_ONLY') {
+    return `Inspect advisor assessments for review gate ${decision.decisionId}; do not treat advisory output as pass.`;
+  }
+  return `Resolve review gate ${decision.decisionId} blockers before continuing.`;
+}