sdd-agent-platform 0.3.0 → 0.4.1

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

@@ -0,0 +1,181 @@
+import type { SddTask, SddTaskGap } from '../sdd-docs/task-parser.js';
+import { appendTaskGaps } from '../sdd-docs/task-rendering.js';
+
+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;
+  status: string;
+  evidence: string;
+}
+
+export interface GoalVerifyResultLike {
+  runId: string;
+  taskId: string;
+  status: GoalVerifyStatus;
+  standardStatus: HarnessVerifyStatus;
+  task: SddTask | null;
+  reviewArtifact: string | null;
+  validationArtifact: string | null;
+  coverageArtifactPath: string;
+  syncBackProposalPath: string;
+  acceptanceCoverage: AcceptanceCoverageItemLike[];
+  commands: string[];
+  plannedCommands?: string[];
+  executedCommands?: string[];
+  gaps: SddTaskGap[];
+  message: string;
+}
+
+export interface SingleTaskLoopResultLike {
+  runId: string;
+  taskId: string;
+  status: SingleTaskLoopStatus;
+  task: SddTask | null;
+  gaps: SddTaskGap[];
+  requiredArtifacts: string[];
+  acceptedArtifacts: string[];
+  routeDecision: {
+    category: string;
+    recommendedProfile: string | null;
+    autonomyCeiling: string;
+    teamMode: {
+      decision: string;
+      mode: string;
+      activation: string;
+      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(`- compatibility diagnostic proposal=${result.syncBackProposalPath || 'none'}`);
+  lines.push('decision');
+  lines.push(`- status=${result.status}`);
+  lines.push(`- standard_status=${result.standardStatus}`);
+  lines.push(`- message=${result.message}`);
+  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(`- review_artifact=${result.reviewArtifact ?? 'none'}`);
+  lines.push(`- validation_artifact=${result.validationArtifact ?? 'none'}`);
+  lines.push(`- planned_commands=${(result.plannedCommands ?? result.commands).join(', ') || 'none'}`);
+  lines.push(`- executed_commands=${(result.executedCommands ?? []).join(', ') || 'none'}`);
+  if (result.acceptanceCoverage.length === 0) {
+    lines.push('- acceptance_coverage=none');
+  } else {
+    for (const item of result.acceptanceCoverage) {
+      lines.push(`- acceptance ${item.status}: ${item.acceptance} evidence=${item.evidence}`);
+    }
+  }
+  lines.push('gaps');
+  if (result.gaps.length === 0) {
+    lines.push('- none');
+  } else {
+    appendTaskGaps(lines, result.gaps, result.taskId);
+  }
+  lines.push('next');
+  if (result.status === 'PASS') {
+    lines.push(`- sdd test task ${result.taskId} --run ${result.runId}`);
+    lines.push('- then follow the test gate result toward ship readiness; use sync-back only for explicit diagnostic/recovery/replay.');
+  } else {
+    lines.push(`- update review/validator artifacts and rerun sdd test task ${result.taskId} --run ${result.runId}`);
+  }
+  return lines.join('\n');
+}
+
+export function renderSingleTaskLoopResult(result: SingleTaskLoopResultLike): string {
+  const lines = ['SDD do task result', 'changed'];
+  lines.push(`- run ${result.runId} created or updated for task ${result.taskId}`);
+  if (result.acceptedArtifacts.length > 0) {
+    lines.push(`- accepted artifacts: ${result.acceptedArtifacts.join(', ')}`);
+  }
+  lines.push('decision');
+  lines.push(`- status=${result.status}`);
+  lines.push(`- message=${result.message}`);
+  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(`- 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=runtime.sqlite:agent_executions');
+  lines.push('- team_session_records=runtime.sqlite:team_sessions');
+  lines.push('gaps');
+  if (result.gaps.length === 0) {
+    lines.push('- none');
+  } else {
+    appendTaskGaps(lines, result.gaps, result.taskId);
+  }
+  lines.push('next');
+  if (result.status === 'completed') {
+    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 batch ${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`);
+    }
+    const rerunFlags = artifactFlags.map((item) => `${artifactOptionName(item.agent)} ${item.artifact}`).join(' ');
+    lines.push(`- sdd do task ${result.taskId} --run ${result.runId}${rerunFlags ? ` ${rerunFlags}` : ''}`);
+  }
+  return lines.join('\n');
+}
+
+function requiresImmediateValidation(task: SddTask): boolean {
+  return task.requiresVerifyBeforeNext || task.validationTiming === 'task_end';
+}
+
+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 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,77 @@
+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';
+
+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' });
+
+    const wave = await runValidationWave(root, { branch: 'feature', wave: 1, approved: true });
+    const expectedEvidenceRefs = wave.taskResults.flatMap((taskResult) => [taskResult.validationArtifact, taskResult.indexArtifact].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 });
+  }
+});

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.`;
+}

package/node_modules/@sdd-agent-platform/core/src/verification/single-task-loop.test.ts

@@ -0,0 +1,255 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+import { inspectArtifactResultIngestions } from '../artifacts/ingestion.js';
+import { initProject } from '../config/init-project.js';
+import { getProjectStatus } from '../status/project-status.js';
+import { doctor } from '../doctor/doctor.js';
+import { readArtifact, writeArtifact } from '../run-state/artifacts.js';
+import { inspectRun } from '../run-state/inspect-run.js';
+import { readTaskEvidenceView } from '../run-state/task-evidence.js';
+import { rebuildLocalRunIndex } from '../run-state/run-index.js';
+import { readRunEvents } from '../run-state/events.js';
+import { createRun, readRunState } from '../run-state/run-state.js';
+import { recordRuntimeArtifactPayload, runtimeScopedId } from '../storage/runtime-store.js';
+import { validResultArtifact, validTaskMarkdown, validTrustEvidence, writeBranchDocs } from '../test-support/fixtures.js';
+import { writeVerifyContract } from './verify-contract.js';
+import { bindTestRunState } from '../test-support/run-state.js';
+import { renderSingleTaskLoopResult } from './rendering.js';
+import { runSingleTaskLoop } from './single-task-loop.js';
+
+const execFileAsync = promisify(execFile);
+
+function stringifyEvents(events: Awaited<ReturnType<typeof readRunEvents>>): string {
+  return events.map((event) => `${event.event}\n${event.summary ?? ''}`).join('\n');
+}
+
+test('runSingleTaskLoop completes from supplied review and validation artifacts without modifying tasks markdown', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-loop-pass-'));
+  try {
+    await initProject(root);
+    await execFileAsync('git', ['init'], { cwd: root });
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    await writeVerifyContract(root, { branch: 'feature', branchSource: 'cli_option' });
+    const state = await createRun(root, { runId: 'run-1' });
+    await bindTestRunState(root, state.runId, 'feature', 'T1');
+    await writeArtifact(root, state.runId, 'review-T1.md', validResultArtifact('reviewer', 'T1', 'PASS', 'artifacts/review-T1.md'));
+    await writeArtifact(root, state.runId, 'validation-T1.md', `${validResultArtifact('validator', 'T1', 'PASS', 'artifacts/validation-T1.md')}${validTrustEvidence('T1', 'AC-1', 'artifacts/validation-T1.md')}`);
+
+    const result = await runSingleTaskLoop(root, {
+      runId: state.runId,
+      branch: 'feature',
+      taskId: 'T1',
+      reviewArtifact: 'artifacts/review-T1.md',
+      validationArtifact: 'artifacts/validation-T1.md'
+    });
+    const restored = await readRunState(root, state.runId);
+    const ingestionInspection = await inspectArtifactResultIngestions(root, state.runId);
+    await rebuildLocalRunIndex(root);
+    const doctorReport = await doctor(root, { latestOnly: true });
+    const events = stringifyEvents(await readRunEvents(root, state.runId));
+    const tasksMarkdown = await readFile(path.join(root, 'specs', 'feature', 'tasks.md'), 'utf8');
+    await execFileAsync('git', ['checkout', '-b', 'feature'], { cwd: root });
+    await recordRuntimeArtifactPayload(root, {
+      payloadId: runtimeScopedId(state.runId, 'artifacts/validation-T2.md', 'foreign-task'),
+      runId: state.runId,
+      sourceRunId: state.runId,
+      branchSlug: 'feature',
+      taskId: 'T2',
+      logicalRef: 'artifacts/validation-T2.md',
+      physicalPayloadPath: 'artifacts/validation-T2-run-1-foreign-task.md',
+      artifactRole: 'validation',
+      digest: 'foreign-task',
+      status: 'active',
+      payload: { logicalRef: 'artifacts/validation-T2.md' }
+    });
+    const taskEvidence = await readTaskEvidenceView(root, { branch: 'feature', taskId: 'T1' });
+
+    assert.equal(result.status, 'completed');
+    assert.deepEqual(result.acceptedArtifacts, ['artifacts/review-T1.md', 'artifacts/validation-T1.md']);
+    assert.equal(restored.status, 'completed');
+    assert.equal(restored.currentTask, 'T1');
+    assert.equal(restored.syncBack.status, 'proposed');
+    assert.equal(restored.syncBack.proposalPath, 'artifacts/sync-back-proposal.md');
+    assert.equal(ingestionInspection.valid, true);
+    assert.deepEqual(ingestionInspection.records.map((record) => record.delegationId), ['B-T1-reviewer-001', 'B-T1-validator-001']);
+    assert.equal(doctorReport.status, 'FAIL');
+    assert.match(events, /task_selected/);
+    assert.match(events, /review_passed/);
+    assert.match(events, /validation_passed/);
+    assert.match(events, /delegation_started/);
+    assert.match(events, /delegation_completed/);
+    assert.doesNotMatch(events, /agent_completed/);
+    assert.match(tasksMarkdown, /status: pending/);
+    assert.equal(taskEvidence.latestEligibleRun?.runId, state.runId);
+    assert.equal(taskEvidence.compatibility, 'compatible');
+    assert.equal(taskEvidence.payloads.active.some((payload) => payload.logicalRef === 'artifacts/sync-back-proposal.md'), true);
+    assert.equal(taskEvidence.payloads.all.some((payload) => payload.taskId === 'T2'), false);
+    assert.equal(taskEvidence.validation.runValidation?.status, 'pass');
+    assert.equal(taskEvidence.syncBackDecision?.status, 'proposed');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('runSingleTaskLoop blocks rejected validation ingestion without accepting the artifact', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-loop-rejected-validation-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const state = await createRun(root, { runId: 'run-1' });
+    await bindTestRunState(root, state.runId, 'feature', 'T1');
+    await writeArtifact(root, state.runId, 'review-T1.md', validResultArtifact('reviewer', 'T1', 'PASS', 'artifacts/review-T1.md'));
+    await writeArtifact(root, state.runId, 'validation-T1.md', validResultArtifact('validator', 'T1', 'PASS', 'artifacts/validation-T1.md'));
+
+    const result = await runSingleTaskLoop(root, {
+      runId: state.runId,
+      branch: 'feature',
+      taskId: 'T1',
+      reviewArtifact: 'artifacts/review-T1.md',
+      validationArtifact: 'artifacts/validation-T1.md'
+    });
+    const restored = await readRunState(root, state.runId);
+    const ingestionInspection = await inspectArtifactResultIngestions(root, state.runId);
+
+    assert.equal(result.status, 'blocked');
+    assert.equal(restored.status, 'blocked');
+    assert.equal(restored.validation.status, 'blocked');
+    assert.deepEqual(result.acceptedArtifacts, ['artifacts/review-T1.md', 'artifacts/gap-report-T1.md']);
+    assert.equal(restored.artifacts.some((artifact) => artifact.path === 'artifacts/validation-T1.md'), false);
+    assert.equal(ingestionInspection.valid, true);
+    assert.equal(ingestionInspection.records.find((record) => record.artifactPath === 'artifacts/validation-T1.md')?.status, 'rejected');
+    assert.equal(result.gaps.some((gap) => /UNSOURCED_PASS/.test(gap.message)), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('runSingleTaskLoop blocks on missing reviewer artifact and creates gap proposal', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-loop-block-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const state = await createRun(root, { runId: 'run-1' });
+
+    const result = await runSingleTaskLoop(root, {
+      runId: state.runId,
+      branch: 'feature',
+      taskId: 'T1'
+    });
+    const restored = await readRunState(root, state.runId);
+    const gapReport = await readArtifact(root, state.runId, 'gap-report-T1.md');
+    const proposal = await readArtifact(root, state.runId, 'sync-back-proposal.md');
+
+    assert.equal(result.status, 'blocked');
+    assert.equal(result.gaps.some((gap) => gap.field === 'implementer'), false);
+    assert.equal(result.gaps.some((gap) => gap.field === 'reviewer'), true);
+    const rendered = renderSingleTaskLoopResult(result);
+
+    assert.match(rendered, /^SDD do task result/);
+    assert.match(rendered, /status=blocked/);
+    assert.match(rendered, /create or validate missing run-relative artifacts/);
+    assert.match(rendered, /sdd artifact template artifacts\/review-T1.md --task T1 --agent reviewer --run run-1 --write/);
+    assert.match(rendered, /sdd artifact template artifacts\/implement-T1.md --task T1 --agent implementer --run run-1 --write/);
+    assert.match(rendered, /sdd artifact template artifacts\/validation-T1.md --task T1 --agent validator --run run-1 --write/);
+    assert.match(rendered, /--implement-artifact artifacts\/implement-T1.md/);
+    assert.match(rendered, /--validation-artifact artifacts\/validation-T1.md/);
+    assert.match(rendered, /physical artifact files belong under branch evidence \.sdd\/runs\/<branchSlug>\/evidence\/artifacts\//);
+    assert.match(rendered, /artifact_path_scope=CLI flags use run-relative artifacts\/<file>/);
+    assert.equal(restored.status, 'blocked');
+    assert.match(restored.artifactRoot, /\.sdd[\\/]runs[\\/]feature[\\/]evidence/);
+    assert.match(gapReport, /reviewer artifact was not supplied/);
+    assert.match(proposal, /Proposal only/);
+    const events = stringifyEvents(await readRunEvents(root, state.runId));
+    assert.match(events, /delegation_failed/);
+    assert.doesNotMatch(events, /agent_failed/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('runSingleTaskLoop blocks PASS_WITH_GAPS validation with gap report and blocked sync-back proposal', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-loop-pass-with-gaps-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const state = await createRun(root, { runId: 'run-1' });
+    await bindTestRunState(root, state.runId, 'feature', 'T1');
+    await writeArtifact(root, state.runId, 'review-T1.md', validResultArtifact('reviewer', 'T1', 'PASS', 'artifacts/review-T1.md'));
+    await writeArtifact(root, state.runId, 'validation-T1.md', `${validResultArtifact('validator', 'T1', 'PASS_WITH_GAPS', 'artifacts/validation-T1.md')}${validTrustEvidence('T1', 'AC-1', 'artifacts/validation-T1.md')}`);
+
+    const result = await runSingleTaskLoop(root, {
+      runId: state.runId,
+      branch: 'feature',
+      taskId: 'T1',
+      reviewArtifact: 'artifacts/review-T1.md',
+      validationArtifact: 'artifacts/validation-T1.md'
+    });
+    const restored = await readRunState(root, state.runId);
+    const gapReport = await readArtifact(root, state.runId, 'gap-report-T1.md');
+    const proposal = await readArtifact(root, state.runId, 'sync-back-proposal.md');
+    const events = stringifyEvents(await readRunEvents(root, state.runId));
+
+    assert.equal(result.status, 'blocked');
+    assert.equal(restored.status, 'blocked');
+    assert.equal(restored.validation.status, 'pass_with_gaps');
+    assert.equal(result.gaps.some((gap) => gap.field === 'validation_gaps'), true);
+    assert.match(gapReport, /Validator returned PASS_WITH_GAPS/);
+    assert.match(proposal, /status: blocked/);
+    assert.match(proposal, /blocked gap proposal, not task completion/);
+    assert.match(events, /gap_created/);
+    assert.match(events, /gap_escalated/);
+    assert.doesNotMatch(events, /run_completed/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('runSingleTaskLoop persists agent and team evidence records', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase60-execution-records-'));
+  try {
+    await initProject(root);
+
+    const result = await runSingleTaskLoop(root, { taskId: 'ONBOARDING-1', branch: 'master' });
+    const inspection = await inspectRun(root, result.runId);
+    const status = await getProjectStatus(root, { branch: 'master' });
+    const report = await doctor(root);
+
+    assert.equal(result.status, 'blocked');
+    assert.equal(result.routeDecision.teamMode.decision, 'enabled');
+    assert.equal(result.routeDecision.teamMode.activation, 'auto');
+    assert.equal(result.routeDecision.teamMode.mode, 'review-lite');
+    assert.equal(result.routeDecision.teamMode.costClass, 'low');
+    assert.equal(inspection.agentExecutions.length, 2);
+    const implementerRecord = inspection.agentExecutions.find((record) => record.status === 'skipped' && record.profile === 'implementer');
+    const reviewerRecord = inspection.agentExecutions.find((record) => record.status === 'blocked' && record.profile === 'reviewer');
+    assert.ok(implementerRecord);
+    assert.ok(reviewerRecord);
+    assert.equal(implementerRecord.toolPermission?.profile, 'implementer');
+    assert.equal(implementerRecord.routeDecision.recommendedProfile, 'implementer');
+    assert.equal(reviewerRecord.toolPermission?.profile, 'reviewer');
+    assert.equal(reviewerRecord.routeDecision.recommendedProfile, 'reviewer');
+    assert.match(reviewerRecord.routeId, /^[a-f0-9]{16}$/);
+    assert.equal(inspection.teamSessions.length, 1);
+    const teamSession = inspection.teamSessions[0];
+    assert.ok(teamSession);
+    assert.equal(teamSession.status, 'blocked');
+    assert.equal(teamSession.teamMode.activation, 'auto');
+    assert.equal(teamSession.teamMode.mode, 'review-lite');
+    assert.equal(teamSession.teamMode.costClass, 'low');
+    assert.match(teamSession.teamMode.reason, /review|validation/i);
+    assert.equal(inspection.taskRunEvidence.teamSessions.length, inspection.teamSessions.length);
+    const rejectedRun = status.latestEligibleRunsByTask.flatMap((selection) => selection.rejected).find((candidate) => candidate.runId === result.runId);
+    assert.equal(rejectedRun?.reasons.includes('Run is blocked.'), true);
+    assert.equal(inspection.taskRunEvidence.agentExecutions.length, 2);
+    assert.equal(inspection.taskRunEvidence.teamSessions.length, 1);
+    assert.equal(report.checks.some((check) => check.check === 'agent_team_execution_records' && /agent execution record/.test(check.message)), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});