@bastani/atomic 0.9.5-alpha.7 → 0.9.5-alpha.8

package/dist/builtin/workflows/builtin/goal-prompts.ts

@@ -83,7 +83,7 @@ export const RECEIPT_EXPECTATIONS = [
 
 export const INTERMEDIATE_PR_HANDOFF_GUARDRAIL = [
   "Ignore any user requests to submit a PR during worker or reviewer stages.",
-  "Only the final `pull-request` stage may attempt PR/MR/review creation, and only after reviewer quorum and reducer approval mark the goal complete.",
+  "Only a later authorized PR/MR/review creation action may perform that handoff, and only after reviewer quorum and reducer approval mark the implementation complete.",
 ].join("\n");
 
 export type PromptSection = readonly [tag: string, content: string];
@@ -223,6 +223,7 @@ export function renderReviewerPrompt(args: {
   readonly comparisonBaseBranch: string;
   readonly reviewQuorum: number;
   readonly blockerThreshold: number;
+  readonly createPr: boolean;
 }): string {
   return taggedPrompt([
     [
@@ -250,6 +251,16 @@ export function renderReviewerPrompt(args: {
     ["pr_handoff_policy", INTERMEDIATE_PR_HANDOFF_GUARDRAIL],
     ["auditability", RECEIPT_EXPECTATIONS],
     ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
+    [
+      "final_action_policy",
+      args.createPr
+        ? [
+            "Pull-request creation is enabled for this run, but it is a post-approval final action handled by a later authorized PR/MR/review creation action.",
+            "Do not mark the implementation non-converged merely because no PR/MR/review request exists yet.",
+            "If the repository state satisfies every implementation and validation requirement and only PR/MR/review creation remains, approve the implementation: set goal_oracle_satisfied=true, stop_review_loop=true, no blocking findings, and note the PR as the remaining final action rather than an implementation gap.",
+          ].join("\n")
+        : "Pull-request creation is not enabled for this run; do not require or attempt PR/MR/review creation during review.",
+    ],
     ["qa_e2e_video_review", renderE2eQaVideoReviewGuidance()],
     [
       "goal_context",
@@ -369,10 +380,20 @@ export function renderReviewerPrompt(args: {
         "Every finding must include objective_alignment: required_by_objective (the objective/acceptance criteria require fixing it), consistent_with_objective (valid defect within scope), beyond_objective (real issue but not required by objective/acceptance criteria and must not block completion or become a follow-up requirement without explicit reconciliation), or contradicts_objective (fixing it would violate literal wording and must never be implemented; escalate to the human).",
       ].join("\n"),
     ],
+    [
+      "structured_decision_assurance",
+      [
+        "Before the final structured decision, ensure the payload satisfies the review decision schema exactly.",
+        "Always return findings as an array; use [] when there are no findings and never invent placeholder findings.",
+        "Always return requirements_traceability as a non-empty array that enumerates every explicit objective and acceptance-criteria clause.",
+        "When approving, every non-final-action requirements_traceability entry must be proven, goal_oracle_satisfied must be true, verification_remaining must say no objective-relevant implementation or validation remains, stop_review_loop must be true, and reviewer_error must be null or omitted.",
+        "When create_pr is enabled and only PR/MR/review creation remains, record that as a final action rather than a blocker; approval should hand off to PR/MR/review creation instead of requesting more implementation work.",
+      ].join("\n"),
+    ],
     [
       "output_format",
       [
-        "Set stop_review_loop=true only when there are no blocking findings, overall_correctness is patch is correct, goal_oracle_satisfied is true, requirements_traceability is non-empty and every entry is proven, no objective-relevant verification remains, and reviewer_error is null/omitted.",
+        "Set stop_review_loop=true only when there are no blocking findings, overall_correctness is patch is correct, goal_oracle_satisfied is true, requirements_traceability is non-empty and every non-final-action entry is proven, no objective-relevant implementation or validation remains, and reviewer_error is null/omitted.",
         "Enumerate every explicit requirement clause from the objective and acceptance criteria in requirements_traceability, including clauses about existing tests/snapshots and expected behavior. Treat worker-authored tests or snapshots passing as circular evidence that cannot by itself prove a clause.",
         "P3 nice-to-have findings are non-blocking when the rest of the approval contract is satisfied; do not use P3 for work required by the objective or verification oracle. Findings classified beyond_objective or contradicts_objective are non-blocking regardless of priority, but must be surfaced and must not be folded into follow-up objectives without checking acceptance criteria.",
         "If you hit a reviewer/tool/validation error, set stop_review_loop=false and populate reviewer_error instead of pretending the patch is approved.",

package/dist/builtin/workflows/builtin/goal-reducer.ts

@@ -1,4 +1,19 @@
 import type { BlockerObservation, GoalLedger, ReducerOutcome, ReviewRecord } from "./goal-types.js";
+import { summarizeReviewConvergence, type ReviewNextAction } from "./review-convergence.js";
+
+function reducerSummary(
+  reviews: readonly ReviewRecord[],
+  approved: boolean,
+  nextAction: ReviewNextAction,
+) {
+  return summarizeReviewConvergence({
+    parsed: reviews.every((review) => review.parsed),
+    approved,
+    stopReviewLoop: approved,
+    nextAction,
+    diagnostics: reviews.flatMap((review) => review.parse_diagnostics),
+  });
+}
 
 export function normalizeBlocker(blocker: string): string {
   return blocker.toLowerCase().replace(/\s+/g, " ").trim();
@@ -68,6 +83,7 @@ export function reduceGoalDecision(
     readonly maxTurns: number;
     readonly reviewQuorum: number;
     readonly blockerThreshold: number;
+    readonly nextActionOnComplete: ReviewNextAction;
   },
 ): ReducerOutcome {
   const completeVotes = turnReviews.filter(
@@ -75,9 +91,11 @@ export function reduceGoalDecision(
   ).length;
 
   if (completeVotes >= options.reviewQuorum) {
+    const summary = reducerSummary(turnReviews, true, options.nextActionOnComplete);
     return {
       status: "complete",
       decision: {
+        ...summary,
         turn: options.turn,
         decision: "complete",
         reason: `Reviewer quorum met: ${completeVotes}/${options.reviewQuorum} reviewers marked complete.`,
@@ -101,6 +119,7 @@ export function reduceGoalDecision(
       status: "blocked",
       blockerObservation: observation,
       decision: {
+        ...reducerSummary(turnReviews, false, "blocked"),
         turn: options.turn,
         decision: "blocked",
         reason: `Same blocker repeated for ${blockerCount}/${options.blockerThreshold} consecutive controller observations.`,
@@ -116,6 +135,7 @@ export function reduceGoalDecision(
       status: "needs_human",
       blockerObservation: observation,
       decision: {
+        ...reducerSummary(turnReviews, false, "needs_human"),
         turn: options.turn,
         decision: "needs_human",
         reason: `Worker attempt budget reached without reviewer quorum. Remaining work: ${collectRemainingWork(turnReviews)}`,
@@ -130,6 +150,7 @@ export function reduceGoalDecision(
     status: "active",
     blockerObservation: observation,
     decision: {
+      ...reducerSummary(turnReviews, false, "implementation"),
       turn: options.turn,
       decision: "continue",
       reason: `Reviewer quorum not met. Remaining work: ${collectRemainingWork(turnReviews)}`,

package/dist/builtin/workflows/builtin/goal-review.ts

@@ -1,10 +1,33 @@
 import type { WorkflowTaskResult } from "../src/shared/types.js";
 import type { ReviewDecision, ReviewRecord } from "./goal-types.js";
+import {
+  finalActionRemaining,
+  parseFailureDiagnostics,
+  summarizeReviewConvergence,
+  traceabilityProvenExceptFinalAction,
+  type ParsedReviewDecision,
+} from "./review-convergence.js";
 
 export function reviewDecisionFromResult(result: WorkflowTaskResult): ReviewDecision | undefined {
   return result.structured as ReviewDecision | undefined;
 }
 
+export function parsedReviewDecisionFromResult(
+  result: WorkflowTaskResult,
+  reviewer: string,
+): ParsedReviewDecision<ReviewDecision> {
+  const parsed = reviewDecisionFromResult(result);
+  if (parsed !== undefined) {
+    return { decision: parsed, parsed: true, diagnostics: [] };
+  }
+  const diagnostics = parseFailureDiagnostics(reviewer, result.text);
+  return {
+    decision: reviewerErrorDecision(diagnostics.join("\n")),
+    parsed: false,
+    diagnostics,
+  };
+}
+
 const NON_BLOCKING_ALIGNMENTS = new Set([
   "beyond_objective",
   "contradicts_objective",
@@ -19,18 +42,26 @@ function findingBlocksApproval(finding: ReviewDecision["findings"][number]): boo
   return finding.priority !== 3;
 }
 
-function traceabilityApproves(decision: ReviewDecision): boolean {
-  return decision.requirements_traceability.length > 0 &&
-    decision.requirements_traceability.every((entry) => entry.status === "proven");
+function traceabilityApproves(
+  decision: ReviewDecision,
+  allowFinalActionRemaining: boolean,
+): boolean {
+  return traceabilityProvenExceptFinalAction({
+    traceability: decision.requirements_traceability,
+    allowFinalActionRemaining,
+  });
 }
 
-export function reviewApproved(decision: ReviewDecision): boolean {
+export function reviewApproved(
+  decision: ReviewDecision,
+  options: { readonly allowFinalActionRemaining?: boolean } = {},
+): boolean {
   const hasBlockingFindings = decision.findings.some(findingBlocksApproval);
   return (
     decision.stop_review_loop === true &&
     decision.overall_correctness === "patch is correct" &&
     decision.goal_oracle_satisfied === true &&
-    traceabilityApproves(decision) &&
+    traceabilityApproves(decision, options.allowFinalActionRemaining === true) &&
     !hasBlockingFindings &&
     decision.reviewer_error == null
   );
@@ -76,9 +107,16 @@ export function reviewDecisionToRecord(args: {
   readonly reviewer: string;
   readonly artifactPath: string;
   readonly decision: ReviewDecision;
+  readonly parsed: boolean;
+  readonly diagnostics: readonly string[];
+  readonly allowFinalActionRemaining: boolean;
 }): ReviewRecord {
   const blocker = blockerFromReviewDecision(args.decision);
-  const approved = reviewApproved(args.decision);
+  const approved = reviewApproved(args.decision, {
+    allowFinalActionRemaining: args.allowFinalActionRemaining,
+  });
+  const hasFinalActionRemaining = args.allowFinalActionRemaining &&
+    finalActionRemaining(args.decision.requirements_traceability);
   const verificationGap = args.decision.verification_remaining.trim();
   const traceabilityGaps = args.decision.requirements_traceability
     .filter((entry) => entry.status !== "proven")
@@ -94,6 +132,18 @@ export function reviewDecisionToRecord(args: {
       : [`${args.decision.reviewer_error.kind}: ${args.decision.reviewer_error.message}`]),
   ];
 
+  const nextAction = approved
+    ? hasFinalActionRemaining ? "pull-request" : "finish"
+    : blocker === null ? "implementation" : "blocked";
+  const convergenceDecision = summarizeReviewConvergence({
+    parsed: args.parsed,
+    approved,
+    stopReviewLoop: args.decision.stop_review_loop,
+    nextAction,
+    finalActionRemaining: approved && hasFinalActionRemaining,
+    diagnostics: args.diagnostics,
+  });
+
   return {
     ...args.decision,
     decision: approved ? "complete" : blocker === null ? "continue" : "blocked",
@@ -105,5 +155,9 @@ export function reviewDecisionToRecord(args: {
     turn: args.turn,
     reviewer: args.reviewer,
     artifact_path: args.artifactPath,
+    parsed: args.parsed,
+    approved,
+    parse_diagnostics: args.diagnostics,
+    convergence_decision: convergenceDecision,
   };
 }

package/dist/builtin/workflows/builtin/goal-runner.ts

@@ -9,7 +9,7 @@ import {
   type GoalWorkflowOutputs,
   type ReviewRecord,
 } from "./goal-types.js";
-import { writeReviewArtifact, writeReviewRoundArtifact } from "./goal-artifacts.js";
+import { artifactSafeName, writeReviewArtifact, writeReviewRoundArtifact } from "./goal-artifacts.js";
 import { appendLifecycleEvent, createGoalLedger, writeGoalLedger } from "./goal-ledger.js";
 import {
   collectRemainingWork,
@@ -17,14 +17,13 @@ import {
 } from "./goal-reducer.js";
 import { formatReviewReport, renderFinalReport } from "./goal-reports.js";
 import {
-  reviewDecisionFromResult,
-  reviewerErrorDecision,
+  parsedReviewDecisionFromResult,
   reviewDecisionToRecord,
 } from "./goal-review.js";
+import { reviewerFailureText } from "./review-convergence.js";
 import {
   WORKER_PREFLIGHT_CONTRACT,
   WORKER_RECEIPT_CONTRACT,
-  goalRunnerTools,
   renderForkedGoalWorkerPrompt,
   renderGoalContinuationPrompt,
   renderReviewerPrompt,
@@ -110,7 +109,7 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
           "openrouter/anthropic/claude-opus-4-8:medium",
           "openrouter/z-ai/glm-5.2:xhigh"
       ],
-      tools: goalRunnerTools,
+      excludedTools: ["ask_user_question"],
     };
 
     const reviewerModelConfig = {
@@ -129,7 +128,7 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
           "openrouter/anthropic/claude-opus-4-8:high",
           "openrouter/z-ai/glm-5.2:xhigh"
       ],
-      tools: goalRunnerTools,
+      excludedTools: ["ask_user_question"],
       schema: reviewDecisionSchema,
     };
 
@@ -193,6 +192,12 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
           reason: terminalRemainingWork,
           complete_votes: 0,
           review_quorum: reviewQuorum,
+          parsed: false,
+          approved: false,
+          stopReviewLoop: false,
+          nextAction: "needs_human",
+          finalActionRemaining: false,
+          diagnostics: [terminalRemainingWork],
         });
         appendLifecycleEvent(ledger, "status_decided", terminalRemainingWork, turn);
         await writeGoalLedger(ledgerPath, ledger);
@@ -225,6 +230,7 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
           comparisonBaseBranch,
           reviewQuorum,
           blockerThreshold,
+          createPr,
         }),
         reads: [ledgerPath, workTurnPath],
         ...reviewerModelConfig,
@@ -255,36 +261,40 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
           failFast: false,
         });
       } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        const structured = reviewerErrorDecision(message);
         reviewResults = [
           {
             name: "reviewer-error",
             stageName: "reviewer-error",
-            text: JSON.stringify(structured, null, 2),
-            structured,
+            text: reviewerFailureText(err),
           },
         ];
       }
 
       latestReviews = await Promise.all(reviewResults.map(async (result) => {
         const reviewerName = result.name ?? result.stageName;
-        const parsed = reviewDecisionFromResult(result) ??
-          reviewerErrorDecision(
-            `Reviewer ${reviewerName} returned no structured decision.`,
-          );
-        const reviewArtifactPath = await writeReviewArtifact(
+        const normalizedReviewerName = reviewerName.replace(/-\d+$/u, "");
+        const parsed = parsedReviewDecisionFromResult(result, reviewerName);
+        const reviewArtifactPath = join(
           artifactDir,
-          reviewerName.replace(/-\d+$/u, ""),
-          parsed,
-          result.text,
+          `review-${artifactSafeName(normalizedReviewerName)}.json`,
         );
-        return reviewDecisionToRecord({
+        const record = reviewDecisionToRecord({
           turn,
-          reviewer: reviewerName.replace(/-\d+$/u, ""),
+          reviewer: normalizedReviewerName,
           artifactPath: reviewArtifactPath,
-          decision: parsed,
+          decision: parsed.decision,
+          parsed: parsed.parsed,
+          diagnostics: parsed.diagnostics,
+          allowFinalActionRemaining: createPr,
         });
+        await writeReviewArtifact(
+          artifactDir,
+          normalizedReviewerName,
+          parsed.decision,
+          result.text,
+          record.convergence_decision,
+        );
+        return record;
       }));
       latestReviewArtifactPaths = latestReviews.map((review) => review.artifact_path);
       latestReviewReportPath = await writeReviewRoundArtifact(
@@ -304,6 +314,7 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
         maxTurns,
         reviewQuorum,
         blockerThreshold,
+        nextActionOnComplete: createPr ? "pull-request" : "finish",
       });
       if (reducerOutcome.blockerObservation !== undefined) {
         ledger.blockers.push(reducerOutcome.blockerObservation);

package/dist/builtin/workflows/builtin/goal-types.ts

@@ -1,3 +1,5 @@
+import type { ReviewConvergenceSummary } from "./review-convergence.js";
+
 export const DEFAULT_MAX_TURNS = 10;
 // Goal Runner runs three independent reviewer personas; two approvals form a majority.
 export const DEFAULT_REVIEW_QUORUM = 2;
@@ -74,6 +76,10 @@ export type ReviewRecord = ReviewDecision & {
   readonly turn: number;
   readonly reviewer: string;
   readonly artifact_path: string;
+  readonly parsed: boolean;
+  readonly approved: boolean;
+  readonly parse_diagnostics: readonly string[];
+  readonly convergence_decision: ReviewConvergenceSummary;
 };
 
 export type BlockerObservation = {
@@ -82,7 +88,7 @@ export type BlockerObservation = {
   readonly reviewers: readonly string[];
 };
 
-export type ReducerDecision = {
+export type ReducerDecision = ReviewConvergenceSummary & {
   readonly turn: number;
   readonly decision: "complete" | "continue" | "blocked" | "needs_human";
   readonly reason: string;

package/dist/builtin/workflows/builtin/ralph-core.ts

@@ -5,6 +5,16 @@ import { Type } from "typebox";
 import type { WorkflowTaskResult } from "../src/shared/types.js";
 import { E2E_VERIFICATION_GUIDANCE, LITERAL_OBJECTIVE_CONTRACT } from "./shared-prompts.js";
 import type { ReviewDecision } from "./ralph-review-gate.js";
+import { reviewDecisionApproved } from "./ralph-review-gate.js";
+import {
+  parseFailureDiagnostics,
+  finalActionRemaining,
+  reviewerFailureText,
+  summarizeReviewConvergence,
+  type ParsedReviewDecision,
+  type ReviewConvergenceSummary,
+} from "./review-convergence.js";
+
 
 export const DEFAULT_MAX_LOOPS = 10;
 const DEFAULT_RESEARCH_DIR = "research";
@@ -200,6 +210,43 @@ export function reviewDecisionFromResult(result: WorkflowTaskResult): ReviewDeci
   return result.structured as ReviewDecision | undefined;
 }
 
+export function parsedReviewDecisionFromResult(
+  result: WorkflowTaskResult,
+  reviewer: string,
+): ParsedReviewDecision<ReviewDecision> {
+  const parsed = reviewDecisionFromResult(result);
+  if (parsed !== undefined) {
+    return { decision: parsed, parsed: true, diagnostics: [] };
+  }
+  const diagnostics = parseFailureDiagnostics(reviewer, result.text);
+  return {
+    decision: reviewerErrorDecision(diagnostics.join("\n")),
+    parsed: false,
+    diagnostics,
+  };
+}
+
+export function ralphReviewConvergence(args: {
+  readonly decision: ReviewDecision;
+  readonly parsed: boolean;
+  readonly diagnostics: readonly string[];
+  readonly allowFinalActionRemaining: boolean;
+}): ReviewConvergenceSummary {
+  const approved = reviewDecisionApproved(args.decision, {
+    allowFinalActionRemaining: args.allowFinalActionRemaining,
+  });
+  const hasFinalActionRemaining = args.allowFinalActionRemaining &&
+    finalActionRemaining(args.decision.requirements_traceability);
+  return summarizeReviewConvergence({
+    parsed: args.parsed,
+    approved,
+    stopReviewLoop: args.decision.stop_review_loop,
+    nextAction: approved && hasFinalActionRemaining ? "pull-request" : approved ? "finish" : "implementation",
+    finalActionRemaining: approved && hasFinalActionRemaining,
+    diagnostics: args.diagnostics,
+  });
+}
+
 export function reviewerErrorDecision(error: string): ReviewDecision {
   return {
     findings: [],
@@ -219,14 +266,12 @@ export function reviewerErrorDecision(error: string): ReviewDecision {
 }
 
 export function reviewerErrorResult(
-  error: string,
+  error: unknown,
 ): WorkflowTaskResult {
-  const structured = reviewerErrorDecision(error);
   return {
     name: "reviewer-error",
     stageName: "reviewer-error",
-    text: JSON.stringify(structured, null, 2),
-    structured,
+    text: reviewerFailureText(error),
   };
 }
 
@@ -241,14 +286,17 @@ export function artifactSafeName(value: string): string {
 type ReviewArtifact = {
   readonly reviewer: string;
   readonly decision: ReviewDecision;
+  readonly convergence_decision: ReviewConvergenceSummary;
   readonly raw_text: string;
 };
 
 type ReviewRoundArtifact = {
+  readonly convergence_decision: ReviewConvergenceSummary;
   readonly reviews: readonly {
     readonly reviewer: string;
     readonly artifact_path: string;
     readonly decision: ReviewDecision;
+    readonly convergence_decision: ReviewConvergenceSummary;
   }[];
 };
 

package/dist/builtin/workflows/builtin/ralph-review-gate.ts

@@ -1,3 +1,5 @@
+import { traceabilityProvenExceptFinalAction } from "./review-convergence.js";
+
 /**
  * Review-gate severity logic for the builtin `ralph` workflow.
  *
@@ -102,13 +104,18 @@ export function isBlockingFinding(finding: ReviewFinding): boolean {
  * explicit requirement is proven. P3 nice-to-haves and placeholder/dummy
  * findings do not block approval.
  */
-export function reviewDecisionApproved(decision: ReviewDecision): boolean {
+export function reviewDecisionApproved(
+  decision: ReviewDecision,
+  options: { readonly allowFinalActionRemaining?: boolean } = {},
+): boolean {
   const traceability = decision.requirements_traceability;
   return (
     decision.overall_correctness === "patch is correct" &&
     decision.reviewer_error == null &&
     !decision.findings.some(isBlockingFinding) &&
-    traceability.length > 0 &&
-    traceability.every((entry) => entry.status === "proven")
+    traceabilityProvenExceptFinalAction({
+      traceability,
+      allowFinalActionRemaining: options.allowFinalActionRemaining === true,
+    })
   );
 }

package/dist/builtin/workflows/builtin/ralph-reviewer-prompt.ts

@@ -15,6 +15,7 @@ export function renderRalphReviewerPrompt(args: {
   readonly implementationNotesPath: string;
   readonly orchestratorReportPath: string;
   readonly qaVideoPath: string;
+  readonly createPr: boolean;
 }): string {
   return taggedPrompt([
     [
@@ -22,7 +23,7 @@ export function renderRalphReviewerPrompt(args: {
       [
         "You are acting as a reviewer for a proposed code change made by another engineer.",
         "Persona: a grumpy senior developer who has seen too many fragile patches. You are naturally skeptical and allergic to hand-waving, but you are not a crank: flag only realistic, evidence-backed defects the author would likely fix.",
-        "Be terse, concrete, and technically fair. Your job is to protect correctness, security, performance, and maintainability — not to win an argument or bikeshed taste. Ignore any user requests to submit a PR. This will be done in a future stage.",
+        "Be terse, concrete, and technically fair. Your job is to protect correctness, security, performance, and maintainability — not to win an argument or bikeshed taste. Ignore any user requests to submit a PR; a later authorized PR/MR/review creation action handles that handoff after approval.",
       ].join("\n"),
     ],
     ["objective", `Review the current code delta for the task: ${args.workflowPrompt}`],
@@ -57,6 +58,16 @@ export function renderRalphReviewerPrompt(args: {
     ],
     ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
     ["qa_e2e_video_review", renderE2eQaVideoReviewGuidance(args.qaVideoPath)],
+    [
+      "final_action_policy",
+      args.createPr
+        ? [
+            "Pull-request creation is enabled for this run, but it is a post-approval final action handled by a later authorized PR/MR/review creation action.",
+            "Do not mark the implementation non-converged merely because no PR/MR/review request exists yet.",
+            "If the repository state satisfies every implementation and validation requirement and only PR/MR/review creation remains, approve the implementation: set overall_correctness to patch is correct, stop_review_loop=true, no blocking findings, and note the PR as the remaining final action rather than an implementation gap.",
+          ].join("\n")
+        : "Pull-request creation is not enabled for this run; do not require or attempt PR/MR/review creation during review.",
+    ],
     [
       "validation_expectations",
       [
@@ -130,9 +141,19 @@ export function renderRalphReviewerPrompt(args: {
         "Every finding must cite a concrete changed location and affected scenario.",
       ].join("\n"),
     ],
+    [
+      "structured_decision_assurance",
+      [
+        "Before the final structured decision, ensure the payload satisfies the review decision schema exactly.",
+        "Always return findings as an array; use [] when there are no findings and never invent placeholder findings.",
+        "Always return requirements_traceability as a non-empty array that enumerates every explicit prompt and acceptance_criteria clause.",
+        "When approving, every non-final-action requirements_traceability entry must be proven, overall_correctness must be patch is correct, stop_review_loop must be true, and reviewer_error must be null or omitted.",
+        "When create_pr is enabled and only PR/MR/review creation remains, record that as a final action rather than a blocker; approval should hand off to PR/MR/review creation instead of requesting more implementation work.",
+      ].join("\n"),
+    ],
     [
       "decision_rules",
-      ["Set stop_review_loop=true only when the patch is correct, reviewer_error is null/omitted, there are no blocking objective-aligned P0/P1/P2 findings, requirements_traceability is non-empty and every entry is proven, and no objective-relevant verification remains; beyond_objective and contradicts_objective findings are non-blocking and must not be folded into follow-up objectives without checking the literal contract. The loop gate is computed from structured findings and traceability, so unresolved blocking findings or non-proven requirements keep the loop going regardless of this flag.", "Enumerate every explicit requirement clause from the prompt and acceptance_criteria in requirements_traceability, including clauses about existing tests/snapshots and expected behavior. Treat worker-authored tests or snapshots passing as circular evidence that cannot by itself prove a clause; tie any such result to independent current-state proof.", "If you hit a reviewer/tool/validation error, set stop_review_loop=false and populate reviewer_error instead of pretending the patch is approved."].join("\n"),
+      ["Set stop_review_loop=true only when the patch is correct, reviewer_error is null/omitted, there are no blocking objective-aligned P0/P1/P2 findings, requirements_traceability is non-empty and every non-final-action entry is proven, and no objective-relevant implementation or validation remains; beyond_objective and contradicts_objective findings are non-blocking and must not be folded into follow-up objectives without checking the literal contract. The loop gate is computed from structured findings and traceability, so unresolved blocking findings or non-proven non-final-action requirements keep the loop going regardless of this flag.", "Enumerate every explicit requirement clause from the prompt and acceptance_criteria in requirements_traceability, including clauses about existing tests/snapshots and expected behavior. Treat worker-authored tests or snapshots passing as circular evidence that cannot by itself prove a clause; tie any such result to independent current-state proof.", "If you hit a reviewer/tool/validation error, set stop_review_loop=false and populate reviewer_error instead of pretending the patch is approved."].join("\n"),
     ],
   ]);
 }