@deksden-com/dd-flow-cli 0.9.0-beta.121 → 0.9.0-beta.122

package/dist/services/vnext-code-review.js

@@ -17,6 +17,7 @@ import { addWorkBatch, prepareWorkBatch, bindStageCoordinatorWork, finishStageCo
 import { withStageSettlement, prepareFlowRunStageAttachment } from "./runs.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { acceptStageReport, prepareStageReport } from "./stage-report-renderer.js";
+import { prepareRunVerificationMatrix, acceptVerificationMatrix, commitVerificationMatrixStart, resumeVerificationMatrix, verificationMatrixInstruction, latestRunVerificationMatrix, publishVerificationMatrix } from "./verification-matrix.js";
 import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
 import { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
 import { stageGraphScope } from "./stage-work-graph.js";
@@ -50,7 +51,7 @@ export function prepareVnextCodeReviewStart(context, input) {
     const common = { projectRoot, project, run, home, root, rootWork, existingPrompt };
     if (prior && fs.existsSync(existingPrompt))
         return { ...common, resumed: true, prior, prompt: fs.readFileSync(existingPrompt, "utf8"), orchestration: readFanoutDescriptor(root) };
-    prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" });
+    const attachment = prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" });
     const mode = effectiveMode(home, run);
     const cycle = reviewCycle(run);
     const codeReportSha256 = sha256File(path.join(home, "05-code", "stage-report.json"));
@@ -61,7 +62,8 @@ export function prepareVnextCodeReviewStart(context, input) {
     const checks = mode.mode === "off" ? [] : acceptedCodeChecks(context, project.id, run.id).map(({ id, purpose }) => ({ id, purpose }));
     for (const name of ["review-context.json", ...(mode.mode === "off" ? ["decision.json"] : ["review-work-batch.json", "fanout.json"])])
         prepareOutputFile(path.join(root, name));
-    return { ...common, resumed: false, mode, cycle, codeReportSha256, groups, batch, items, template, checks };
+    const matrix = mode.mode === "off" ? null : prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "input", stageAttempt: attachment.attempt });
+    return { ...common, resumed: false, mode, cycle, codeReportSha256, groups, batch, items, template, checks, matrix };
 }
 export function startVnextCodeReview(context, input, prepared = prepareVnextCodeReviewStart(context, input)) {
     const { projectRoot, project, run, root, rootWork, existingPrompt } = prepared;
@@ -69,6 +71,8 @@ export function startVnextCodeReview(context, input, prepared = prepareVnextCode
     assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
     fs.mkdirSync(root, { recursive: true });
     if (prepared.resumed) {
+        if (effectiveMode(prepared.home, run).mode !== "off")
+            resumeVerificationMatrix(context, project.id, run.id, stage);
         const externalContext = applyExternalStageContext({ stageRoot: root, promptPath: existingPrompt, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         const binding = bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath: existingPrompt, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
         const prompt = fs.readFileSync(existingPrompt, "utf8");
@@ -76,6 +80,7 @@ export function startVnextCodeReview(context, input, prepared = prepareVnextCode
         return { ok: true, resumed: true, run_id: run.id, stage, stage_status: prepared.prior, id: binding.work_session_id, prompt_path: existingPrompt, worker_prompt_markdown: prompt, ...(externalContext ? { external_context: externalContext } : {}), ...(orchestration ? { orchestration } : {}), next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
     }
     const { mode, cycle, groups, batch, items, template, checks, codeReportSha256 } = prepared;
+    prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" }, true);
     const aspectMapChecksums = mode.mode === "off" ? [] : fs.readdirSync(path.join(run.run_root, "03-plan"), { withFileTypes: true })
         .filter(entry => entry.isDirectory() && fs.existsSync(path.join(run.run_root, "03-plan", entry.name, "aspect-map.json")))
         .map(entry => ({ path: `03-plan/${entry.name}/aspect-map.json`, sha256: sha256File(path.join(run.run_root, "03-plan", entry.name, "aspect-map.json")) }))
@@ -90,18 +95,21 @@ export function startVnextCodeReview(context, input, prepared = prepareVnextCode
         fs.writeFileSync(promptPath, prompt);
         const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         const binding = bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-        attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" });
+        const attachmentInput = { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" };
+        attachFlowRunStage(context, attachmentInput, prepareFlowRunStageAttachment(context, attachmentInput));
         return { ok: true, run_id: run.id, stage, mode: mode.mode, mode_source: mode.source, id: binding.work_session_id, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
     }
     const batchFile = path.join(root, "review-work-batch.json");
     fs.writeFileSync(batchFile, `${JSON.stringify(batch, null, 2)}\n`);
-    const prompt = `${orchestratorPrompt(context, { projectRoot, run, root, rootWork, mode: mode.mode, groups, template, checks })}\n${stageLifecycleInstruction}\n`;
+    const prompt = `${orchestratorPrompt(context, { projectRoot, run, root, rootWork, mode: mode.mode, groups, template, checks })}\n${stageLifecycleInstruction}\n${verificationMatrixInstruction(prepared.matrix?.metadata ?? null, prepared.home, "reviewing whether current evidence proves the accepted obligations")}\n`;
     fs.writeFileSync(promptPath, prompt);
     const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     const binding = bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
     const registered = addWorkBatch(context, { parentWorkId: rootWork.work_id, value: batch, prepared: items, stage, cycle });
     const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true, scope: stageGraphScope(context, project.id, run.id, stage) });
-    attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1", inputSha256: sha256Value(JSON.stringify({ batch: sha256File(batchFile), aspect_maps: aspectMapChecksums })) });
+    const attachmentInput = { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1", inputSha256: sha256Value(JSON.stringify({ batch: sha256File(batchFile), aspect_maps: aspectMapChecksums })) };
+    const attachment = prepareFlowRunStageAttachment(context, attachmentInput);
+    commitVerificationMatrixStart(context, prepared.matrix, () => attachFlowRunStage(context, attachmentInput, attachment));
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "code_review_started", work_id: rootWork.work_id, mode: mode.mode, mode_source: mode.source, groups, registered });
     return { ok: true, run_id: run.id, stage, mode: mode.mode, mode_source: mode.source, id: binding.work_session_id, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), orchestration, review: { groups, works: registered }, next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
 }
@@ -208,7 +216,8 @@ export async function finishVnextCodeReview(context, input) {
             fs.writeFileSync(temporary, `${JSON.stringify({ ...reviewContext, accepted_decision: decision }, null, 2)}\n`);
             fs.renameSync(temporary, contextFile);
             const repair = addVnextCodeReviewRepair(context, { projectRoot, runId: run.id, findingIds: fixIds, checkRefsByFinding, decisionReasonsByFinding: Object.fromEntries(canonical.decision.findings.map((item) => [item.finding_ref, item.reason])), objective: `Resolve accepted CODE-REVIEW findings: ${fixIds.join(", ")}` });
-            return { ok: true, run_id: run.id, stage, outcome: "repair_required", repair, instruction: "The repair Work is already registered: do not invoke its start_command in this coordinator Session. End this Turn so the controller can launch it in a fresh child Session. When it completes, invoke next.finish_command; this review cycle uses the decision already accepted by the runtime.", next: { finish_command: finishCommand(context, run.id, projectRoot, decisionFile) } };
+            const retained = latestRunVerificationMatrix(context, project.id, run.id, stage, "input");
+            return { ok: true, run_id: run.id, stage, outcome: "repair_required", repair, ...(retained ? { verification_matrix: retained.metadata } : {}), instruction: `The repair Work is already registered: do not invoke its start_command in this coordinator Session. End this Turn so the controller can launch it in a fresh child Session. When it completes, invoke next.finish_command; this review cycle uses the decision already accepted by the runtime.\n${verificationMatrixInstruction(retained?.metadata ?? null, home, "the accepted review decision and repair")}`, next: { finish_command: finishCommand(context, run.id, projectRoot, decisionFile) } };
         }
         repairs = reviewRepairWorks(context, project.id, run.id, root, cycle);
         const incompleteRepairs = repairs.filter((work) => work.status !== "completed");
@@ -224,16 +233,21 @@ export async function finishVnextCodeReview(context, input) {
         appendFlowRunTimelineEvent(context, project.id, run.id, { type: "check_retry_requested", check_receipt_id: input.retryCheckId, stage, reason: input.retryReason ?? "operator retry" });
     }
     const receipts = await runCodeChecks(context, { projectId: project.id, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, artifactDir: stageDir, scope: "aggregate", checks: finalChecks, ...(input.retryCheckId ? { retryReceiptId: input.retryCheckId, retryReason: input.retryReason } : {}), ...(input.progress ? { progress: input.progress } : {}) });
+    const matrix = prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "output", receipts, semanticFile: decisionFile });
     const failed = receipts.filter((receipt) => receipt.status !== "passed");
-    if (failed.length)
+    if (failed.length) {
+        context.db.writeTransaction(() => acceptVerificationMatrix(context, matrix));
+        publishVerificationMatrix(context, matrix);
         throw new AppError("code_review_gate_failed", "CODE-REVIEW repair changed the project but the aggregate gate failed", 2, {
             failures: failed,
             outcome: "repair_required",
             retry_after_workspace_change: true,
             workspace_fingerprint: failed[0].workspace_fingerprint,
             continuation: registerAggregateCodeRepair(context, { projectRoot, runId: run.id, stage, failures: failed, checks: finalChecks, generation }),
-            instruction: "Repair Work is already registered. End this Turn so the controller can launch a fresh child; after it finishes, repeat finish with the already accepted review decision. Do not redo review."
+            ...(matrix ? { verification_matrix: matrix.metadata } : {}),
+            instruction: `Repair Work is already registered. End this Turn so the controller can launch a fresh child; after it finishes, repeat finish with the already accepted review decision. Do not redo review.\n${verificationMatrixInstruction(matrix?.metadata ?? null, home, "the current aggregate failures and repair")}`
         });
+    }
     const stopTarget = executionStopTarget(run);
     const nextAction = stopTarget === "merge_completed" ? "start_merge" : "code_review_completed";
     const now = context.now();
@@ -245,6 +259,8 @@ export async function finishVnextCodeReview(context, input) {
     let mergeRequest = null;
     assertRunMutationAllowed(context, project.id, run.id, generation);
     const prepareMerge = nextAction === "start_merge" ? prepareVnextMergeRequest(context, { projectRoot, runId: run.id, acceptedPaths }) : null;
+    if (matrix)
+        Object.assign(report.semantic, { verification_matrix: matrix.metadata });
     const preparedReport = prepareStageReport(report);
     const completionInput = { projectRoot, runId: run.id, stage, status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@1", report: "stage-report.md", stageReport: "stage-report.html", dataSha256: preparedReport.sha256, git: report.mechanical.git };
     withStageSettlement(context, () => {
@@ -256,6 +272,7 @@ export async function finishVnextCodeReview(context, input) {
         }
         mergeRequest = prepareMerge?.() ?? null;
         const preparedCompletion = prepareFlowRunStageCompletion(context, completionInput);
+        acceptVerificationMatrix(context, matrix);
         acceptStageReport(context, { projectId: project.id, runId: run.id, stage, root, prepared: preparedReport });
         completeFlowRunStage(context, completionInput, preparedCompletion);
         appendFlowRunTimelineEvent(context, project.id, run.id, { type: "code_review_completed", work_id: rootWork.work_id, outcome });

package/dist/services/vnext-code.js

@@ -25,6 +25,7 @@ import { applyExternalStageContext, prepareExternalStageContext } from "./stage-
 import { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
 import { assertRunMutationAllowed } from "./run-recovery.js";
 import { prepareJsonSchema, prepareOutputFile } from "../cli/input-preparation.js";
+import { prepareRunVerificationMatrix, acceptVerificationMatrix, commitVerificationMatrixStart, resumeVerificationMatrix, verificationMatrixInstruction, publishVerificationMatrix, latestRunVerificationMatrix } from "./verification-matrix.js";
 const stage = "code";
 const stageDir = vnextStageDirectory("code");
 /** A controller prepares slow, deterministic project tooling before it asks an
@@ -63,8 +64,7 @@ export function prepareVnextCodeStart(context, input) {
     if (existingStage && fs.existsSync(existingPrompt)) {
         return { ...common, resumed: true, existingStage, prompt: fs.readFileSync(existingPrompt, "utf8"), orchestration: readFanoutDescriptor(existingRoot) };
     }
-    if (!sourceRepairAttempt)
-        prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" });
+    const attachment = sourceRepairAttempt ? null : prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" });
     const batch = path.join(home, "03-plan", "code-work-batch.json");
     const handoffFailures = validateVnextCodeHandoff(context, {
         projectRoot,
@@ -86,23 +86,27 @@ export function prepareVnextCodeStart(context, input) {
     validateWorkBatchFile(batch);
     const template = fs.readFileSync(path.join(run.workspace_root, ".memory-bank", "dd-flow", "vnext", "code.md"), "utf8");
     const variables = getFlowRunVariables(context, { projectRoot, runId: run.id });
-    return { ...common, resumed: false, template, capacity: variables.variables?.["runtime.subagent.available_slots"] };
+    const matrix = prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "input", completeness: "declared", ...(attachment ? { stageAttempt: attachment.attempt } : {}) });
+    return { ...common, resumed: false, template, capacity: variables.variables?.["runtime.subagent.available_slots"], matrix };
 }
 export async function startVnextCode(context, input, prepared = prepareVnextCodeStart(context, input)) {
     const { projectRoot, project, run, root, promptPath, rootWork, sourceRepairAttempt } = prepared;
     assertRunMutationAllowed(context, project.id, run.id);
     assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
     if (prepared.resumed) {
+        resumeVerificationMatrix(context, project.id, run.id, stage);
         const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
         const orchestration = prepared.orchestration ?? writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true, scope: stageGraphScope(context, project.id, run.id, stage) });
         return { ok: true, resumed: true, run_id: run.id, stage, stage_status: prepared.existingStage, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), orchestration, graph: codeWorkGraph(context, project.id, run.id), next: { refresh_graph_command: runtimeCommand(context, ["work", "ls", "--run", run.id, "--ready", "--project-root", projectRoot, "--json"]), finish_command: finishCommand(context, input.runId, projectRoot, path.join(root, "code-verification.json")) } };
     }
+    if (!sourceRepairAttempt)
+        prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" }, true);
     fs.mkdirSync(root, { recursive: true });
     const readiness = await ensureCodeWorkspaceReady(context, project.id, run, root, [], input.progress);
     // Graph rendering may issue managed child commands; it belongs to execution.
     const graph = codeWorkGraph(context, project.id, run.id);
-    const prompt = `${coordinatorPrompt(context, { projectRoot, run, root, rootWork, readiness, template: prepared.template, capacity: prepared.capacity, graph })}\n${stageLifecycleInstruction}\n`;
+    const prompt = `${coordinatorPrompt(context, { projectRoot, run, root, rootWork, readiness, template: prepared.template, capacity: prepared.capacity, graph })}\n${stageLifecycleInstruction}\n${verificationMatrixInstruction(prepared.matrix?.metadata ?? null, prepared.home, "implementation and code-verification.json")}\n`;
     fs.writeFileSync(promptPath, prompt);
     const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     const binding = bindStageCoordinatorWork(context, {
@@ -114,15 +118,19 @@ export async function startVnextCode(context, input, prepared = prepareVnextCode
         ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {})
     });
     if (!sourceRepairAttempt) {
-        attachFlowRunStage(context, {
+        const attachmentInput = {
             projectRoot,
             runId: input.runId,
             stage,
             dir: stageDir,
             status: "running",
             dataSchemaId: "dd-flow/stage-report@1"
-        });
+        };
+        const attachment = prepareFlowRunStageAttachment(context, attachmentInput);
+        commitVerificationMatrixStart(context, prepared.matrix, () => attachFlowRunStage(context, attachmentInput, attachment));
     }
+    else
+        commitVerificationMatrixStart(context, prepared.matrix, () => undefined);
     const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true, scope: stageGraphScope(context, project.id, run.id, stage) });
     appendFlowRunTimelineEvent(context, project.id, input.runId, { type: "code_started", work_id: rootWork.work_id, graph });
     return {
@@ -180,8 +188,10 @@ export async function finishVnextCode(context, input) {
     // Reject a malformed semantic receipt before running the expensive gate.
     const verification = input.verification ?? verificationForFinish(context, { file: input.verificationFile, projectRoot: run.workspace_root, runId: run.id, runRoot: home });
     validateSchema({ schemaName: "code-verification", file: input.verificationFile, data: verification, projectRoot: run.workspace_root, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: home });
+    const retainedMatrix = latestRunVerificationMatrix(context, project.id, run.id, stage);
+    const retainedMatrixInstruction = verificationMatrixInstruction(retainedMatrix?.metadata ?? null, home, "the current semantic verification and repair");
     if (verification.verdict === "blocked") {
-        return { ok: true, run_id: run.id, stage, outcome: "blocked", verification, instruction: "CODE remains running. Resolve the stated external or user-input blocker in this same coordinator session, update code-verification.json, then invoke this same stage finish command again." };
+        return { ok: true, run_id: run.id, stage, outcome: "blocked", verification, ...(retainedMatrix ? { verification_matrix: retainedMatrix.metadata } : {}), instruction: `CODE remains running. Resolve the stated external or user-input blocker in this same coordinator session, update code-verification.json, then invoke this same stage finish command again.\n${retainedMatrixInstruction}` };
     }
     if (verification.verdict === "passed" && verification.unresolved.length > 0) {
         throw new AppError("verification_contradictory", "A passed CODE verification cannot contain unresolved obligations", 2, { unresolved: verification.unresolved });
@@ -196,7 +206,7 @@ export async function finishVnextCode(context, input) {
             verification,
             objective: verification.summary
         });
-        return { ok: true, run_id: run.id, stage, outcome: "repair_required", verification, repair, instruction: "The semantic verification is not accepted. The repair Work is already registered: do not invoke its start_command in this coordinator Session. End this Turn so the controller can launch it in a fresh child Session. After that Work completes, update code-verification.json and invoke this same stage finish command again." };
+        return { ok: true, run_id: run.id, stage, outcome: "repair_required", verification, repair, ...(retainedMatrix ? { verification_matrix: retainedMatrix.metadata } : {}), instruction: `The semantic verification is not accepted. The repair Work is already registered: do not invoke its start_command in this coordinator Session. End this Turn so the controller can launch it in a fresh child Session. After that Work completes, update code-verification.json and invoke this same stage finish command again.\n${retainedMatrixInstruction}` };
     }
     const checks = finalCodeCheckDeclarations(run.workspace_root, works.flatMap((work) => packet(work)?.checks ?? []));
     if (input.retryCheckId) {
@@ -209,7 +219,11 @@ export async function finishVnextCode(context, input) {
         ...(input.progress ? { progress: input.progress } : {})
     });
     const failed = receipts.filter((receipt) => receipt.status !== "passed");
+    const matrix = prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "output", receipts, semanticFile: input.verificationFile });
+    const matrixInstruction = matrix ? verificationMatrixInstruction(matrix.metadata, home, "semantic verification in code-verification.json") : "";
     if (failed.length) {
+        context.db.writeTransaction(() => acceptVerificationMatrix(context, matrix));
+        publishVerificationMatrix(context, matrix);
         const continuation = registerAggregateCodeRepair(context, { projectRoot, runId: run.id, stage, failures: failed, checks, generation });
         throw new AppError("code_gate_failed", "CODE remains running because the aggregate project gate failed", 2, {
             failures: failed,
@@ -217,15 +231,19 @@ export async function finishVnextCode(context, input) {
             retry_after_workspace_change: true,
             workspace_fingerprint: failed[0].workspace_fingerprint,
             continuation,
-            instruction: "Repair Work is already registered. End this coordinator Turn; the controller will launch a fresh child. After it completes, update semantic verification and finish the Stage."
+            ...(matrix ? { verification_matrix: matrix.metadata, verification_matrix_instruction: matrixInstruction } : {}),
+            instruction: `Repair Work is already registered. End this coordinator Turn; the controller will launch a fresh child. After it completes, update semantic verification and finish the Stage.\n${matrixInstruction}`
         });
     }
     const finalReceipts = receipts;
     if (verification.verdict === "needs_checks") {
+        context.db.writeTransaction(() => acceptVerificationMatrix(context, matrix));
+        publishVerificationMatrix(context, matrix);
         return { ok: true, run_id: run.id, stage, outcome: "verification_required", verification,
+            ...(matrix ? { verification_matrix: matrix.metadata, verification_matrix_instruction: matrixInstruction } : {}),
             receipts: finalReceipts.map(receipt => ({ id: receipt.id, receipt_path: receipt.receipt_path, input_hash: receipt.input_hash, status: receipt.status })),
             next: { kind: "verification_required", finish_command: finishCommand(context, run.id, projectRoot, input.verificationFile) },
-            instruction: "Aggregate receipts are available. Keep CODE running. Inspect them, update code-verification.json to passed or needs_repair, then invoke only the issued successor finish_command. A material document change belongs to the registered fresh repair Work, not this coordinator Session." };
+            instruction: `Aggregate receipts are available. Keep CODE running. Inspect them, update code-verification.json to passed or needs_repair, then invoke only the issued successor finish_command. A material document change belongs to the registered fresh repair Work, not this coordinator Session.\n${matrixInstruction}` };
     }
     const projectedVerification = verificationProjection(works, finalReceipts, { historicalReceipts: finalReceipts, runId: run.id, runHome: home });
     const unresolvedAcceptance = (projectedVerification.acceptance ?? []).filter((item) => item.status === "unresolved");
@@ -278,6 +296,8 @@ export async function finishVnextCode(context, input) {
     let mergeRequest = null;
     assertRunMutationAllowed(context, project.id, run.id, generation);
     const prepareMerge = next === "start_merge" ? prepareVnextMergeRequest(context, { projectRoot, runId: run.id, acceptedPaths: changedPaths }) : null;
+    if (matrix)
+        Object.assign(report.semantic, { verification_matrix: matrix.metadata });
     const preparedReport = prepareStageReport(report);
     const completionInput = { projectRoot, runId: run.id, stage, status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@1", report: "stage-report.md", stageReport: "stage-report.html", dataSha256: preparedReport.sha256, git: report.mechanical.git };
     withStageSettlement(context, () => {
@@ -288,6 +308,7 @@ export async function finishVnextCode(context, input) {
         }
         mergeRequest = prepareMerge?.() ?? null;
         const preparedCompletion = prepareFlowRunStageCompletion(context, completionInput);
+        acceptVerificationMatrix(context, matrix);
         acceptStageReport(context, { projectId: project.id, runId: run.id, stage, root, prepared: preparedReport });
         completeFlowRunStage(context, completionInput, preparedCompletion);
         const rootWork = requireRootWork(context, project.id, run.id);

package/dist/services/vnext-merge.js

@@ -23,6 +23,7 @@ import { ensureLaneWorkspace, prepareLaneWorkspace, heartbeatLaneLock, releaseLa
 import { assertRunMutationAllowed } from "./run-recovery.js";
 import { assertStageStartHookEvent } from "./hooks.js";
 import { prepareJsonSchema, prepareOutputFile } from "../cli/input-preparation.js";
+import { prepareRunVerificationMatrix, acceptVerificationMatrix, commitVerificationMatrixStart, resumeVerificationMatrix, verificationMatrixInstruction, latestRunVerificationMatrix, publishVerificationMatrix } from "./verification-matrix.js";
 const stage = "merge";
 const stageDir = vnextStageDirectory(stage);
 export function isVnextMergeRun(context, input) {
@@ -133,8 +134,7 @@ export function prepareVnextMergeStart(context, input) {
     if (!work || work.project_id !== project.id || work.run_id !== run.id || !["created", "running"].includes(work.status))
         throw new AppError("runtime_artifact_invalid", "MERGE executor Work is missing or not startable", 1, { work_id: request.executor_work_id });
     const index = JSON.parse(run.index_json);
-    if (!index.stage_runs?.some(entry => entry.stage === stage))
-        prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@2" });
+    const attachment = ["active", "action_required"].includes(request.status) && index.stage_runs?.some(entry => entry.stage === stage) ? null : prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@2" });
     prepareLaneWorkspace(context, { projectRoot, lane: "merge", workspacePath: request.target_workspace, branch: request.target_branch });
     const checks = effectiveMergeChecks(run, request), settings = executionSettings(run);
     const existingPrompt = ["active", "action_required"].includes(request.status) && fs.existsSync(promptPath) ? fs.readFileSync(promptPath, "utf8") : null;
@@ -142,15 +142,21 @@ export function prepareVnextMergeStart(context, input) {
         prepareOutputFile(promptPath);
     if (input.externalContext)
         prepareExternalStageContext({ stageRoot: root, loaded: input.externalContext });
-    return { ...common, terminal: false, root, workRoot, resultPath, promptPath, checks, settings, existingPrompt };
+    const matrix = existingPrompt !== null ? latestRunVerificationMatrix(context, project.id, run.id, stage, "input") : prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "input", ...(attachment ? { stageAttempt: attachment.attempt } : {}) });
+    return { ...common, terminal: false, root, workRoot, resultPath, promptPath, checks, settings, existingPrompt, matrix };
 }
 export async function startVnextMerge(context, input, prepared = prepareVnextMergeStart(context, input)) {
     const { projectRoot, project, run, request, generation } = prepared;
     if (prepared.terminal)
         return requestView(context, request);
     const { root, workRoot, resultPath, promptPath, checks, settings, existingPrompt } = prepared;
+    if (existingPrompt !== null)
+        resumeVerificationMatrix(context, project.id, run.id, stage);
     assertRunMutationAllowed(context, project.id, run.id, generation);
     assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    const alreadyAttached = ["active", "action_required"].includes(request.status) && (JSON.parse(requireRun(context, project.id, run.id).index_json).stage_runs ?? []).some((item) => item.stage === stage);
+    if (!alreadyAttached)
+        prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@2" }, true);
     fs.mkdirSync(workRoot, { recursive: true });
     ensureLaneWorkspace(context, { projectRoot, lane: "merge", workspacePath: request.target_workspace, branch: request.target_branch });
     const lane = await waitAcquireLaneLock(context, { projectRoot, lane: "merge", workerId: request.executor_work_id, workspacePath: request.target_workspace, timeoutSeconds: 3600, pollIntervalSeconds: 15, ttlSeconds: 7200, reason: `MERGE ${request.merge_request_id}`, ...(input.progress ? { progress: input.progress } : {}) });
@@ -163,11 +169,13 @@ export async function startVnextMerge(context, input, prepared = prepareVnextMer
             const binding = pendingWork?.status === "created"
                 ? startStageCoordinatorWork(context, { workId: request.executor_work_id, hookEventId: input.hookEventId, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) })
                 : bindStageCoordinatorWork(context, { workId: request.executor_work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-            const prompt = existingPrompt ?? `${mergePrompt(context, { run, request, resultPath, projectRoot }, checks, settings)}\n${stageLifecycleInstruction}\n`;
+            const prompt = existingPrompt ?? `${mergePrompt(context, { run, request, resultPath, projectRoot }, checks, settings)}\n${stageLifecycleInstruction}\n${verificationMatrixInstruction(prepared.matrix?.metadata ?? null, run.run_root, "MERGE source/target verification and residual-risk assessment")}\n`;
             if (existingPrompt === null)
                 fs.writeFileSync(promptPath, prompt);
             const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
-            ensureMergeStageAttached(context, run, projectRoot);
+            const attachmentInput = { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@2" };
+            const attachment = alreadyAttached ? null : prepareFlowRunStageAttachment(context, attachmentInput);
+            commitVerificationMatrixStart(context, prepared.matrix, () => attachment ? attachFlowRunStage(context, attachmentInput, attachment) : undefined);
             return startPacket(context, run, request, binding, promptPath, resultPath, prompt, projectRoot, checks, externalContext);
         }
         const current = requireRequest(context, request.merge_request_id);
@@ -182,11 +190,13 @@ export async function startVnextMerge(context, input, prepared = prepareVnextMer
         if (claimed.changes !== 1 && requireRequest(context, current.merge_request_id).status !== "active")
             throw new AppError("merge_claim_conflict", "MERGE request could not acquire the integration lane", 1, { merge_request_id: current.merge_request_id });
         const started = startStageCoordinatorWork(context, { workId: current.executor_work_id, hookEventId: input.hookEventId, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-        const prompt = `${mergePrompt(context, { run, request: requireRequest(context, current.merge_request_id), resultPath, projectRoot }, checks, settings)}\n${stageLifecycleInstruction}\n`;
+        const prompt = `${mergePrompt(context, { run, request: requireRequest(context, current.merge_request_id), resultPath, projectRoot }, checks, settings)}\n${stageLifecycleInstruction}\n${verificationMatrixInstruction(prepared.matrix?.metadata ?? null, run.run_root, "MERGE source/target verification and residual-risk assessment")}\n`;
         fs.writeFileSync(promptPath, prompt);
         const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         context.db.run("UPDATE work_sessions SET prompt_path = ?, result_path = ?, updated_at = ? WHERE work_id = ? AND status = 'running'", [promptPath, resultPath, context.now(), current.executor_work_id]);
-        attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@2" });
+        const attachmentInput = { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@2" };
+        const attachment = alreadyAttached ? null : prepareFlowRunStageAttachment(context, attachmentInput);
+        commitVerificationMatrixStart(context, prepared.matrix, () => attachment ? attachFlowRunStage(context, attachmentInput, attachment) : undefined);
         appendFlowRunTimelineEvent(context, project.id, run.id, { type: "merge_started", merge_request_id: current.merge_request_id, work_id: current.executor_work_id, target_head: targetHead });
         return startPacket(context, run, current, started, promptPath, resultPath, prompt, projectRoot, checks, externalContext);
     }
@@ -323,6 +333,11 @@ export async function finishVnextMerge(context, input, prepared = prepareVnextMe
     verifyLocalDelivery(request);
     context.db.run("UPDATE merge_requests SET checkpoint = 'delivered', updated_at = ? WHERE merge_request_id = ?", [context.now(), request.merge_request_id]);
     request = requireRequest(context, request.merge_request_id);
+    const matrix = prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "output", receipts, semanticFile: prepared.resultPath });
+    // Retain exact bounded sources before deleting the feature checkout. A
+    // crash here recovers presentation from packets, never repeats the checks.
+    context.db.writeTransaction(() => acceptVerificationMatrix(context, matrix));
+    publishVerificationMatrix(context, matrix);
     performConfiguredCleanup(run, request);
     const acceptedResult = prepared.result.text;
     const executor = context.db.get("SELECT status, result FROM works WHERE work_id = ?", [request.executor_work_id]);
@@ -338,6 +353,8 @@ export async function finishVnextMerge(context, input, prepared = prepareVnextMe
     const root = path.join(requireHome(run), stageDir);
     const retainedReport = completedMergeReport(context, run, root);
     const report = retainedReport ?? mergeReport(context, run, requireRequest(context, request.merge_request_id), semantic, receipts);
+    if (matrix)
+        Object.assign(report.semantic, { verification_matrix: matrix.metadata });
     if (!retainedReport)
         commitMergeStageReport(context, run, projectRoot, root, report);
     const rootWork = requireRootWork(context, project.id, run.id);
@@ -409,10 +426,16 @@ function completedMergeReport(context, run, root) {
     return JSON.parse(fs.readFileSync(file, "utf8"));
 }
 function commitMergeStageReport(context, run, projectRoot, root, report) {
+    const matrix = latestRunVerificationMatrix(context, run.project_id, run.id, stage, "output");
+    if (matrix)
+        Object.assign(report.semantic, { verification_matrix: matrix.metadata });
+    if (JSON.parse(run.index_json).verification_matrix_contract && !matrix)
+        throw new AppError("verification_matrix_packet_missing", "Completed marked MERGE lacks its retained final matrix", 1, { run_id: run.id });
     const preparedReport = prepareStageReport(report);
     const completion = { projectRoot, runId: run.id, stage, status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@2", report: "stage-report.md", stageReport: "stage-report.html", dataSha256: preparedReport.sha256 };
     const preparedCompletion = prepareFlowRunStageCompletion(context, completion);
     withStageSettlement(context, () => {
+        acceptVerificationMatrix(context, matrix);
         acceptStageReport(context, { projectId: run.project_id, runId: run.id, stage, root, prepared: preparedReport });
         completeFlowRunStage(context, completion, preparedCompletion);
     });

package/dist/services/vnext-plan-review.js

@@ -22,6 +22,7 @@ import { prepareJsonSchema, prepareOutputFile } from "../cli/input-preparation.j
 import { getStageFanoutCapacity, readFanoutDescriptor, subagentCapacityKey, writeFanoutDescriptor } from "./vnext-fanout.js";
 import { stageGraphScope } from "./stage-work-graph.js";
 import { stageLifecycleInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { prepareRunVerificationMatrix, acceptVerificationMatrix, commitVerificationMatrixStart, resumeVerificationMatrix, verificationMatrixInstruction, latestRunVerificationMatrix } from "./verification-matrix.js";
 const stage = "plan-review";
 const stageDir = vnextStageDirectory(stage);
 const reviewTask = "Independently review the accepted PLAN and decide whether CODE may open.";
@@ -59,14 +60,15 @@ export function prepareVnextPlanReviewStart(context, input) {
     if (input.externalContext)
         prepareExternalStageContext({ stageRoot: root, loaded: input.externalContext });
     prepareOutputFile(path.join(root, "stage-prompt.md"));
-    const active = { ...common, requested, protocolIds, groups, effective, workspaceRoute, batchChecksum, planChecksum };
+    const attachment = existing?.status === "running" ? null : prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/plan-review-decision@3" });
+    const matrix = existing?.status === "running" ? latestRunVerificationMatrix(context, project.id, run.id, stage, "input") : prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "input", ...(attachment ? { stageAttempt: attachment.attempt } : {}) });
+    const active = { ...common, requested, protocolIds, groups, effective, workspaceRoute, batchChecksum, planChecksum, matrix };
     if (existing?.status === "running") {
         const orchestration = readFanoutDescriptor(root);
         if (!orchestration)
             prepareOutputFile(path.join(root, "fanout.json"));
         return { ...active, state: "resumed", workId: existing.work_id, prompt: fs.readFileSync(path.join(root, "stage-prompt.md"), "utf8"), orchestration };
     }
-    prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/plan-review-decision@3" });
     const rootWork = rootWorkId(context, project.id, run.id);
     if (effective === "off") {
         const failures = validateVnextPlanArtifacts(context, { projectRoot, workspaceRoot: run.workspace_root, runId: run.id, home, protocols: protocolIds });
@@ -85,7 +87,8 @@ export function prepareVnextPlanReviewStart(context, input) {
         }
         for (const name of ["stage-report.json", "stage-report.md", "stage-report.html"])
             prepareOutputFile(path.join(root, name));
-        return { ...active, state: "off", rootWork, codeItems };
+        const outputMatrix = prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "output", ...(attachment ? { stageAttempt: attachment.attempt } : {}) });
+        return { ...active, state: "off", rootWork, codeItems, outputMatrix };
     }
     const template = read(path.join(projectRoot, ".memory-bank", "dd-flow", "vnext", "plan-review.md"));
     const revision = currentPlanRevision(home, run.workspace_root);
@@ -103,11 +106,13 @@ export function startVnextPlanReview(context, input, prepared = prepareVnextPlan
     }
     const { requested, effective, groups, batchChecksum, planChecksum, workspaceRoute } = prepared;
     if (prepared.state === "resumed") {
+        resumeVerificationMatrix(context, project.id, run.id, stage);
         const promptPath = path.join(root, "stage-prompt.md");
         const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         return { ...preparedExisting(context, { projectRoot, projectId: project.id, run, root, workId: prepared.workId, hookEventId: input.hookEventId, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}), requested, effective, groups, batchChecksum, planChecksum, orchestration: prepared.orchestration }), ...(externalContext ? { external_context: externalContext } : {}) };
     }
     ensureWorkRegistry(context);
+    prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/plan-review-decision@3" }, true);
     fs.mkdirSync(root, { recursive: true });
     const now = context.now(), rootWork = prepared.rootWork;
     if (prepared.state === "off") {
@@ -115,12 +120,17 @@ export function startVnextPlanReview(context, input, prepared = prepareVnextPlan
         fs.writeFileSync(promptPath, "PLAN-REVIEW is disabled by the frozen RUN configuration.\n");
         const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         bindStageCoordinatorWork(context, { workId: rootWork, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-        attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/plan-review-decision@3" });
+        const attachmentInput = { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/plan-review-decision@3" };
+        const attachment = prepareFlowRunStageAttachment(context, attachmentInput);
+        commitVerificationMatrixStart(context, prepared.matrix, () => attachFlowRunStage(context, attachmentInput, attachment));
         const reportGit = gitFacts(run.workspace_root);
         const nextCommand = codeCommand(context, run.id, projectRoot);
         return withStageSettlement(context, () => {
             const registered = addWorkBatch(context, { parentWorkId: rootWork, prepared: prepared.codeItems, stage: "code" });
             const report = reportFor(context, { run, mode: effective, requested, outcome: "off", groups: [], batchChecksum, planChecksum, code: registered, now, projectRoot, flow: flowCommand(context), git: reportGit, nextCommand });
+            acceptVerificationMatrix(context, prepared.outputMatrix);
+            if (prepared.outputMatrix)
+                Object.assign(report.semantic, { verification_matrix: prepared.outputMatrix.metadata });
             const preparedReport = prepareStageReport(report);
             acceptStageReport(context, { projectId: project.id, runId: run.id, stage, root, prepared: preparedReport });
             const completionInput = { projectRoot, runId: run.id, stage, status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@1", report: "stage-report.md", stageReport: "stage-report.html", dataSha256: preparedReport.sha256, git: reportGit };
@@ -133,7 +143,7 @@ export function startVnextPlanReview(context, input, prepared = prepareVnextPlan
     const workId = nextWorkId(context, project.id, "plan-review");
     context.db.run("INSERT INTO works (work_id, project_id, run_id, parent_work_id, task, launch_policy, result_schema, depends_on_json, status, result, started_at, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, ?, 'reuse_allowed', NULL, '[]', 'running', NULL, ?, ?, ?, NULL)", [workId, project.id, run.id, rootWork, reviewTask, now, now, now]);
     const pauseCommand = stagePauseCommand(context, { runId: run.id, stage, workId, projectRoot });
-    const prompt = `${orchestratorPrompt(context, { projectRoot, run, home, root, workId, requested, effective, groups, batchChecksum, planChecksum, workspaceRoute, pauseCommand, pauseCommandTemplate: stagePauseCommandTemplate(pauseCommand), template: prepared.template, revision: prepared.revision, capacity: prepared.capacity })}\n${stageLifecycleInstruction}\n`;
+    const prompt = `${orchestratorPrompt(context, { projectRoot, run, home, root, workId, requested, effective, groups, batchChecksum, planChecksum, workspaceRoute, pauseCommand, pauseCommandTemplate: stagePauseCommandTemplate(pauseCommand), template: prepared.template, revision: prepared.revision, capacity: prepared.capacity })}\n${stageLifecycleInstruction}\n${verificationMatrixInstruction(prepared.matrix?.metadata ?? null, home, "reviewing PLAN coverage, fixtures and proof limits")}\n`;
     const promptPath = path.join(root, "stage-prompt.md");
     fs.writeFileSync(promptPath, prompt);
     const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
@@ -146,7 +156,9 @@ export function startVnextPlanReview(context, input, prepared = prepareVnextPlan
         fs.rmSync(promptPath, { force: true });
         throw error;
     }
-    attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/plan-review-decision@3" });
+    const attachmentInput = { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/plan-review-decision@3" };
+    const attachment = prepareFlowRunStageAttachment(context, attachmentInput);
+    commitVerificationMatrixStart(context, prepared.matrix, () => attachFlowRunStage(context, attachmentInput, attachment));
     markReviewPending(home, groups);
     const workSessionId = String(binding.work_session_id);
     const sessionId = String(binding.session_id);
@@ -307,13 +319,17 @@ function finishPlanReviewOwned(context, input) {
     const codeItems = prepareWorkBatch(context, { parentWorkId: codeParentId, file: batch, stage: "code" });
     const reportGit = gitFacts(run.workspace_root);
     const nextCommand = codeCommand(context, run.id, projectRoot);
+    const matrix = prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "output", semanticFile: decisionPath });
     return withStageSettlement(context, () => {
         const registered = addWorkBatch(context, { parentWorkId: codeParentId, prepared: codeItems, stage: "code" });
         const now = context.now();
         settleReviewParent(context, { projectRoot, projectId: project.id, runId: run.id, parentWorkId: parent.work_id, status: "completed", result: decision.summary, reason: "plan_review_completed", resultPath: path.join(root, "stage-report.json") });
         const report = reportFor(context, { run, mode: contextFile.system?.effective_mode ?? "standard", requested: contextFile.system?.requested_mode ?? "auto", outcome: "accepted", groups, batchChecksum: contextFile.system?.batch_checksum ?? finalBatchChecksum, planChecksum: contextFile.system?.plan_checksum ?? finalPlanChecksum, finalBatchChecksum, finalPlanChecksum, initialPlanRevision: reviewedPlanRevision, finalPlanRevision: planRevision, code: registered, now, projectRoot, decision, children: latestChildren, flow: flowCommand(context), git: reportGit, nextCommand });
         applyReviewResults(home, latestChildren, decision);
+        if (matrix)
+            Object.assign(report.semantic, { verification_matrix: matrix.metadata });
         const preparedReport = prepareStageReport(report);
+        acceptVerificationMatrix(context, matrix);
         acceptStagePacket(context, { projectId: project.id, runId: run.id, stage, prepared: decisionReceipt });
         acceptStageReport(context, { projectId: project.id, runId: run.id, stage, root, prepared: preparedReport });
         const completionInput = { projectRoot, runId: run.id, stage, status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@1", report: "stage-report.md", stageReport: "stage-report.html", dataSha256: preparedReport.sha256, git: reportGit };

package/dist/services/vnext-plan.js

@@ -21,6 +21,7 @@ import { acceptStageReport, prepareStageReport } from "./stage-report-renderer.j
 import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
 import { subagentCapacityKey } from "./vnext-fanout.js";
 import { stageLifecycleInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { prepareRunVerificationMatrix, acceptVerificationMatrix, commitVerificationMatrixStart, verificationMatrixInstruction } from "./verification-matrix.js";
 export function isVnextPlanRun(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     return Boolean(context.db.get("SELECT id FROM runs WHERE project_id = ? AND id = ? AND flow_kind = 'vnext_protocolize'", [project.id, input.runId]));
@@ -41,7 +42,7 @@ export function prepareVnextPlanStart(context, input) {
     const { profile: codeCheckProfile } = readCodeCheckProfile(run.workspace_root);
     if (context.db.get("SELECT 1 FROM works WHERE project_id = ? AND run_id = ? AND task = ? AND status = 'running'", [project.id, run.id, planTask]))
         throw new AppError("invalid_work_state", "PLAN already has a running Work", 1, { run_id: run.id });
-    prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage: "plan", dir: "03-plan", status: "running", dataSchemaId: "dd-flow/protocol-plan@6" });
+    const attachment = prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage: "plan", dir: "03-plan", status: "running", dataSchemaId: "dd-flow/protocol-plan@6" });
     const root = path.join(home, vnextStageDirectory("plan"));
     if (input.externalContext)
         prepareExternalStageContext({ stageRoot: root, loaded: input.externalContext });
@@ -58,12 +59,16 @@ export function prepareVnextPlanStart(context, input) {
     const git = gitFacts(run.workspace_root);
     for (const file of [...planPaths, ...mapPaths, ...["stage-prompt.md", "work-context.json", "fixture-root.prompt.md"].map(name => path.join(root, name))])
         prepareOutputFile(file);
-    return { projectRoot, project, run, home, root, rootWork, workspaceRoute, protocols, template, codeCheckProfile, planPaths, mapPaths, owned, identities, aspects, runVariables, mergeRequired, git };
+    const matrix = prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage: "plan", role: "input", stageAttempt: attachment.attempt });
+    return { projectRoot, project, run, home, root, rootWork, workspaceRoute, protocols, template, codeCheckProfile, planPaths, mapPaths, owned, identities, aspects, runVariables, mergeRequired, git, matrix };
 }
 export function startVnextPlan(context, input, prepared = prepareVnextPlanStart(context, input)) {
     const { projectRoot, project, run, root, rootWork, workspaceRoute, protocols, template, codeCheckProfile, planPaths, mapPaths, owned, identities, aspects, runVariables, mergeRequired, git, home } = prepared;
     ensureWorkRegistry(context);
     assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage: "plan", projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    if (context.db.get("SELECT 1 FROM works WHERE project_id = ? AND run_id = ? AND task = ? AND status = 'running'", [project.id, run.id, planTask]))
+        throw new AppError("invalid_work_state", "PLAN already has a running Work", 1, { run_id: run.id });
+    prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage: "plan", dir: "03-plan", status: "running", dataSchemaId: "dd-flow/protocol-plan@6" }, true);
     fs.mkdirSync(root, { recursive: true });
     const now = context.now();
     // Imported stage fixtures have a synthetic running root with no prior agent.
@@ -113,9 +118,13 @@ export function startVnextPlan(context, input, prepared = prepareVnextPlanStart(
         : `PLAN-REVIEW mode is ${planReviewMode}: include review groups only for genuinely applicable aspects; an empty set is allowed.`;
     fs.writeFileSync(promptPath, `${prompt}\n<review_mode_rule>${reviewModeRule}</review_mode_rule>\n<verification_rule>Every flow check must be an autonomous executable command. Do not declare external/manual proof or a human review as a check, evidence substitute, DEF, or gate. The only user interaction supported by this flow is an explicit stage pause for a material unanswered question.</verification_rule>\n${stageLifecycleInstruction}\n`);
     const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+    if (prepared.matrix)
+        fs.appendFileSync(promptPath, verificationMatrixInstruction(prepared.matrix.metadata, home, "designing the source PLAN and its tests"));
     fs.writeFileSync(path.join(root, "work-context.json"), JSON.stringify({ schema_id: "dd-flow/work-context@1", system: { run_id: run.id, work_id: planWorkId, stage: "plan" }, workspace: { project_root: projectRoot, workspace_root: run.workspace_root, stage_root: root }, artifacts: artifactMaterialization, input: { protocols, owned_obligations: Object.fromEntries(owned) } }, null, 2));
     const binding = bindStageCoordinatorWork(context, { workId: planWorkId, hookEventId: input.hookEventId, stage: "plan", promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-    attachFlowRunStage(context, { projectRoot, runId: run.id, stage: "plan", dir: "03-plan", status: "running", dataSchemaId: "dd-flow/protocol-plan@6" });
+    const attachmentInput = { projectRoot, runId: run.id, stage: "plan", dir: "03-plan", status: "running", dataSchemaId: "dd-flow/protocol-plan@6" };
+    const attachment = prepareFlowRunStageAttachment(context, attachmentInput);
+    commitVerificationMatrixStart(context, prepared.matrix, () => attachFlowRunStage(context, attachmentInput, attachment));
     const workSessionId = String(binding.work_session_id);
     const sessionId = String(binding.session_id);
     refreshRunWorkProjection(context, project.id, run.id);
@@ -169,6 +178,9 @@ function finishVnextPlanOwned(context, input) {
         plan_checksums: planFiles.map((file) => ({ path: path.relative(run.workspace_root, file).split(path.sep).join("/"), sha256: checksum(file) })),
         aspect_map_checksums: mapFiles.map((file) => ({ path: path.relative(home, file).split(path.sep).join("/"), sha256: checksum(file) }))
     });
+    const matrix = prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage: "plan", role: "output" });
+    if (matrix)
+        Object.assign(report.semantic, { verification_matrix: matrix.metadata });
     const preparedReport = prepareStageReport(report);
     validateSchema({ schemaName: "stage-report", file: path.join(root, "stage-report.json"), data: preparedReport.normalized, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: home });
     const completionInput = { projectRoot, runId: run.id, stage: "plan", status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@1", report: "stage-report.md", stageReport: "stage-report.html", dataSha256: preparedReport.sha256, git: report.mechanical.git };
@@ -179,6 +191,7 @@ function finishVnextPlanOwned(context, input) {
             throw new AppError("invalid_work_state", "PLAN Work changed during finish preparation", 1);
         context.db.run("UPDATE works SET status = 'completed', result = ?, completed_at = ?, updated_at = ? WHERE work_id = ?", ["PLAN accepted; awaiting PLAN-REVIEW", now, now, work.work_id]);
         context.db.run("UPDATE work_sessions SET status = 'completed', result_path = ?, updated_at = ?, completed_at = ? WHERE id = ?", [path.join(root, "stage-report.json"), now, now, workSession.id]);
+        acceptVerificationMatrix(context, matrix);
         acceptStageReport(context, { projectId: project.id, runId: run.id, stage: "plan", root, prepared: preparedReport });
         completeFlowRunStage(context, completionInput, preparedCompletion);
         refreshRunWorkProjection(context, project.id, run.id);