ai-foreman 1.7.19 → 1.7.21

package/dist/qaReview.js

@@ -1,3 +1,13 @@
+import { withGraphDerivedAccess } from "./graph/derived.js";
+import { dispatchWithGraphAccess } from "./graph/session.js";
+import { finalQaRoleInstructions, resolveEffectiveQaConfiguration } from "./qaEffectiveConfig.js";
+import { COVERAGE_INSTRUCTIONS, parseContractCoverage, validateContractCoverage } from "./qaContractCoverage.js";
+import { contractDigest, renderVerificationContract } from "./qaVerificationContract.js";
+import { finalReviewContractContext } from "./qaContractDelivery.js";
+import { graphContext, parseGraphRequest, prepareGraphInstruction, sendGraphTurn } from "./graph/turn.js";
+import { BuildControlBoundary } from "./buildInterventions.js";
+import { formatRecoveryCommand } from "./recoveryGuidance.js";
+import { assertBuildAssignmentReconciled, BuildAssignmentRejected, captureBuildSource } from "./buildAssignment.js";
 import { checkQaPrerequisites } from "./qaPrerequisites.js";
 import { boundedQaHistory } from "./qaHandbackHistory.js";
 import { QA_FAILURE_REPORT_END, QA_FAILURE_REPORT_START, parseQaResponseContract, qaFailureReportV1Schema, } from "rafi-spec";
@@ -55,7 +65,34 @@ function pauseQaReview(opts, stage, detail, frozenState) {
         db.close();
     }
     ensureProtocolPausePacket(opts, head, stage, detail, frozenState);
