sdd-agent-platform 0.4.1 → 0.4.2

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

@@ -1,5 +1,5 @@
-import { createHash } from 'node:crypto';
 import { SDD_RESULT_CONTRACT, SDD_RESULT_VERSION } from '../contracts.js';
+import { toBranchStageEvidenceRef } from '../runtime-paths.js';
 import { artifactKind, writeArtifact } from '../run-state/artifacts.js';
 import { appendEvent } from '../run-state/events.js';
 import type { RunState, RunStateTaskRuntime } from '../run-state/model.js';
@@ -9,11 +9,13 @@ import { bindRunStateToTask } from '../sdd-docs/run-binding.js';
 import { inspectSddTask, taskGap } from '../sdd-docs/task-inspection.js';
 import { parseSddBranch, type SddTask, type SddTaskGap } from '../sdd-docs/task-parser.js';
 import type { AgentRouterDecision } from '../router/agent-runtime.js';
+import type { LifecycleRiskDecision } from '../risk/contracts.js';
+import { readLifecycleRiskDecisionProjection } from '../risk/kernel.js';
 import type { TeamModeActivation } from '../router/route-cache.js';
 import { routeSddTask } from '../router/route-sdd-task.js';
 import { buildAgentExecutionRecord, buildTeamSessionRecord, writeAgentExecutionRecord, writeTeamSessionRecord } from '../execution/agent-execution-records.js';
 import { runBackgroundExecutor } from '../execution/background-executor.js';
-import { recordRuntimeSyncBackDecision, runtimeScopedId } from '../storage/runtime-store.js';
+import { reconcileDoCollaborationClosure } from '../stage-collaboration.js';
 
 export type SingleTaskLoopStatus = 'completed' | 'blocked' | 'failed';
 
@@ -45,7 +47,6 @@ export interface SingleTaskLoopResult {
   gaps: SddTaskGap[];
   requiredArtifacts: string[];
   acceptedArtifacts: string[];
-  syncBackProposalPath: string;
   routeDecision: AgentRouterDecision;
   message: string;
 }
@@ -54,21 +55,22 @@ export async function runSingleTaskLoop(projectRoot: string, options: SingleTask
   const context = await resolveSddContext(projectRoot, options.branch ? { branch: options.branch, branchSource: 'cli_option' } : {});
   const branch = context.partition;
   const model = await parseSddBranch(projectRoot, branch);
-  const inspected = inspectSddTask(model, options.taskId);
+  const routeDecision = await routeSddTask(projectRoot, { taskId: options.taskId, branch, teamModeEnabled: options.teamModeEnabled, teamModeActivation: options.teamModeActivation, approved: options.approved });
+  const taskId = routeDecision.taskId;
+  const inspected = inspectSddTask(model, taskId);
   const runState = options.runId ? await readRunState(projectRoot, options.runId) : await createRun(projectRoot);
-  const boundRunState = await bindRunStateToTask(projectRoot, runState, context, model, inspected.task ?? null, options.taskId);
+  const boundRunState = await bindRunStateToTask(projectRoot, runState, context, model, inspected.task ?? null, taskId);
   const runId = boundRunState.runId;
-  const routeDecision = await routeSddTask(projectRoot, { taskId: options.taskId, branch, teamModeEnabled: options.teamModeEnabled, teamModeActivation: options.teamModeActivation, approved: options.approved });
   await appendEvent(projectRoot, runId, {
     event: 'agent_router_preflight',
     runId,
-    summary: `Agent router preflight ${routeDecision.blockedReason ? 'blocked' : 'passed'} for ${options.taskId}`,
-    data: { taskId: options.taskId, decision: routeDecision }
+    summary: `Agent router preflight ${routeDecision.blockedReason ? 'blocked' : 'passed'} for ${taskId}`,
+    data: { taskId: taskId, decision: routeDecision }
   });
   if (routeDecision.teamMode.enabled || routeDecision.teamMode.decision !== 'disabled') {
     await writeTeamSessionRecord(projectRoot, buildTeamSessionRecord({
       runId,
-      taskId: options.taskId,
+      taskId: taskId,
       route: routeDecision,
       status: routeDecision.teamMode.decision === 'enabled' ? 'created' : routeDecision.teamMode.decision === 'blocked' ? 'blocked' : 'disabled',
       artifacts: [],
@@ -79,62 +81,57 @@ export async function runSingleTaskLoop(projectRoot: string, options: SingleTask
   await appendEvent(projectRoot, runId, {
     event: 'phase_started',
     runId,
-    summary: `Phase 3.15 ingestion-aware task loop started for ${options.taskId}`,
-    data: { phase: 'do', branch, task: options.taskId }
+    summary: `Phase 3.15 ingestion-aware task loop started for ${taskId}`,
+    data: { phase: 'do', branch, task: taskId }
   });
 
+  const stageEvidenceResult = await reconcileDoStageEvidenceIfAvailable(projectRoot, {
+    branch,
+    runId,
+    taskId: taskId,
+    task: inspected.task,
+    routeDecision,
+    options
+  });
+  if (stageEvidenceResult) {
+    return stageEvidenceResult;
+  }
+
   if (routeDecision.blockedReason || routeDecision.toolPermission?.policy === 'deny' || !inspected.task || inspected.gaps.some((gap) => gap.severity === 'blocking')) {
-    const routeGap = routeDecision.blockedReason ? [taskGap(options.taskId, 'agent_router', routeDecision.blockedReason, routeDecision.nextAction)] : [];
-    const toolPermissionGap = routeDecision.toolPermission?.policy === 'deny' ? [taskGap(options.taskId, 'tool_permission', 'Agent router denied required tool permission for this task.', 'Change task scope, tool policy, or route through a permitted profile before execution.')] : [];
+    const routeGap = routeDecision.blockedReason ? [taskGap(taskId, 'agent_router', routeDecision.blockedReason, routeDecision.nextAction)] : [];
+    const toolPermissionGap = routeDecision.toolPermission?.policy === 'deny' ? [taskGap(taskId, 'tool_permission', 'Agent router denied required tool permission for this task.', 'Change task scope, tool policy, or route through a permitted profile before execution.')] : [];
     const allGaps = [...routeGap, ...toolPermissionGap, ...inspected.gaps];
-    const gapArtifact = await writeArtifact(projectRoot, runId, `gap-report-${options.taskId}.md`, renderLoopGapReport(options.taskId, allGaps));
-    const proposal = await writeSyncBackProposal(projectRoot, runId, options.taskId, 'blocked', [gapArtifact.runRelativePath], allGaps, 'Task selection is blocked by router preflight or parser/task gaps.');
     await persistLoopState(projectRoot, runId, {
       status: 'blocked',
       phase: 'do',
-      taskId: options.taskId,
-      taskState: buildRuntimeTaskState(inspected.task, 'blocked', 'blocked', allGaps, [gapArtifact.runRelativePath]),
+      taskId: taskId,
+      taskState: buildRuntimeTaskState(inspected.task, 'blocked', 'blocked', allGaps, []),
       validationStatus: 'blocked',
-      syncBackProposalPath: proposal.runRelativePath,
-      syncBackProposalDigest: proposal.digest,
-      artifacts: [{ path: gapArtifact.runRelativePath, kind: 'gap-report', task: options.taskId, agent: 'runtime' }]
-    });
-    await recordLoopSyncBackDecision(projectRoot, {
-      runId,
-      branch,
-      taskId: options.taskId,
-      status: 'proposed',
-      proposalPath: proposal.runRelativePath,
-      proposalDigest: proposal.digest,
-      proposalPayloadId: proposal.payloadId,
-      reasons: allGaps.map((gap) => `${gap.severity} ${gap.type} ${gap.field}: ${gap.message}`),
-      payload: { sourceVerifyStatus: 'blocked', artifacts: [gapArtifact.runRelativePath] }
+      artifacts: []
     });
     await appendEvent(projectRoot, runId, {
       event: 'gap_detected',
       runId,
-      summary: `Task ${options.taskId} is blocked before implementation.`,
-      data: { gaps: allGaps, artifact: gapArtifact.runRelativePath, routeDecision }
+      summary: `Task ${taskId} is blocked before implementation.`,
+      data: { gaps: allGaps, routeDecision }
     });
     await writeAgentExecutionRecord(projectRoot, buildAgentExecutionRecord({
       runId,
-      taskId: options.taskId,
+      taskId: taskId,
       agent: 'orchestrator',
       route: routeDecision,
       status: 'blocked',
-      delegationId: `P-${options.taskId}-router-001`,
-      artifactPath: gapArtifact.runRelativePath,
+      delegationId: `P-${taskId}-router-001`,
       evidenceSummary: `Task loop blocked before implementation by router preflight or task gaps with ${allGaps.length} issue(s).`
     }));
     return {
       runId,
-      taskId: options.taskId,
+      taskId: taskId,
       status: 'blocked',
       task: inspected.task,
       gaps: allGaps,
       requiredArtifacts: [],
-      acceptedArtifacts: [gapArtifact.runRelativePath],
-      syncBackProposalPath: proposal.runRelativePath,
+      acceptedArtifacts: [],
       routeDecision,
       message: 'Task loop blocked before implementation by router preflight or task gaps.'
     };
@@ -143,52 +140,52 @@ export async function runSingleTaskLoop(projectRoot: string, options: SingleTask
   await appendEvent(projectRoot, runId, {
     event: 'task_selected',
     runId,
-    summary: `Task selected for ingestion-aware task loop: ${options.taskId}`,
-    data: { task: options.taskId, title: inspected.task.title, source: inspected.task.source }
+    summary: `Task selected for ingestion-aware task loop: ${taskId}`,
+    data: { task: taskId, title: inspected.task.title, source: inspected.task.source }
   });
 
-  const steps = buildLoopSteps(options.taskId, options, inspected.task);
+  const steps = buildLoopSteps(branch, taskId, options, inspected.task);
   const acceptedArtifacts: string[] = [];
   const gaps: SddTaskGap[] = [];
   let terminalStatus: SingleTaskLoopStatus = 'completed';
   let validationStatus: RunState['validation']['status'] = 'not_run';
 
   for (const step of steps) {
-    const stepRouteDecision = await routeSddTask(projectRoot, { taskId: options.taskId, branch, agent: step.agent, teamModeEnabled: options.teamModeEnabled, teamModeActivation: options.teamModeActivation, approved: options.approved });
+    const stepRouteDecision = await routeSddTask(projectRoot, { taskId: taskId, branch, agent: step.agent, teamModeEnabled: options.teamModeEnabled, teamModeActivation: options.teamModeActivation, approved: options.approved });
     if (!step.suppliedArtifact) {
       if (!step.required) {
         await appendEvent(projectRoot, runId, {
           event: 'delegation_cancelled',
           runId,
-          summary: `${step.agent} artifact not supplied; optional step skipped for ${options.taskId}`,
+          summary: `${step.agent} artifact not supplied; optional step skipped for ${taskId}`,
           data: { agent: step.agent, expectedArtifact: step.expectedArtifact }
         });
         await writeAgentExecutionRecord(projectRoot, buildAgentExecutionRecord({
           runId,
-          taskId: options.taskId,
+          taskId: taskId,
           agent: step.agent,
           route: stepRouteDecision,
           status: 'skipped',
-          delegationId: `B-${options.taskId}-${step.agent}-001`,
+          delegationId: `B-${taskId}-${step.agent}-001`,
           evidenceSummary: `${step.agent} artifact was not supplied and the step is optional.`
         }));
         continue;
       }
-      const gap = taskGap(options.taskId, step.agent, `${step.agent} artifact was not supplied; the task loop facade does not invoke external agents directly.`, `Run the ${step.agent} step in Claude Code and pass ${artifactOptionName(step.agent)} artifacts/<file>; physical evidence is branch-scoped under .sdd/runs/<branchSlug>/evidence/artifacts/<file>.`);
+      const gap = taskGap(taskId, step.agent, `${step.agent} artifact was not supplied; the task loop facade does not invoke external agents directly.`, `Run the ${step.agent} step in Claude Code and provide agent-authored evidence under .sdd/runs/<branch>/do/*.md before closing do-stage evidence.`);
       gaps.push(gap);
       await appendEvent(projectRoot, runId, {
         event: 'delegation_failed',
         runId,
-        summary: `${step.agent} artifact missing for ${options.taskId}`,
+        summary: `${step.agent} artifact missing for ${taskId}`,
         data: { agent: step.agent, expectedArtifact: step.expectedArtifact }
       });
       await writeAgentExecutionRecord(projectRoot, buildAgentExecutionRecord({
         runId,
-        taskId: options.taskId,
+        taskId: taskId,
         agent: step.agent,
         route: stepRouteDecision,
         status: 'blocked',
-        delegationId: `B-${options.taskId}-${step.agent}-001`,
+        delegationId: `B-${taskId}-${step.agent}-001`,
         evidenceSummary: `${step.agent} artifact was not supplied; execution is blocked before host invocation.`
       }));
       terminalStatus = 'blocked';
@@ -199,10 +196,10 @@ export async function runSingleTaskLoop(projectRoot: string, options: SingleTask
     const result = await runBackgroundExecutor(projectRoot, {
       branch,
       runId,
-      taskId: options.taskId,
+      taskId: taskId,
       agent: step.agent,
       artifactPath: step.suppliedArtifact,
-      delegationId: `B-${options.taskId}-${step.agent}-001`,
+      delegationId: `B-${taskId}-${step.agent}-001`,
       approved: options.approved
     });
 
@@ -210,8 +207,8 @@ export async function runSingleTaskLoop(projectRoot: string, options: SingleTask
       const issueText = result.issues.map((issue) => issue.message).join('; ') || result.message;
       const recommendation = issueText.includes('manual isolation gate') || issueText.includes('requires confirmation')
         ? 'Resolve the manual isolation or approval gate for this high-risk task before ingesting execution artifacts.'
-        : `Fix ${step.suppliedArtifact} so the Phase 3 executor can ingest one valid sdd-result block for ${step.agent}/${options.taskId}.`;
-      gaps.push(taskGap(options.taskId, step.agent, `${step.agent} artifact ${step.suppliedArtifact} could not be ingested: ${issueText}`, recommendation));
+        : `Fix ${step.suppliedArtifact} so the Phase 3 executor can ingest one valid sdd-result block for ${step.agent}/${taskId}.`;
+      gaps.push(taskGap(taskId, step.agent, `${step.agent} artifact ${step.suppliedArtifact} could not be ingested: ${issueText}`, recommendation));
       terminalStatus = 'blocked';
       validationStatus = step.agent === 'validator' ? 'blocked' : validationStatus;
       break;
@@ -221,11 +218,11 @@ export async function runSingleTaskLoop(projectRoot: string, options: SingleTask
 
     if (step.agent === 'reviewer') {
       if (result.ingestion.resultStatus === 'PASS') {
-        await appendEvent(projectRoot, runId, { event: 'review_passed', runId, summary: `Review passed for ${options.taskId}`, data: { artifact: result.ingestion.artifactPath } });
+        await appendEvent(projectRoot, runId, { event: 'review_passed', runId, summary: `Review passed for ${taskId}`, data: { artifact: result.ingestion.artifactPath } });
       } else {
-        await appendEvent(projectRoot, runId, { event: 'review_failed', runId, summary: `Review did not pass for ${options.taskId}; debugger may be supplied once.`, data: { artifact: result.ingestion.artifactPath, status: result.ingestion.resultStatus } });
+        await appendEvent(projectRoot, runId, { event: 'review_failed', runId, summary: `Review did not pass for ${taskId}; debugger may be supplied once.`, data: { artifact: result.ingestion.artifactPath, status: result.ingestion.resultStatus } });
         if (!options.debugArtifact) {
-          gaps.push(taskGap(options.taskId, 'debugger', 'Review did not pass and no debugger artifact was supplied.', 'Run one debugger attempt or create a gap report; the task loop allows only one debugger pass.'));
+          gaps.push(taskGap(taskId, 'debugger', 'Review did not pass and no debugger artifact was supplied.', 'Run one debugger attempt or create a gap report; the task loop allows only one debugger pass.'));
           terminalStatus = result.ingestion.resultStatus === 'BLOCKED' ? 'blocked' : 'failed';
           validationStatus = 'fail';
           break;
@@ -235,16 +232,16 @@ export async function runSingleTaskLoop(projectRoot: string, options: SingleTask
 
     if (step.agent === 'validator') {
       if (result.ingestion.resultStatus === 'PASS') {
-        await appendEvent(projectRoot, runId, { event: 'validation_passed', runId, summary: `Validation passed for ${options.taskId}`, data: { artifact: result.ingestion.artifactPath } });
+        await appendEvent(projectRoot, runId, { event: 'validation_passed', runId, summary: `Validation passed for ${taskId}`, data: { artifact: result.ingestion.artifactPath } });
         validationStatus = 'pass';
       } else if (result.ingestion.resultStatus === 'PASS_WITH_GAPS') {
-        await appendEvent(projectRoot, runId, { event: 'validation_passed', runId, summary: `Validation passed with gaps for ${options.taskId}; task remains blocked until gaps are resolved.`, data: { artifact: result.ingestion.artifactPath, status: result.ingestion.resultStatus } });
-        gaps.push(taskGap(options.taskId, 'validation_gaps', 'Validator returned PASS_WITH_GAPS; the task loop cannot mark the task completed without structured gap evidence and explicit sync-back proposal semantics.', 'Inspect the validator artifact, resolve or defer each validation gap, then rerun with PASS validation evidence.'));
+        await appendEvent(projectRoot, runId, { event: 'validation_passed', runId, summary: `Validation passed with gaps for ${taskId}; task remains blocked until gaps are resolved.`, data: { artifact: result.ingestion.artifactPath, status: result.ingestion.resultStatus } });
+        gaps.push(taskGap(taskId, 'validation_gaps', 'Validator returned PASS_WITH_GAPS; the task loop cannot mark the task completed without structured gap evidence.', 'Inspect the validator artifact, resolve or defer each validation gap, then rerun with PASS validation evidence.'));
         validationStatus = 'pass_with_gaps';
         terminalStatus = 'blocked';
       } else {
-        await appendEvent(projectRoot, runId, { event: 'validation_failed', runId, summary: `Validation failed for ${options.taskId}`, data: { artifact: result.ingestion.artifactPath, status: result.ingestion.resultStatus } });
-        gaps.push(taskGap(options.taskId, 'validation', `Validator returned ${result.ingestion.resultStatus}.`, 'Do not mark the task completed; create a gap report or revise the task/plan.'));
+        await appendEvent(projectRoot, runId, { event: 'validation_failed', runId, summary: `Validation failed for ${taskId}`, data: { artifact: result.ingestion.artifactPath, status: result.ingestion.resultStatus } });
+        gaps.push(taskGap(taskId, 'validation', `Validator returned ${result.ingestion.resultStatus}.`, 'Do not mark the task completed; create a gap report or revise the task/plan.'));
         validationStatus = result.ingestion.resultStatus === 'BLOCKED' ? 'blocked' : 'fail';
         terminalStatus = result.ingestion.resultStatus === 'BLOCKED' ? 'blocked' : 'failed';
       }
@@ -252,56 +249,37 @@ export async function runSingleTaskLoop(projectRoot: string, options: SingleTask
   }
 
   if (gaps.length > 0 && terminalStatus !== 'completed') {
-    const gapArtifact = await writeArtifact(projectRoot, runId, `gap-report-${options.taskId}.md`, renderLoopGapReport(options.taskId, gaps));
-    acceptedArtifacts.push(gapArtifact.runRelativePath);
+    const gapFileName = `gap-report-${taskId}.md`;
+    await writeArtifact(projectRoot, runId, gapFileName, renderLoopGapReport(branch, taskId, gaps));
+    const gapRef = toBranchStageEvidenceRef(branch, 'do', gapFileName);
+    acceptedArtifacts.push(gapRef);
     await appendEvent(projectRoot, runId, {
       event: 'gap_created',
       runId,
-      summary: `Gap report created for ${options.taskId}`,
-      data: { artifact: gapArtifact.runRelativePath, gaps }
+      summary: `Gap report created for ${taskId}`,
+      data: { artifact: gapRef, gaps }
     });
   }
 
   const taskState = buildRuntimeTaskState(inspected.task, terminalStatus, validationStatus, gaps, acceptedArtifacts);
-  const proposalStatus = taskState.status === 'implemented_pending_validation' ? taskState.status : terminalStatus === 'completed' ? 'completed' : terminalStatus;
-  const proposal = await writeSyncBackProposal(projectRoot, runId, options.taskId, proposalStatus, acceptedArtifacts, gaps, terminalStatus === 'completed' ? 'Ingestion-aware task loop accepted implementation evidence; validation may still be pending by task contract.' : terminalStatus === 'blocked' && validationStatus === 'pass_with_gaps' ? 'Ingestion-aware task loop stopped because validator returned PASS_WITH_GAPS; sync-back is a blocked gap proposal, not task completion.' : 'Ingestion-aware task loop stopped with blocking/failing evidence.');
   await persistLoopState(projectRoot, runId, {
     status: terminalStatus,
     phase: 'do',
-    taskId: options.taskId,
+    taskId: taskId,
     taskState,
     validationStatus,
-    syncBackProposalPath: proposal.runRelativePath,
-    syncBackProposalDigest: proposal.digest,
-    artifacts: acceptedArtifacts.map((artifactPath) => ({ path: artifactPath, kind: artifactKind(artifactPath), task: options.taskId, agent: agentFromArtifactPath(artifactPath) }))
-  });
-  await recordLoopSyncBackDecision(projectRoot, {
-    runId,
-    branch,
-    taskId: options.taskId,
-    status: 'proposed',
-    proposalPath: proposal.runRelativePath,
-    proposalDigest: proposal.digest,
-    proposalPayloadId: proposal.payloadId,
-    reasons: gaps.map((gap) => `${gap.severity} ${gap.type} ${gap.field}: ${gap.message}`),
-    payload: { sourceVerifyStatus: terminalStatus, artifacts: acceptedArtifacts }
-  });
-  await appendEvent(projectRoot, runId, {
-    event: 'sync_back_proposed',
-    runId,
-    summary: `Sync-back proposal created for ${options.taskId}`,
-    data: { proposal: proposal.runRelativePath, status: terminalStatus }
+    artifacts: acceptedArtifacts.map((artifactPath) => ({ path: artifactPath, kind: artifactKind(artifactPath), task: taskId, agent: agentFromArtifactPath(artifactPath) }))
   });
   await appendEvent(projectRoot, runId, {
     event: terminalStatus === 'completed' ? 'run_completed' : terminalStatus === 'blocked' ? 'gap_escalated' : 'validation_failed',
     runId,
-    summary: `Phase 3.15 ingestion-aware task loop ${terminalStatus} for ${options.taskId}`,
-    data: { task: options.taskId, artifacts: acceptedArtifacts, gaps }
+    summary: `Phase 3.15 ingestion-aware task loop ${terminalStatus} for ${taskId}`,
+    data: { task: taskId, artifacts: acceptedArtifacts, gaps }
   });
   if (routeDecision.teamMode.enabled || routeDecision.teamMode.decision !== 'disabled') {
     await writeTeamSessionRecord(projectRoot, buildTeamSessionRecord({
       runId,
-      taskId: options.taskId,
+      taskId: taskId,
       route: routeDecision,
       status: terminalStatus === 'completed' ? 'completed' : 'blocked',
       artifacts: acceptedArtifacts,
@@ -311,27 +289,111 @@ export async function runSingleTaskLoop(projectRoot: string, options: SingleTask
 
   return {
     runId,
-    taskId: options.taskId,
+    taskId: taskId,
     status: terminalStatus,
     task: inspected.task,
     gaps,
     requiredArtifacts: steps.map((step) => step.expectedArtifact),
     acceptedArtifacts,
-    syncBackProposalPath: proposal.runRelativePath,
     routeDecision,
-    message: terminalStatus === 'completed' ? 'Task loop completed through Phase 3 executor artifact ingestion.' : validationStatus === 'pass_with_gaps' ? 'Task loop blocked because validator returned PASS_WITH_GAPS; inspect gap report and sync-back proposal.' : 'Task loop stopped; inspect gap report and sync-back proposal.'
+    message: terminalStatus === 'completed' ? 'Task loop completed through Phase 3 executor artifact ingestion.' : validationStatus === 'pass_with_gaps' ? 'Task loop blocked because validator returned PASS_WITH_GAPS; inspect gap report and stage runtime metadata.' : 'Task loop stopped; inspect gap report and stage runtime metadata.'
   };
 }
 
-function buildLoopSteps(taskId: string, options: SingleTaskLoopOptions, task: SddTask | null): LoopAgentStep[] {
+async function reconcileDoStageEvidenceIfAvailable(projectRoot: string, input: { branch: string; runId: string; taskId: string; task: SddTask | null; routeDecision: AgentRouterDecision; options: SingleTaskLoopOptions }): Promise<SingleTaskLoopResult | null> {
+  if (input.options.implementArtifact || input.options.reviewArtifact || input.options.validationArtifact || input.options.debugArtifact || input.routeDecision.blockedReason) {
+    return null;
+  }
+  const decision = await resolveDoLifecycleDecision(projectRoot, input.branch);
+  if (!decision) {
+    return null;
+  }
+  const result = await reconcileDoCollaborationClosure(projectRoot, {
+    decision,
+    runId: input.runId,
+    allowedChangedFileRefs: input.task?.affectedFiles ?? []
+  });
+  const health = result.adjudication.health;
+  const status: SingleTaskLoopStatus = doStageLoopStatus(health, result.adjudication.rejection?.reasonCode ?? null);
+  const gaps = status === 'completed' ? [] : [taskGap(input.taskId, 'do-stage-runtime', result.adjudication.rejection?.explanation ?? `Do-stage reconciliation returned ${health}.`, result.adjudication.rejection?.requiredNextAction ?? 'Inspect .sdd/runs/<branch>/do/*.md frontmatter, hashes, review verdict, and manager closure recommendation.')];
+  const acceptedArtifacts = result.artifactRefs.map((ref) => ref.ref);
+  const validationStatus: RunState['validation']['status'] = status === 'completed' ? 'not_run' : status === 'blocked' ? 'blocked' : 'fail';
+  const state = await readRunState(projectRoot, result.runId);
+  const createdAt = new Date().toISOString();
+  await writeRunState(projectRoot, {
+    ...state,
+    status,
+    phase: 'do',
+    currentTask: input.taskId,
+    taskId: input.taskId,
+    tasks: {
+      ...state.tasks,
+      [input.taskId]: buildRuntimeTaskState(input.task, status, validationStatus, gaps, acceptedArtifacts)
+    },
+    artifacts: acceptedArtifacts.map((artifactPath) => ({ path: artifactPath, kind: artifactKind(artifactPath), task: input.taskId, agent: agentFromStageEvidenceRef(artifactPath), createdAt })),
+    validation: {
+      ...state.validation,
+      status: validationStatus
+    }
+  });
+  await appendEvent(projectRoot, result.runId, {
+    event: 'stage_collaboration_reconciled',
+    runId: result.runId,
+    summary: `Do-stage evidence reconciliation ${status} for ${input.taskId}.`,
+    data: { health, artifactRefs: acceptedArtifacts, projectionRef: result.projectionRef }
+  });
+  return {
+    runId: result.runId,
+    taskId: input.taskId,
+    status,
+    task: input.task,
+    gaps,
+    requiredArtifacts: ['.sdd/runs/<branch>/do/implementation-vN.md', '.sdd/runs/<branch>/do/code-review-vN.md', '.sdd/runs/<branch>/do/do-manager-vN.md'],
+    acceptedArtifacts,
+    routeDecision: input.routeDecision,
+    message: status === 'completed' ? 'Task loop completed through do-stage runtime reconciliation over .sdd/runs/<branch>/do/*.md evidence.' : 'Task loop stopped after do-stage runtime reconciliation; inspect stage collaboration rejection metadata.'
+  };
+}
+
+function doStageLoopStatus(health: string, reasonCode: string | null): SingleTaskLoopStatus {
+  if (health === 'ready_for_test') {
+    return 'completed';
+  }
+  if (health === 'blocked' || reasonCode === 'missing_refs') {
+    return 'blocked';
+  }
+  return 'failed';
+}
+
+
+async function resolveDoLifecycleDecision(projectRoot: string, branch: string): Promise<LifecycleRiskDecision | null> {
+  const existing = await readLifecycleRiskDecisionProjection(projectRoot, { branch });
+  return existing?.payload ?? null;
+}
+
+function agentFromStageEvidenceRef(ref: string): string {
+  const fileName = ref.split('/').pop() ?? ref;
+  if (fileName.startsWith('implementation-')) {
+    return 'implementer';
+  }
+  if (fileName.startsWith('code-review-')) {
+    return 'reviewer';
+  }
+  if (fileName.startsWith('do-manager-')) {
+    return 'do-manager';
+  }
+  return 'stage-agent';
+}
+
+function buildLoopSteps(branch: string, taskId: string, options: SingleTaskLoopOptions, task: SddTask | null): LoopAgentStep[] {
   const steps: LoopAgentStep[] = [
-    { agent: 'implementer', suppliedArtifact: options.implementArtifact, expectedArtifact: `artifacts/implement-${taskId}.md`, required: false },
-    { agent: 'reviewer', suppliedArtifact: options.reviewArtifact, expectedArtifact: `artifacts/review-${taskId}.md`, required: true }
+    { agent: 'implementer', suppliedArtifact: options.implementArtifact, expectedArtifact: toBranchStageEvidenceRef(branch, 'do', `implementation-${taskId}.md`), required: false },
+    { agent: 'reviewer', suppliedArtifact: options.reviewArtifact, expectedArtifact: toBranchStageEvidenceRef(branch, 'do', `code-review-${taskId}.md`), required: true }
   ];
   if (options.debugArtifact) {
-    steps.push({ agent: 'debugger', suppliedArtifact: options.debugArtifact, expectedArtifact: `artifacts/debug-${taskId}.md`, required: false });
+    steps.push({ agent: 'debugger', suppliedArtifact: options.debugArtifact, expectedArtifact: toBranchStageEvidenceRef(branch, 'do', `debug-${taskId}.md`), required: false });
   }
-  steps.push({ agent: 'validator', suppliedArtifact: options.validationArtifact, expectedArtifact: `artifacts/validation-${taskId}.md`, required: requiresImmediateValidation(task) });
+  steps.push({ agent: 'validator', suppliedArtifact: options.validationArtifact, expectedArtifact: toBranchStageEvidenceRef(branch, 'test', `validation-${taskId}.md`), required: requiresImmediateValidation(task) });
   return steps;
 }
 
@@ -395,8 +457,6 @@ async function persistLoopState(projectRoot: string, runId: string, input: {
   taskId: string;
   taskState: RunStateTaskRuntime;
   validationStatus: RunState['validation']['status'];
-  syncBackProposalPath: string;
-  syncBackProposalDigest: string;
   artifacts: Array<{ path: string; kind: string; task: string; agent: string }>;
 }): Promise<void> {
   const state = await readRunState(projectRoot, runId);
@@ -419,61 +479,16 @@ async function persistLoopState(projectRoot: string, runId: string, input: {
       ...state.validation,
       status: input.validationStatus,
       evidence: input.artifacts.filter((artifact) => artifact.kind === 'validation').map((artifact) => artifact.path)
-    },
-    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; payloadId: 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 digest = hashDocumentContent(content);
-  const written = await writeArtifact(projectRoot, runId, 'sync-back-proposal.md', content);
-  return { ...written, digest, payloadId: runtimeScopedId(runId, written.runRelativePath, digest) };
-}
 
-async function recordLoopSyncBackDecision(projectRoot: string, input: { runId: string; branch: string; taskId: string; status: string; proposalPath: string; proposalDigest: string; proposalPayloadId: string; reasons: string[]; payload: unknown }): Promise<void> {
-  const now = new Date().toISOString();
-  await recordRuntimeSyncBackDecision(projectRoot, {
-    decisionId: runtimeScopedId(input.runId, input.taskId, 'sync-back'),
-    runId: input.runId,
-    branch: input.branch,
-    taskId: input.taskId,
-    status: input.status,
-    proposalPath: input.proposalPath,
-    proposalDigest: input.proposalDigest,
-    proposalPayloadId: input.proposalPayloadId,
-    reasons: input.reasons,
-    createdAt: now,
-    updatedAt: now,
-    payload: input.payload
-  });
+function renderLoopGapReport(branch: string, taskId: string, gaps: SddTaskGap[]): string {
+  const gapRef = toBranchStageEvidenceRef(branch, 'do', `gap-report-${taskId}.md`);
+  return `# Gap Report ${taskId}\n\n\`\`\`sdd-result\ncontract: ${SDD_RESULT_CONTRACT}\nversion: ${SDD_RESULT_VERSION}\nagent: runtime\ntask: ${taskId}\nstatus: BLOCKED\nartifacts:\n  - ${gapRef}\n\`\`\`\n\n## Gaps\n\n${gaps.length > 0 ? gaps.map((gap) => `- [${gap.severity}] ${gap.type} ${gap.field}: ${gap.message} Recommendation: ${gap.recommendation}`).join('\n') : '- No structured gaps were provided; inspect task selection and supplied stage evidence.'}\n`;
 }
 
-function renderLoopGapReport(taskId: string, gaps: SddTaskGap[]): string {
-  return `# Gap Report ${taskId}\n\n\`\`\`sdd-result\ncontract: ${SDD_RESULT_CONTRACT}\nversion: ${SDD_RESULT_VERSION}\nagent: runtime\ntask: ${taskId}\nstatus: BLOCKED\nartifacts:\n  - artifacts/gap-report-${taskId}.md\n\`\`\`\n\n## Gaps\n\n${gaps.length > 0 ? gaps.map((gap) => `- [${gap.severity}] ${gap.type} ${gap.field}: ${gap.message} Recommendation: ${gap.recommendation}`).join('\n') : '- No structured gaps were provided; inspect task selection and supplied artifacts.'}\n`;
-}
-
-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';
-}
 
 function agentFromArtifactPath(artifactPath: string): string {
   const kind = artifactKind(artifactPath);
@@ -483,12 +498,9 @@ 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';
 }
 
-function hashDocumentContent(raw: string): string {
-  return createHash('sha256').update(raw).digest('hex');
-}