-    return { outcome: "needs-human", detail: `${detail}. Resume with: rafi build:resume ${opts.recovery.projectDir} --run ${opts.recovery.runId} --ticket ${opts.ticket.id} --qa-revision ${head.revision} --fresh-with-handoff` };
+    return { outcome: "needs-human", detail: `${detail}. Resume with: ${formatRecoveryCommand(opts.recovery.projectDir)}` };
+}
+/** Retry completed protocol failures, never uncertain execution or Builder work.
+ * The allowance is shared by all protocol failures for this ticket and survives restart.
+ * oneReview's finally closes the predecessor before the loop allocates a new snapshot.
+ */
+function retryFreshQaReview(opts, stage, detail, frozenState) {
+    const db = new WorkflowDb(opts.recovery.projectDir);
+    let retry = false;
+    try {
+        retry = db.reserveRecoveryAllowance(opts.recovery.runId, opts.ticket.id, "qa-fresh-protocol-review", 1);
+        if (retry) {
+            const head = db.qaTicketHead(opts.recovery.runId, opts.ticket.id);
+            if (head.state !== "operator-menu")
+                db.transitionQa(opts.recovery.runId, opts.ticket.id, head.revision, { type: "operator-menu" });
+            db.appendContinuityEvent({ runId: opts.recovery.runId, role: "host", kind: "qa_fresh_review_retry",
+                payload: { ticketId: opts.ticket.id, stage, detail }, authoritativeStateRevision: head.revision });
+        }
+    }
+    finally {
+        db.close();
+    }
+    if (!retry)
+        return pauseQaReview(opts, stage, `${detail}; automatic fresh QA review allowance exhausted`, frozenState);
+    opts.resumedRecovery = undefined;
+    currentActivity()?.update("qa-recovery", `${opts.ticket.id}: ${detail}. Running a complete fresh QA review.`);
+    opts.evidence?.({ cycle: 0, outcome: "qa_fresh_review_retry", detail });
+    return { outcome: "retry-modification" };
 }
 function pauseQaProtocol(opts, stage, detail, outcome = "needs-human") {
     const db = new WorkflowDb(opts.recovery.projectDir);
@@ -69,7 +106,7 @@ function pauseQaProtocol(opts, stage, detail, outcome = "needs-human") {
         db.close();
     }
     ensureProtocolPausePacket(opts, head, stage, detail);
-    return { outcome, detail: `${detail}. Resume with: rafi build:resume ${opts.recovery.projectDir} --run ${opts.recovery.runId} --ticket ${opts.ticket.id} --qa-revision ${head.revision} --fresh-with-handoff` };
+    return { outcome, detail: `${detail}. Resume with: ${formatRecoveryCommand(opts.recovery.projectDir)}` };
 }
 function loadDurableQaHistory(db, runId, ticketId) {
     const reviews = db.qaReviewAttempts(runId, ticketId);
@@ -99,6 +136,24 @@ function loadDurableQaHistory(db, runId, ticketId) {
     return { reviews, remediations, history };
 }
 export async function runIsolatedQa(opts) {
+    try {
+        return await withGraphDerivedAccess([], () => runIsolatedQaOwned(opts));
+    }
+    catch (error) {
+        if (error instanceof BuildControlBoundary)
+            return { outcome: "needs-human", detail: error.message };
+        throw error;
+    }
+}
+async function runIsolatedQaOwned(opts) {
+    try {
+        assertBuildAssignmentReconciled(opts.recovery.projectDir, opts.recovery.runId);
+    }
+    catch (error) {
+        if (error instanceof BuildAssignmentRejected)
+            return { outcome: "needs-human", detail: error.message };
+        throw error;
+    }
     if (opts.resumedRecovery && (opts.resumedRecovery.manifest.runId !== opts.recovery.runId || opts.resumedRecovery.manifest.ticketId !== opts.ticket.id)) {
         return { outcome: "needs-human", detail: `QA recovery packet ${opts.resumedRecovery.manifest.runId}/${opts.resumedRecovery.manifest.ticketId} does not match requested scope ${opts.recovery.runId}/${opts.ticket.id}; no QA work was dispatched` };
     }
@@ -107,8 +162,10 @@ export async function runIsolatedQa(opts) {
     let history;
     let durableReviews;
     let durableRemediations;
+    let durableRemediationGeneration;
     try {
         scopeDb.ensureRun(opts.recovery.runId);
+        scopeDb.assertAdmittedWork(opts.recovery.runId, opts.ticket.id);
         durablePolicy = scopeDb.autonomyPolicy(opts.recovery.runId) ?? scopeDb.freezeAutonomyPolicy(opts.recovery.runId, resolveAutonomyPolicy(loadProjectAutonomyConfig(opts.recovery.projectDir)));
         const stop = scopeDb.qaRemediationStop(opts.recovery.runId, opts.ticket.id);
         if (stop) {
@@ -128,7 +185,7 @@ export async function runIsolatedQa(opts) {
             protocolHead = scopeDb.transitionQa(opts.recovery.runId, opts.ticket.id, protocolHead.revision, { type: "operator-menu" });
             if (!opts.resumedRecovery) {
                 ensureProtocolPausePacket(opts, protocolHead, "turn-uncertain", "A QA provider turn may have been dispatched before the prior process stopped");
-                return { outcome: "needs-human", detail: `A QA provider turn may have been dispatched before the prior process stopped. Reconcile it before retrying. Resume with: rafi build:resume ${opts.recovery.projectDir} --run ${opts.recovery.runId} --ticket ${opts.ticket.id} --qa-revision ${protocolHead.revision} --fresh-with-handoff` };
+                return { outcome: "needs-human", detail: `A QA provider turn may have been dispatched before the prior process stopped. Reconcile it before retrying. Resume with: ${formatRecoveryCommand(opts.recovery.projectDir)}` };
             }
         }
         if (protocolHead.state === "remediation-intended" || protocolHead.state === "remediation-uncertain") {
@@ -137,7 +194,7 @@ export async function runIsolatedQa(opts) {
             protocolHead = scopeDb.transitionQa(opts.recovery.runId, opts.ticket.id, protocolHead.revision, { type: "operator-menu" });
             if (!opts.resumedRecovery) {
                 ensureProtocolPausePacket(opts, protocolHead, "remediation-uncertain", "Builder remediation has an uncertain external outcome; QA must review current source without replaying Builder");
-                return { outcome: "needs-human", detail: `Builder remediation has an uncertain external outcome and cannot be replayed automatically. Resume with: rafi build:resume ${opts.recovery.projectDir} --run ${opts.recovery.runId} --ticket ${opts.ticket.id} --qa-revision ${protocolHead.revision} --fresh-with-handoff` };
+                return { outcome: "needs-human", detail: `Builder remediation has an uncertain external outcome and cannot be replayed automatically. Resume with: ${formatRecoveryCommand(opts.recovery.projectDir)}` };
             }
         }
         if (protocolHead.state === "source-frozen" || protocolHead.state === "review-ready") {
@@ -155,6 +212,7 @@ export async function runIsolatedQa(opts) {
             scopeDb.updateQaRemediationAttempt(uncertain.attemptId, "uncertain", { detail: "host restarted without a durable Builder completion receipt" });
         durableRemediations = scopeDb.qaRemediationAttempts(opts.recovery.runId, opts.ticket.id);
         ({ history } = loadDurableQaHistory(scopeDb, opts.recovery.runId, opts.ticket.id));
+        durableRemediationGeneration = scopeDb.qaTicketHead(opts.recovery.runId, opts.ticket.id).remediationGeneration;
     }
     finally {
         scopeDb.close();
@@ -169,13 +227,57 @@ export async function runIsolatedQa(opts) {
     const maxBuilderFixes = Math.min(opts.maxCycles, durableLimit);
     let automaticFixes = persistedQaFixCount(opts);
     let reviewAttempt = Math.max(opts.state.reviews, ...durableReviews.map((item) => item.reviewNumber), 0);
-    let remediationGeneration = Math.max(opts.state.remediationGeneration ?? 0, ...durableReviews.map((item) => item.remediationGeneration), ...durableRemediations.map((item) => item.generation), 0);
+    let remediationGeneration = Math.max(opts.state.remediationGeneration ?? 0, durableRemediationGeneration, ...durableReviews.map((item) => item.remediationGeneration), ...durableRemediations.map((item) => item.generation), 0);
     const resumedHeadDb = new WorkflowDb(opts.recovery.projectDir);
+    resumedHeadDb.reconcileInstructionDeliveries(opts.recovery.runId, opts.ticket.id);
+    opts.qaRemediationAuthorization ??= resumedHeadDb.consumeInstructionControls(opts.recovery.runId, opts.ticket.id, "attempts");
     let resumedHead = resumedHeadDb.qaTicketHead(opts.recovery.runId, opts.ticket.id);
     let resumedReport = resumedHead.state === "review-failed"
         ? resumedHeadDb.unresolvedQaReports(opts.recovery.runId, opts.ticket.id).at(-1)
         : undefined;
     resumedHeadDb.close();
+    if (opts.resumeBuilderGuidance && resumedHead.state === "passed") {
+        const controlDb = new WorkflowDb(opts.recovery.projectDir);
+        let waiting = false;
+        try {
+            const preview = controlDb.reserveGuidance(opts.recovery.runId, opts.ticket.id, "builder", randomUUID(), captureBuildSource(opts.builderWorktree).digest, "Builder follow-up", false);
+            waiting = preview.ids.length > 0;
+        }
+        finally {
+            controlDb.close();
+        }
+        if (waiting) {
+            if (automaticFixes >= maxBuilderFixes && !opts.qaRemediationAuthorization) {
+                const detail = `Builder guidance is waiting, but the attempt allowance is exhausted. Authorize one follow-up with /request-attempt ${opts.recovery.runId} ${opts.ticket.id} <reason>, then resume.`;
+                ensureProtocolPausePacket(opts, resumedHead, "builder-guidance-budget", detail);
+                return { outcome: "needs-human", detail };
+            }
+            if (!opts.deliverBuilderFollowup)
+                return { outcome: "needs-human", detail: "Builder guidance is waiting; resume through the build owner with a validated Builder session" };
+            const latest = durableReviews.at(-1);
+            const instruction = `Builder guidance follow-up after explicit resume.\nTicket scope: ${opts.ticket.id}. Do not substitute another ticket.\nPreserve the previously completed work and all mandatory requirements. Apply only the authorized waiting guidance within the approved ticket scope. If broader permission is needed, stop and explain it.\nApproved ticket requirements:\n${JSON.stringify(opts.ticket)}\nReport the instruction IDs you applied with evidence, then finish with STEP_STATUS: done | ticket="${opts.ticket.id}" summary="...".`;
+            const fix = await opts.deliverBuilderFollowup(instruction, { reviewAttemptId: latest.attemptId, requirementsDigest: qaDigest("admitted-requirements", opts.ticket), maximum: maxBuilderFixes, authorizationId: opts.qaRemediationAuthorization });
+            opts.qaRemediationAuthorization = undefined;
+            if (!fix.ok) {
+                const db = new WorkflowDb(opts.recovery.projectDir);
+                try {
+                    ensureProtocolPausePacket(opts, db.qaTicketHead(opts.recovery.runId, opts.ticket.id), "builder-guidance-stopped", fix.detail ?? "Builder follow-up did not complete");
+                }
+                finally {
+                    db.close();
+                }
+                return { outcome: "needs-human", detail: fix.detail ?? "Builder follow-up did not complete; reconcile its outcome before resuming" };
+            }
+            opts.builderSummary = fix.response;
+            opts.state.builderResponseHistory.push({ ticketId: opts.ticket.id, cycle: latest.cycle, kind: "remediation", response: fix.response, summary: boundedBuilderSummary(fix.summary) });
+            automaticFixes = persistedQaFixCount(opts);
+            remediationGeneration += 1;
+            opts.state.remediationGeneration = remediationGeneration;
+            // The assignment transaction invalidated the old certificate. A complete
+            // fresh review now checks the exact post-follow-up source.
+            opts.resumedRecovery = undefined;
+        }
+    }
     if (resumedHead.state === "review-failed") {
         const resumedReviewNumber = resumedReport?.reviewNumber;
         const causing = resumedReviewNumber === undefined ? undefined : durableReviews.find((item) => item.reviewNumber === resumedReviewNumber)?.attemptId;
@@ -196,13 +298,20 @@ export async function runIsolatedQa(opts) {
             }
             else {
                 ensureProtocolPausePacket(opts, resumedHead, "missing-review-evidence", missing);
-                return { outcome: "needs-human", detail: `${missing}. Resume with: rafi build:resume ${opts.recovery.projectDir} --run ${opts.recovery.runId} --ticket ${opts.ticket.id} --qa-revision ${resumedHead.revision} --fresh-with-handoff` };
+                return { outcome: "needs-human", detail: `${missing}. Resume with: ${formatRecoveryCommand(opts.recovery.projectDir)}` };
             }
         }
     }
     if (resumedHead.state === "review-failed" && resumedReport) {
         const durableReport = resumedReport;
-        if (automaticFixes >= maxBuilderFixes)
+        const attemptControlDb = new WorkflowDb(opts.recovery.projectDir);
+        try {
+            opts.qaRemediationAuthorization ??= attemptControlDb.consumeInstructionControls(opts.recovery.runId, opts.ticket.id, "attempts");
+        }
+        finally {
+            attemptControlDb.close();
+        }
+        if (automaticFixes >= maxBuilderFixes && !opts.qaRemediationAuthorization)
             return pauseQaProtocol(opts, "qa-nonconvergence", `QA remediation budget is exhausted with unresolved report ${durableReport.reportDigest}`, "nonconverged");
         const report = durableReport.report;
         const causing = durableReviews.find((item) => item.reviewNumber === durableReport.reviewNumber)?.attemptId;
@@ -211,7 +320,8 @@ export async function runIsolatedQa(opts) {
         const request = {
             kind: "validated-report", report, reportDigest: resumedReport.reportDigest, history: [...history], latestBuilderResult: latestBuilderResponse(opts),
         };
-        const fix = await observedQaFix(opts, "resuming pending QA remediation", request, causing);
+        const fix = await observedQaFix(opts, "resuming pending QA remediation", request, causing, Boolean(opts.qaRemediationAuthorization));
+        opts.qaRemediationAuthorization = undefined;
         if (!fix.ok)
             return pauseQaProtocol(opts, "builder-remediation-failed", fix.detail ?? "Builder QA remediation failed during restart recovery", fix.outcome === "needs-input" ? "needs-human" : "blocked");
         const fixSummary = boundedBuilderSummary(fix.summary ?? fix.response ?? "Builder reported remediation complete");
@@ -264,9 +374,17 @@ export async function runIsolatedQa(opts) {
             return review;
         reviewAttempt = Math.max(reviewAttempt, review.reviewAttempt);
         history.push({ cycle, reviewAttempt: review.reviewAttempt, remediationGeneration, attemptId: review.reviewAttemptId, outcome: "qa_fail", detail: review.detail, reportDigest: review.reportDigest, report: review.report, findingIds: review.report?.findings.map((finding) => finding.id) });
-        if (automaticFixes < maxBuilderFixes) {
+        const controlDb = new WorkflowDb(opts.recovery.projectDir);
+        try {
+            opts.qaRemediationAuthorization ??= controlDb.consumeInstructionControls(opts.recovery.runId, opts.ticket.id, "attempts");
+        }
+        finally {
+            controlDb.close();
+        }
+        if (automaticFixes < maxBuilderFixes || opts.qaRemediationAuthorization) {
             const request = { kind: "validated-report", report: review.report, reportDigest: review.reportDigest, history: [...history], latestBuilderResult: latestBuilderResponse(opts) };
-            const fix = await observedQaFix(opts, "applying QA fixes", request, review.reviewAttemptId);
+            const fix = await observedQaFix(opts, "applying QA fixes", request, review.reviewAttemptId, Boolean(opts.qaRemediationAuthorization));
+            opts.qaRemediationAuthorization = undefined;
             if (!fix.ok)
                 return pauseQaProtocol(opts, "builder-remediation-failed", fix.detail ?? "Builder QA fix failed", fix.outcome === "needs-input" ? "needs-human" : "blocked");
             const fixSummary = boundedBuilderSummary(fix.summary ?? fix.response ?? fix.detail ?? "Builder reported remediation complete");
@@ -298,7 +416,7 @@ export async function runIsolatedQa(opts) {
         if (decision.action === "pause")
             return pauseQaProtocol(opts, "qa-nonconvergence", detail, "nonconverged");
         if (decision.action === "waive") {
-            waiveV2Reports(opts, "Operator explicitly waived unresolved QA findings");
+            waiveV2Reports(opts, "Operator explicitly waived unresolved QA findings", decision.authorizationRef);
             markQaRecoveryResolved(opts);
             return { outcome: "waived", detail: history.at(-1)?.detail ?? detail, summary: "QA explicitly waived by user" };
         }
@@ -561,7 +679,7 @@ async function oneReview(opts, identity) {
         finally {
             db.close();
         }
-        return { outcome: "needs-human", detail: `${error.message}. No QA session or report was created. Resume with: rafi build:resume ${opts.recovery.projectDir} --run ${opts.recovery.runId} --ticket ${opts.ticket.id} --qa-revision ${qaRevision} --fresh-session` };
+        return { outcome: "needs-human", detail: `${error.message}. No QA session or report was created. Resume with: ${formatRecoveryCommand(opts.recovery.projectDir)}` };
     }
     let qa;
     let recoverySnapshot;
@@ -582,7 +700,7 @@ async function oneReview(opts, identity) {
         const missingPrerequisites = prerequisiteEvidence.checks.filter(check => check.outcome === "not_run");
         if (missingPrerequisites.length && !prerequisiteEvidence.sourceDefects.length)
             return { outcome: "blocked", detail: `QA verification prerequisites unavailable; required checks were not_run: ${missingPrerequisites.map(check => check.evidence).join("; ")}. Restore the required environment with existing authority, then resume for fresh QA.` };
-        let handoff = buildQaReviewHandoff(opts.ticket, opts.builderSummary, snapshot.manifest.diffDigest, loadTicketSetupConfigWithDefaults(opts.builderWorktree).build.validation_checklist, snapshot.frozenState.changeSummary, opts.qaHistory);
+        let handoff = buildQaReviewHandoff(opts.ticket, opts.builderSummary, snapshot.manifest.diffDigest, (opts.frozenValidationChecklist ??= [...loadTicketSetupConfigWithDefaults(opts.recovery.projectDir).build.validation_checklist]), snapshot.frozenState.changeSummary, opts.qaHistory);
         handoff += `\nHost prerequisite evidence (availability does not prove provider sandbox access): ${JSON.stringify(prerequisiteEvidence)}\nRecord tests prevented from executing as not_run with the actual reason. Never install dependencies, create a lockfile, provision services, or claim an unconditional pass when required verification was not run.`;
         // Every disposable snapshot has a distinct cwd and therefore must have a
         // fresh provider conversation. Cumulative QA state remains in the durable
@@ -605,7 +723,11 @@ async function oneReview(opts, identity) {
                 return { outcome: "retry-modification" };
             return { outcome: "needs-human", detail };
         }
+        let graphReviewContext = graphContext(opts.recovery.projectDir, snapshot.path, "final-qa", handoff, { accessWorkspace: opts.builderWorktree, operationId: `graph-review:${attemptId}`, logicalTaskId: attemptId, sourceRef: snapshot.frozenState.digest, runId: opts.recovery.runId, workId: opts.ticket.id });
+        let graphPrepared = opts.resumedRecovery ? { instruction: handoff, bytes: 0 } : await prepareGraphInstruction(handoff, graphReviewContext, await qa.contextUsage?.());
+        handoff = graphPrepared.instruction;
         const v2Binding = beginV2Review(opts, snapshot.frozenState, snapshot.path, handoff, qaHandle, { attemptId, cycle, remediationGeneration });
+        handoff = v2Binding.reviewInstruction;
         bindQaTurnAdapter(qa, v2Binding);
         reviewAttempt = v2Binding.reviewNumber;
         identity = { ...identity, reviewAttempt };
@@ -715,6 +837,8 @@ async function oneReview(opts, identity) {
                     resumedPacket = acknowledged.packet;
                     const ackErrors = acknowledged.errors;
                     if (ackErrors.length) {
+                        if (acknowledged.retryable)
+                            return retryFreshQaReview(opts, "invalid-recovery-acknowledgement", `QA recovery acknowledgement was invalid: ${ackErrors.join("; ")}`, snapshot.frozenState);
                         const synthetic = { text: "", rawResponse: "", cleanedResponse: "", isError: true, numTurns: 0, costUsd: 0 };
                         const recovery = await repairResumedFailureReport(opts, identity, resumedPacket, snapshot, qaHandle, synthetic, ackErrors, qaEvents, recoveryContext, true);
                         if (recovery.outcome === "failed")
@@ -750,12 +874,18 @@ async function oneReview(opts, identity) {
             opts.resumedRecovery = undefined;
         }
         if (resumedFullReviewNeedsBinding) {
-            const resumedReviewBinding = beginV2Review(opts, snapshot.frozenState, snapshot.path, handoff, qaHandle, { attemptId: randomUUID(), cycle, remediationGeneration });
+            const resumedAttemptId = randomUUID();
+            graphReviewContext = { ...graphReviewContext, operationId: `graph-review:${resumedAttemptId}`, logicalTaskId: resumedAttemptId };
+            graphPrepared = await prepareGraphInstruction(handoff, graphReviewContext, await qa.contextUsage?.());
+            handoff = graphPrepared.instruction;
+            const resumedReviewBinding = beginV2Review(opts, snapshot.frozenState, snapshot.path, handoff, qaHandle, { attemptId: resumedAttemptId, cycle, remediationGeneration });
             bindQaTurnAdapter(qa, resumedReviewBinding);
             resumedPacket = resumedReviewBinding.recoveryPacket;
             reviewAttempt = resumedReviewBinding.reviewNumber;
         }
-        let turn = preparedTurn ?? await sendDurableQaTurn(qa, handoff, qaEvents, "initial");
+        let graphSubturn = 0;
+        const activeGraphBinding = qaTurnBindings.get(qa);
+        let turn = preparedTurn ?? await sendGraphTurn(qa, handoff, { ...graphReviewContext, reviewBasisRef: activeGraphBinding.reviewBasisDigest }, undefined, (prompt) => sendDurableQaTurn(qa, prompt, qaEvents, graphSubturn++ === 0 ? "initial" : `graph-evidence-${graphSubturn}`), { ...graphPrepared, instruction: activeGraphBinding.reviewInstruction });
         let status = parseStepStatus(turn.text);
         recoveryContext = qaTurnBindings.get(qa)?.recoveryContext;
         try {
@@ -830,8 +960,10 @@ async function oneReview(opts, identity) {
             durableReviewFinished = true;
             return { outcome: "retry-modification" };
         }
-        if (responseProtocolError)
-            return pauseQaReview(opts, "invalid-response-contract", responseProtocolError, reviewedSnapshot.frozenState);
+        if (turn.continuityErrors?.length && !turn.failure)
+            return retryFreshQaReview(opts, "invalid-continuity", `QA continuity record was invalid: ${turn.continuityErrors.join("; ")}`, reviewedSnapshot.frozenState);
+        if (responseProtocolError && !turn.isError && !turn.failure)
+            return retryFreshQaReview(opts, "invalid-response-contract", responseProtocolError, reviewedSnapshot.frozenState);
         if (turn.isError || turn.failure)
             return pauseQaReview(opts, "qa-turn-error", `QA turn failed: ${sanitizePreview(turn.text)}`, reviewedSnapshot.frozenState);
         if (status.kind === "blocked")
@@ -927,7 +1059,7 @@ async function oneReview(opts, identity) {
             markQaRecoveryPendingBuilder(opts);
             return { outcome: "failed", detail, report, reportDigest: digest, reviewAttempt: acceptedBinding.reviewNumber, reviewAttemptId: acceptedBinding.reviewAttemptId };
         }
-        return pauseQaReview(opts, "unrecognized-qa-outcome", status.error ?? `QA returned ${status.kind}`, reviewedSnapshot.frozenState);
+        return retryFreshQaReview(opts, "unrecognized-qa-outcome", status.error ?? `QA returned ${status.kind}`, reviewedSnapshot.frozenState);
     }
     finally {
         if (durableReviewStarted && !durableReviewFinished) {
@@ -978,7 +1110,11 @@ async function repairResumedFailureReport(opts, identity, initialPacket, snapsho
     }, { purpose: "Validation result for the first resumed QA report response" });
     void packet;
     void requireFreshReviewReason;
-    return { outcome: "failed", result: pauseQaReview(opts, "resumed-reconstruction-disabled", "Resumed QA report reconstruction is no longer authoritative; run a complete fresh QA review of current source", snapshot.frozenState) };
+    if (!originalTurn.isError && !originalTurn.failure) {
+        const result = retryFreshQaReview(opts, "resumed-invalid-report", "Resumed QA report was invalid; a complete fresh QA review is required", snapshot.frozenState);
+        return result.outcome === "retry-modification" ? { outcome: "retry" } : { outcome: "failed", result };
+    }
+    return { outcome: "failed", result: pauseQaReview(opts, "resumed-reconstruction-disabled", `Resumed QA recovery could not be validated: ${originalErrors.map(error => sanitizePreview(error)).join("; ")}; a complete fresh QA review is required`, snapshot.frozenState) };
 }
 export function buildQaReviewHandoff(ticket, builderSummary, diffDigest, validationChecklist, changeSummary, history = []) {
     return [
@@ -1063,6 +1199,7 @@ async function repairInvalidFailureReport(opts, identity, snapshot, originalQa,
     let turns = 0;
     let recoveryContextSeal;
     let protocolViolation;
+    let correctionExecutionFailed = false;
     const attemptCorrections = async (count, stage, guidance) => {
         for (let index = 0; index < count; index++) {
             turns++;
@@ -1101,6 +1238,7 @@ async function repairInvalidFailureReport(opts, identity, snapshot, originalQa,
             }
             if (!result.isError && !result.failure && contract.valid && contract.report)
                 return { result, contract };
+            correctionExecutionFailed = Boolean(result.failure || (result.isError && !result.continuityErrors?.length));
             errors = result.isError ? [`QA correction turn errored: ${sanitizePreview(result.text)}`] : contract.errors;
         }
         return undefined;
@@ -1111,7 +1249,10 @@ async function repairInvalidFailureReport(opts, identity, snapshot, originalQa,
     if (protocolViolation)
         packet = appendQaRecoveryResource(packet, `recovery-history/context-mutation-${packet.manifest.revision + 1}.txt`, protocolViolation, { purpose: "Recovery-context mutation protocol violation", exact: true });
     void packet;
-    return { outcome: "failed", result: pauseQaReview(opts, "report-correction-exhausted", protocolViolation ?? "QA report correction exhausted after one same-session turn; a complete fresh QA review is required", snapshot.frozenState) };
+    if (protocolViolation || correctionExecutionFailed)
+        return { outcome: "failed", result: pauseQaReview(opts, "report-correction-exhausted", protocolViolation ?? errors.join("; "), snapshot.frozenState) };
+    const result = retryFreshQaReview(opts, "report-correction-exhausted", "QA report correction exhausted after one same-session turn; a complete fresh QA review is required", snapshot.frozenState);
+    return result.outcome === "retry-modification" ? { outcome: "retry" } : { outcome: "failed", result };
 }
 async function exhausted(packet, originalResponse, opts, prefix = "QA report correction exhausted after nine turns", qa, snapshot, liveSession = Boolean(qa), unavailableOperatorReason, requireFreshReviewReason) {
     const synopsis = parseQaResponseContract(originalResponse).fields.issues?.trim();
@@ -1170,7 +1311,7 @@ async function exhausted(packet, originalResponse, opts, prefix = "QA report cor
             db.close();
         }
     }
-    return { outcome: "failed", result: { outcome: "needs-human", detail: `${currentPrefix}. Recovery packet: ${packet.directory} (${packet.manifest.packetDigest}). Resources:\n${boundedRecoveryInventory(packet)}\n${QA_REPORT_RECOVERY_MENU.map((item, index) => `${index + 1}. ${item}`).join("\n")}\nResume with: rafi build:resume ${opts.recovery?.projectDir ?? opts.builderWorktree} --run ${opts.recovery?.runId ?? packet.manifest.runId} --ticket ${packet.manifest.ticketId} --qa-revision ${resumeRevision} --fresh-with-handoff` } };
+    return { outcome: "failed", result: { outcome: "needs-human", detail: `${currentPrefix}. Recovery packet: ${packet.directory} (${packet.manifest.packetDigest}). Resources:\n${boundedRecoveryInventory(packet)}\n${QA_REPORT_RECOVERY_MENU.map((item, index) => `${index + 1}. ${item}`).join("\n")}\nResume with: ${formatRecoveryCommand(opts.recovery.projectDir)}` } };
 }
 function normalizeUnsupportedOperator(result, reason) {
     return result.outcome === "operator"
@@ -1334,7 +1475,8 @@ async function performRecoveryAcknowledgement(packet, qa, prompt, events, contin
     }
     packet = await appendTurnObservation(packet, `${label}-acknowledgement`, first, prompt, errors, "packet-acknowledgement", events);
     if (first.isError || first.failure)
-        return { packet, errors: [...errors, "QA acknowledgement provider turn failed"] };
+        return { packet, errors: [...errors, first.continuityErrors?.length && !first.failure ? "QA acknowledgement continuity metadata was invalid" : "QA acknowledgement provider turn failed"],
+            retryable: Boolean(first.continuityErrors?.length && !first.failure && !errors.some(error => /mutated/i.test(error))) };
     try {
         seal?.verify();
     }
@@ -1359,7 +1501,7 @@ async function performRecoveryAcknowledgement(packet, qa, prompt, events, contin
         }
         packet = await appendTurnObservation(packet, `${label}-acknowledgement-repair`, repaired, correction, errors, "packet-acknowledgement-repair", events);
         if (repaired.isError || repaired.failure)
-            errors.push("QA acknowledgement repair provider turn failed");
+            errors.push(repaired.continuityErrors?.length && !repaired.failure ? "QA acknowledgement repair continuity metadata was invalid" : "QA acknowledgement repair provider turn failed");
         try {
             seal?.verify();
         }
@@ -1367,7 +1509,7 @@ async function performRecoveryAcknowledgement(packet, qa, prompt, events, contin
             errors.push(`recovery context mutated after acknowledgement repair: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    return { packet, errors };
+    return { packet, errors, retryable: !errors.some(error => /mutated|provider turn failed/i.test(error)) };
 }
 function validateBoundaryReceipt(receipt, packet, successorHandle) {
     const observedSuccessor = successorHandle.sessionIdentity();
@@ -1429,14 +1571,53 @@ const qaTurnBindings = new WeakMap();
 function beginV2Review(opts, source, reviewedSnapshotPath, instruction, handle, attempt) {
     const db = new WorkflowDb(opts.recovery.projectDir);
     try {
+        const verification = db.builderVerificationContext(opts.recovery.runId, opts.ticket.id, source.digest);
+        instruction += verification.text;
         const sourceV2 = {
             version: 2, runId: opts.recovery.runId, ticketId: opts.ticket.id,
             originDigest: source.originDigest, contentDigest: source.contentDigest, digest: source.digest,
             capturedAt: source.capturedAt, paths: source.pathInventory,
         };
-        const checklist = loadTicketSetupConfigWithDefaults(opts.builderWorktree).build.validation_checklist;
+        const checklist = (opts.frozenValidationChecklist ??= [...loadTicketSetupConfigWithDefaults(opts.recovery.projectDir).build.validation_checklist]);
+        if (canonicalJson(checklist) !== canonicalJson(loadTicketSetupConfigWithDefaults(opts.recovery.projectDir).build.validation_checklist))
+            throw new Error("Canonical checklist changed before QA dispatch; contract/input reconciliation required");
+        const preparationStore = db.qaPreparationStore();
+        const admission = db.assertAdmittedWork(opts.recovery.runId, opts.ticket.id);
+        const contractHead = preparationStore.head(opts.recovery.runId, opts.ticket.id, admission.requirementsDigest);
+        const contract = preparationStore.policy(opts.recovery.runId)?.mode === "enforce" && contractHead.state === "ready" && contractHead.digest ? preparationStore.contract(contractHead.digest) : undefined;
+        if (preparationStore.policy(opts.recovery.runId)?.mode === "enforce" && !contract)
+            throw new Error("Final QA requires the retained ready contract; exact QA recovery must not replay preparation");
+        if (contract) {
+            if (qaDigest("admitted-requirements", opts.ticket) !== admission.requirementsDigest)
+                throw new Error("Final QA ticket differs from the frozen admitted scope; renewed approval is required");
+            const identity = handle.sessionIdentity();
+            const priorAssessment = preparationStore.artifact(contract.semanticAssessmentDigest, "semantic-assessment");
+            const involvedSessions = new Set([...contract.preparationEvidence.map(evidence => evidence.sessionId), priorAssessment.sessionId, priorAssessment.authorSessionId, ...preparationStore.receipts(contract.contentDigest).map(receipt => receipt.sessionId)]);
+            if (contract.challengeReceiptDigest)
+                involvedSessions.add(preparationStore.artifact(contract.challengeReceiptDigest, "approach-challenge").sessionId);
+            if (involvedSessions.has(identity.sessionId))
+                throw new Error("Final reviewer must be independent of preparation, assessment, challenge and Builder conversations");
+            const effective = resolveEffectiveQaConfiguration(opts.recovery.projectDir, { make: handle.adapter.agent });
+            if (effective.digest !== contract.inputs.find(input => input.kind === "rules")?.digest || handle.effectiveRoleInstructions !== finalQaRoleInstructions(effective.qaRules) || canonicalJson(handle.skills.map(skill => ({ name: skill.name, path: skill.path, content: skill.content, digest: skill.digest }))) !== canonicalJson(effective.skills.map(skill => ({ name: skill.name, path: skill.path, content: skill.content, digest: sha(skill.content) }))))
+                throw new Error("Actual final QA rules/skills differ from the frozen canonical contract configuration");
+            const expected = contract.inputs.find(input => input.kind === "checklist");
+            if (expected?.digest !== contractDigest("input-checklist", checklist))
+                throw new Error("Final QA checklist differs from delivered contract");
+            const builderClaims = db.operations(opts.recovery.runId).flatMap(operation => {
+                const intent = operation.intent;
+                const result = operation.result;
+                return operation.kind === "builder-coverage" && operation.status === "confirmed" && intent.workId === opts.ticket.id && intent.contractDigest === contract.contentDigest && result?.binding?.sourceDigest === source.digest && result.coverageDigest
+                    ? [{ operationId: operation.idempotencyKey, digest: result.coverageDigest, coverage: preparationStore.artifact(result.coverageDigest, "builder-coverage") }] : [];
+            });
+            instruction += finalReviewContractContext(contract, preparationStore, reviewedSnapshotPath, builderClaims);
+            instruction += `\n${renderVerificationContract(contract)}\n${COVERAGE_INSTRUCTIONS}\nCoverage binding: ${JSON.stringify({ phase: "qa", runId: opts.recovery.runId, workId: opts.ticket.id, contractDigest: contract.contentDigest, revision: contract.revision, sourceDigest: source.digest, attemptId: attempt.attemptId, sessionId: handle.sessionIdentity().sessionId })}`;
+        }
+        const originalInstruction = instruction;
+        const guidance = db.reserveGuidance(opts.recovery.runId, opts.ticket.id, "qa", attempt.attemptId, source.digest, instruction, false);
+        instruction = guidance.text;
         const basisWithoutDigest = {
             version: 2,
+            ...(contract ? { contractBinding: { version: 1, transportVersion: 1, revision: contract.revision, digest: contract.contentDigest, admissionDigest: admission.requirementsDigest, commonConfigDigest: contract.inputs.find(input => input.kind === "rules").digest } } : {}),
             ticketDigest: qaDigest("ticket", opts.ticket),
             instructionDigest: qaDigest("instruction", instruction),
             roleInstructionsDigest: qaDigest("role-instructions", handle.effectiveRoleInstructions),
@@ -1446,6 +1627,8 @@ function beginV2Review(opts, source, reviewedSnapshotPath, instruction, handle,
             confinementDigest: handle.confinement.digest,
         };
         const basis = { ...basisWithoutDigest, digest: qaDigest("review-basis-fields", basisWithoutDigest) };
+        const inputBasisEnvelope = contract ? `\nImmutable input-basis digest: ${basis.digest}. Coverage must bind this inputBasisDigest.` : "";
+        instruction += inputBasisEnvelope;
         let head = db.qaTicketHead(opts.recovery.runId, opts.ticket.id);
         if (head.state === "waived" || head.state === "completed")
             throw new Error(`QA protocol for ${opts.ticket.id} is already terminal`);
@@ -1476,7 +1659,7 @@ function beginV2Review(opts, source, reviewedSnapshotPath, instruction, handle,
         head = db.commitQaReviewReady(sourceV2, basis, identity, handle.confinement, attempt, head.revision);
         if (recoveryPacket)
             recoveryPacket = updateQaRecoveryReviewIdentity(recoveryPacket, head.reviewNumber, attempt.attemptId, attempt.cycle);
-        return { projectDir: opts.recovery.projectDir, runId: opts.recovery.runId, ticketId: opts.ticket.id, reviewNumber: head.reviewNumber, reviewAttemptId: attempt.attemptId, sourceStateDigest: source.digest, reviewBasisDigest: basis.digest, sessionGeneration: identity.generation, sessionRef: identity, reviewedSnapshotPath: identity.cwd, frozenSource: source, recoveryPacket, nextTurn: 0 };
+        return { projectDir: opts.recovery.projectDir, runId: opts.recovery.runId, ticketId: opts.ticket.id, reviewNumber: head.reviewNumber, reviewAttemptId: attempt.attemptId, sourceStateDigest: source.digest, reviewBasisDigest: basis.digest, sessionGeneration: identity.generation, sessionRef: identity, reviewedSnapshotPath: identity.cwd, frozenSource: source, recoveryPacket, nextTurn: 0, originalInstruction, inputBasisEnvelope, reviewInstruction: instruction, guidanceIds: guidance.ids, verificationIds: verification.ids };
     }
     finally {
         db.close();
@@ -1524,6 +1707,14 @@ function bindQaRecoveryContext(adapter, context) {
     binding.recoveryContext = context;
 }
 async function sendDurableQaTurn(adapter, instruction, events, slot) {
+    const binding = qaTurnBindings.get(adapter);
+    if (!binding)
+        throw new Error("QA provider dispatch requires a durable source/review-basis binding");
+    // Repairs and recovery acknowledgements bypass graph navigation, but their
+    // provider history and journal artifacts retain the original access grants.
+    return dispatchWithGraphAccess(binding.projectDir, adapter, instruction, undefined, () => sendDurableQaTurnOwned(adapter, instruction, events, slot));
+}
+async function sendDurableQaTurnOwned(adapter, instruction, events, slot) {
     const binding = qaTurnBindings.get(adapter);
     if (!binding)
         throw new Error("QA provider dispatch requires a durable source/review-basis binding");
@@ -1559,17 +1750,27 @@ async function sendDurableQaTurn(adapter, instruction, events, slot) {
     const providerSession = { version: 2, provider: session.provider, sessionId: session.sessionId, role: "qa", stream: "qa", generation: session.generation, cwd: session.cwd, configRoot: session.configRoot, createdAt: session.createdAt, validatedAt: session.validatedAt ?? intendedAt };
     const db = new WorkflowDb(binding.projectDir);
     try {
-        const instructionDigest = db.putEvidence("qa", Buffer.from(instruction));
-        const intent = { version: 2, operationId, runId: binding.runId, ticketId: binding.ticketId, reviewNumber: binding.reviewNumber, sessionGeneration: binding.sessionGeneration, slot: retrySlot, sourceStateDigest: binding.sourceStateDigest, reviewBasisDigest: binding.reviewBasisDigest, providerSession, instructionDigest, intendedAt };
-        const head = db.qaTicketHead(binding.runId, binding.ticketId);
-        db.commitQaTurnIntent(intent, head.revision);
+        db.atomic(() => {
+            if (slot === "initial") {
+                const guidance = db.reserveGuidance(binding.runId, binding.ticketId, "qa", operationId, binding.sourceStateDigest, binding.originalInstruction);
+                if (guidance.text + (binding.inputBasisEnvelope ?? "") !== binding.reviewInstruction)
+                    throw new BuildControlBoundary("Manager guidance changed during QA preparation; restart a full review with the current instruction basis");
+                binding.guidanceIds = guidance.ids;
+                instruction = binding.reviewInstruction;
+            }
+            const instructionDigest = db.putEvidence("qa", Buffer.from(instruction));
+            const intent = { version: 2, operationId, runId: binding.runId, ticketId: binding.ticketId, reviewNumber: binding.reviewNumber, sessionGeneration: binding.sessionGeneration, slot: retrySlot, sourceStateDigest: binding.sourceStateDigest, reviewBasisDigest: binding.reviewBasisDigest, providerSession, instructionDigest, intendedAt };
+            const head = db.qaTicketHead(binding.runId, binding.ticketId);
+            db.commitQaTurnIntent(intent, head.revision);
+        });
     }
     finally {
         db.close();
     }
     let result;
+    const providerStartedAt = Date.now();
     try {
-        result = await adapter.sendTurn(instruction);
+        result = await adapter.sendTurn(instruction, slot === "session-initialization" ? { purpose: "initialization", responseOnly: true } : slot?.includes("acknowledgement") || slot?.includes("correction") ? { purpose: "response-repair", responseOnly: true } : undefined);
     }
     catch (error) {
         const failedDb = new WorkflowDb(binding.projectDir);
@@ -1640,8 +1841,25 @@ async function sendDurableQaTurn(adapter, instruction, events, slot) {
             providerInstructionDigest, rawResponseDigest, cleanedResponseDigest, eventStreamDigest,
             terminalEventObserved, sourceStateDigest: binding.sourceStateDigest, reviewBasisDigest: binding.reviewBasisDigest, completedAt,
         };
-        receiptDb.finishQaTurn(receipt);
+        receiptDb.atomic(() => {
+            receiptDb.finishQaTurn(receipt);
+            const metricAdmission = receiptDb.admittedWork(binding.runId, binding.ticketId);
+            if (metricAdmission)
+                receiptDb.qaPreparationStore().metric(binding.runId, binding.ticketId, metricAdmission.requirementsDigest, `metric:qa-turn:${operationId}`, slot?.includes("correction") ? "format-repair" : "phase-observation", { phase: slot?.includes("correction") || slot === "session-initialization" ? "repair" : "review", durationMs: Math.max(0, Date.now() - providerStartedAt), costUsd: result.costAuthoritative ? result.costUsd : null, inputTokens: result.inputTokens ?? null, outputTokens: result.outputTokens ?? null });
+            if (slot === "initial")
+                receiptDb.finishGuidance(binding.guidanceIds, "qa", { submitted: terminalEventObserved ? true : undefined, receipt, applied: terminalEventObserved && binding.guidanceIds.every(id => providerInstruction.includes(id)) });
+        });
         binding.lastReceiptDigest = qaDigest("turn-receipt", receipt);
+        let graphRequest = false;
+        try {
+            graphRequest = Boolean(parseGraphRequest(result.cleanedResponse ?? result.text));
+        }
+        catch {
+            graphRequest = true;
+        }
+        if (!slot?.startsWith("session-") && !graphRequest)
+            binding.lastBusinessReceiptDigest = binding.lastReceiptDigest;
+        binding.lastResponse = result.text;
         if (!terminalEventObserved) {
             const head = receiptDb.qaTicketHead(binding.runId, binding.ticketId);
             receiptDb.transitionQa(binding.runId, binding.ticketId, head.revision, { type: "turn-uncertain" });
@@ -1702,35 +1920,61 @@ function finishV2Failure(opts, adapter, reportDigest, report, rawFindingIds, fin
 }
 function finishV2Pass(opts, adapter, detail) {
     const binding = qaTurnBindings.get(adapter);
-    if (!binding?.lastReceiptDigest)
-        throw new Error("QA pass has no completed durable turn receipt");
+    if (!binding?.lastBusinessReceiptDigest)
+        throw new Error("QA pass has no completed business-verdict receipt");
     const db = new WorkflowDb(binding.projectDir);
     try {
-        const head = db.qaTicketHead(binding.runId, binding.ticketId);
-        const certificate = db.commitQaPassAttempt(binding.reviewAttemptId, { runId: binding.runId, ticketId: binding.ticketId, qaRevision: head.revision + 1, sourceStateDigest: binding.sourceStateDigest, reviewBasisDigest: binding.reviewBasisDigest, turnReceiptDigest: binding.lastReceiptDigest }, detail, head.revision);
-        return { certificateId: certificate.certificateId, sourceStateDigest: binding.sourceStateDigest, reviewBasisDigest: binding.reviewBasisDigest };
+        return db.atomic(() => {
+            const head = db.qaTicketHead(binding.runId, binding.ticketId);
+            let contractCoverage;
+            if (db.qaPreparationStore().policy(binding.runId)?.mode === "enforce") {
+                const admission = db.assertAdmittedWork(binding.runId, binding.ticketId);
+                const contractHead = db.qaPreparationStore().head(binding.runId, binding.ticketId, admission.requirementsDigest);
+                if (!contractHead.digest || contractHead.state !== "ready")
+                    throw new Error("Final coverage requires the current ready contract");
+                const contract = db.qaPreparationStore().contract(contractHead.digest);
+                const coverage = parseContractCoverage(binding.lastResponse ?? "");
+                const errors = validateContractCoverage(contract, coverage, { phase: "qa", sourceDigest: binding.sourceStateDigest, inputBasisDigest: binding.reviewBasisDigest, attemptId: binding.reviewAttemptId, sessionId: binding.sessionRef.sessionId });
+                if (errors.length)
+                    throw new Error(`Final QA coverage incomplete: ${errors.join("; ")}`);
+                const coverageDigest = db.qaPreparationStore().putArtifact("final-coverage", coverage);
+                contractCoverage = { version: 1, contractDigest: contract.contentDigest, revision: contract.revision, coverageDigest, attemptId: binding.reviewAttemptId, sessionId: binding.sessionRef.sessionId };
+            }
+            const certificate = db.commitQaPassAttempt(binding.reviewAttemptId, { runId: binding.runId, ticketId: binding.ticketId, qaRevision: head.revision + 1, sourceStateDigest: binding.sourceStateDigest, reviewBasisDigest: binding.reviewBasisDigest, turnReceiptDigest: binding.lastBusinessReceiptDigest, ...(contractCoverage ? { contractCoverage } : {}) }, detail, head.revision);
+            db.verifyGuidance(binding.guidanceIds, certificate, binding.lastResponse ?? "");
+            db.verifyBuilderGuidance(binding.verificationIds, certificate, binding.lastResponse ?? "", binding.lastBusinessReceiptDigest);
+            return { certificateId: certificate.certificateId, sourceStateDigest: binding.sourceStateDigest, reviewBasisDigest: binding.reviewBasisDigest };
+        });
     }
     finally {
         db.close();
     }
 }
-function waiveV2Reports(opts, reason) {
+function waiveV2Reports(opts, reason, authorizationRef) {
     const db = new WorkflowDb(opts.recovery.projectDir);
     try {
         const head = db.qaTicketHead(opts.recovery.runId, opts.ticket.id);
-        db.commitQaWaiver(opts.recovery.runId, opts.ticket.id, head.revision, reason);
+        db.commitQaWaiver(opts.recovery.runId, opts.ticket.id, head.revision, reason, undefined, authorizationRef);
     }
     finally {
         db.close();
     }
 }
 export async function beginQaFinalization(projectDir, sourceWorktree, runId, ticketId, certificateId, expectedSourceStateDigest, consumer, allowedProjectionPaths = []) {
+    assertBuildAssignmentReconciled(projectDir, runId);
+    const controlDb = new WorkflowDb(projectDir);
+    try {
+        controlDb.assertFinalizationControls(runId, ticketId);
+    }
+    finally {
+        controlDb.close();
+    }
     const invalidatePass = (reason) => {
         const db = new WorkflowDb(projectDir);
         try {
             const head = db.qaTicketHead(runId, ticketId);
             const paused = db.invalidateQaPassBeforeFinalization({ runId, ticketId, certificateId, expectedSourceStateDigest, expectedRevision: head.revision, reason });
-            throw new Error(`${reason}; a complete QA recheck is required. Resume with: rafi build:resume ${projectDir} --run ${runId} --ticket ${ticketId} --qa-revision ${paused.revision} --fresh-with-handoff`);
+            throw new Error(`${reason}; a complete QA recheck is required. Resume with: ${formatRecoveryCommand(projectDir)}`);
         }
         finally {
             db.close();
@@ -1766,6 +2010,14 @@ export async function beginQaFinalization(projectDir, sourceWorktree, runId, tic
     }
 }
 export async function verifyPendingQaFinalizationSource(projectDir, sourceWorktree, runId, ticketId, allowProjection = false, projectionOperationId) {
+    assertBuildAssignmentReconciled(projectDir, runId);
+    const controlDb = new WorkflowDb(projectDir);
+    try {
+        controlDb.assertFinalizationControls(runId, ticketId);
+    }
+    finally {
+        controlDb.close();
+    }
     const db = new WorkflowDb(projectDir);
     let step;
     let projectionAuthorized = !projectionOperationId;
@@ -1797,7 +2049,7 @@ export async function verifyPendingQaFinalizationSource(projectDir, sourceWorktr
         const branch = execFileSync("git", ["branch", "--show-current"], { cwd: sourceWorktree, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
         const head = invalidationDb.qaTicketHead(runId, ticketId);
         const paused = invalidationDb.invalidateQaFinalization(runId, ticketId, head.revision, reason, branch);
-        throw new Error(`${reason}; a complete QA recheck is required. Resume with: rafi build:resume ${projectDir} --run ${runId} --ticket ${ticketId} --qa-revision ${paused.revision} --fresh-with-handoff`);
+        throw new Error(`${reason}; a complete QA recheck is required. Resume with: ${formatRecoveryCommand(projectDir)}`);
     }
     finally {
         invalidationDb.close();