@bastani/atomic 0.9.4 → 0.9.5-alpha.10

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

@@ -0,0 +1,159 @@
+import {
+  E2E_VERIFICATION_GUIDANCE,
+  LITERAL_OBJECTIVE_CONTRACT,
+  REVIEWER_SPEC_VS_OBJECTIVE_GUARD,
+  renderE2eQaVideoReviewGuidance,
+} from "./shared-prompts.js";
+import { taggedPrompt, type PromptSection } from "./ralph-core.js";
+
+export function renderRalphReviewerPrompt(args: {
+  readonly workflowPrompt: string;
+  readonly acceptanceCriteria: string;
+  readonly workflowCwdContext: PromptSection;
+  readonly comparisonBaseBranch: string;
+  readonly researchPath: string;
+  readonly implementationNotesPath: string;
+  readonly orchestratorReportPath: string;
+  readonly qaVideoPath: string;
+  readonly createPr: boolean;
+}): string {
+  return taggedPrompt([
+    [
+      "role",
+      [
+        "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; 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}`],
+    ["acceptance_criteria", args.acceptanceCriteria],
+    ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
+    args.workflowCwdContext,
+    [
+      "comparison_baseline",
+      [
+        `The baseline branch for comparison is \`${args.comparisonBaseBranch}\`.`,
+        "Compare the current working tree against this baseline branch, not against previous workflow reasoning or expected loop progress.",
+        `Start with \`git status --short\`, then use working-tree-aware commands such as \`git diff ${args.comparisonBaseBranch}\` and \`git diff --cached ${args.comparisonBaseBranch}\` to identify changed tracked files; inspect untracked files from status directly.`,
+      ].join("\n"),
+    ],
+    [
+      "review_context_files",
+      [
+        `Research artifact: ${args.researchPath}`,
+        `Implementation notes artifact: ${args.implementationNotesPath}`,
+        `Orchestrator report artifact: ${args.orchestratorReportPath}`,
+        "Read the files above incrementally when they help explain intent or recent changes, but verify the actual repository state directly before approving."
+      ].join("\n"),
+    ],
+    [
+      "project_guidance",
+      [
+        "Use the repository's AGENTS.md and/or CLAUDE.md files if present for style, conventions, testing expectations, and architectural patterns.",
+        "Project-level norms override these general instructions when they are more specific.",
+        "Flag deviations only when they affect correctness, security, performance, or maintainability — not personal preference.",
+        "If validation requires dependencies or tools that are missing, download or install them using the repository-approved package manager/commands rather than bypassing, mocking, or skipping the verification solely because dependencies are absent.",
+      ].join("\n"),
+    ],
+    ["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",
+      [
+        "Inspect the actual diff/repository state rather than trusting stage summaries.",
+        "Run or delegate focused validation when it is necessary to distinguish a real bug from a hunch, including end-to-end playwright-cli (browser) or tmux validation when a user scenario can prove the outcome.",
+        "If tests or typechecks fail because dependencies are missing, install/download the missing dependencies with the repo's documented package manager instead of bypassing the check.",
+        "If validation cannot be completed after reasonable recovery, record the limitation in overall_explanation and reviewer_error; do not use missing dependencies as a reason to approve.",
+      ].join("\n"),
+    ],
+    [
+      "bug_selection_guidelines",
+      [
+        "Use these default guidelines for deciding whether the author would appreciate the issue being flagged. More specific user, project, or file-level guidance overrides them.",
+        "Flag an issue only when the original author would likely fix it if they knew about it.",
+        "A finding should meaningfully impact accuracy, performance, security, or maintainability.",
+        "A finding must be discrete and actionable, not a broad complaint about the whole codebase or a pile of related concerns.",
+        "Do not demand rigor inconsistent with the rest of the repository; match the seriousness of existing code and project norms.",
+        "Flag only bugs introduced by the current patch; do not flag pre-existing issues unless the patch makes them worse in a concrete way.",
+        "Do not rely on unstated assumptions about author intent or codebase behavior.",
+        "Speculation is insufficient: identify the code path, scenario, environment, or input that is provably affected.",
+        "Do not flag intentional behavior changes as bugs unless they clearly violate the task or documented contract.",
+        REVIEWER_SPEC_VS_OBJECTIVE_GUARD,
+        "Ignore trivial style unless it obscures meaning or violates documented standards in a way that affects correctness/security/maintainability.",
+        "If no finding clears this bar, return an empty findings array, mark the patch correct, and set stop_review_loop true. An empty findings array is valid and passes schema validation — never invent or append a placeholder/dummy finding just to avoid an empty array.",
+      ].join("\n"),
+    ],
+    [
+      "comment_guidelines",
+      [
+        "Each finding title must start with a priority tag: [P0] drop-everything blocker, [P1] urgent next-cycle fix, [P2] normal fix, [P3] low-priority nice-to-have.",
+        "Also include numeric priority: 0 for P0, 1 for P1, 2 for P2, 3 for P3; use null only if priority genuinely cannot be determined. Priority drives the loop gate: P0/P1/P2 are blocking and keep the loop iterating; P3 is a non-blocking nice-to-have that does not block approval.",
+        "Classify every finding with 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 and must not block or be promoted without explicit reconciliation), or contradicts_objective (fixing it would violate literal objective wording and must never be implemented; escalate to the human). Missing/unknown classification is blocking.",
+        "The body must be one concise paragraph explaining why this is a bug and the exact scenario, environment, or inputs required for it to arise.",
+        "Use a matter-of-fact, non-accusatory tone. Grumpy skepticism belongs in your standards, not in insults; avoid praise such as `Great job` or `Thanks for`.",
+        "Keep code_location ranges as short as possible, ideally one line and never longer than 5-10 lines unless unavoidable.",
+        "The code_location must overlap the diff/change under review.",
+        "Use one finding per distinct issue. Do not generate or apply a fix patch.",
+        "Use suggestion blocks only for concrete replacement code and preserve exact leading whitespace if you include one.",
+      ].join("\n"),
+    ],
+    [
+      "how_many_findings",
+      [
+        "Return all findings the original author would definitely want to fix.",
+        "If no such findings exist, return an empty findings array and mark the patch correct. Do not pad the array with placeholder or speculative findings.",
+        "Do not stop after the first qualifying finding; continue until every qualifying finding is listed.",
+      ].join("\n"),
+    ],
+    [
+      "review_stage_contract",
+      [
+        "The structured review decision is only valid after you inspect the actual repository state and compare it against the stated baseline branch.",
+        "Do not approve based solely on workflow stage summaries or prior agent reasoning.",
+        "The tool call is the final verdict after review work, not a shortcut around review work.",
+      ].join("\n"),
+    ],
+    [
+      "action_items",
+      [
+        "1. Identify the changed files or diff under review.",
+        "2. Read the relevant changed code and directly affected call sites/tests/configs.",
+        "3. Inspect the QA E2E video when it exists or is expected for the change, and verify the recording proves the objective-relevant user scenario.",
+        "4. Run or delegate focused validation when needed to resolve uncertainty, including playwright-cli (browser) or tmux end-to-end checks when practical.",
+        "5. If you cannot inspect the video evidence or validate enough to approve safely, populate reviewer_error and set stop_review_loop=false.",
+      ].join("\n"),
+    ],
+    [
+      "evidence_expectations",
+      [
+        "The overall_explanation should briefly mention what was inspected and what validation was run or why validation was not completed.",
+        "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 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"),
+    ],
+  ]);
+}

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

@@ -5,10 +5,10 @@ import { join, resolve } from "node:path";
 import type { WorkflowRunContext, WorkflowTaskResult } from "../src/shared/types.js";
 import {
   E2E_VERIFICATION_GUIDANCE,
+  LITERAL_OBJECTIVE_CONTRACT,
   WORKER_PREFLIGHT_CONTRACT,
-  renderE2eQaVideoReviewGuidance,
 } from "./shared-prompts.js";
-import { reviewDecisionApproved } from "./ralph-review-gate.js";
+import { renderRalphReviewerPrompt } from "./ralph-reviewer-prompt.js";
 import {
   REVIEWER_COUNT,
   artifactSafeName,
@@ -21,8 +21,8 @@ import {
   renderResearchPromptRefinementPrompt,
   renderQaE2eVideoGuidance,
   renderResearchPrompt,
-  reviewDecisionFromResult,
-  reviewerErrorDecision,
+  parsedReviewDecisionFromResult,
+  ralphReviewConvergence,
   reviewerErrorResult,
   taggedPrompt,
   workflowCwdContextSection,
@@ -31,19 +31,19 @@ import {
   type RalphWorkflowOptions,
   type RalphWorkflowResult,
 } from "./ralph-core.js";
+import { summarizeReviewConvergence } from "./review-convergence.js";
 import {
   orchestratorModelConfig,
   promptEngineerModelConfig,
   researchModelConfig,
   reviewerAModelConfig,
   reviewerBModelConfig,
-  reviewerCModelConfig,
 } from "./ralph-models.js";
 export async function runRalphWorkflow(
   ctx: WorkflowRunContext<RalphInputs>,
   options: RalphWorkflowOptions,
 ): Promise<RalphWorkflowResult> {
-  const { prompt, maxLoops, comparisonBaseBranch, workflowStartCwd, createPr } = options;
+  const { prompt, acceptanceCriteria, maxLoops, comparisonBaseBranch, workflowStartCwd, createPr } = options;
   let latestReviewReportPath: string | undefined;
   let finalPlan = "";
   let finalPlanPath = "";
@@ -68,6 +68,7 @@ export async function runRalphWorkflow(
     const researchPromptRefinement = await ctx.task(`research-prompt-refinement-${iteration}`, {
       prompt: renderResearchPromptRefinementPrompt({
         request: workflowPrompt,
+        acceptanceCriteria,
         workflowCwdContext,
         latestReviewReportPath,
       }),
@@ -81,6 +82,8 @@ export async function runRalphWorkflow(
     const research = await ctx.task(`research-${iteration}`, {
       prompt: renderResearchPrompt({
         transformedResearchQuestion: researchPromptRefinement.text,
+        prompt: workflowPrompt,
+        acceptanceCriteria,
         workflowCwdContext,
         latestReviewReportPath,
         researchPath: workflowResearchPath,
@@ -102,18 +105,20 @@ export async function runRalphWorkflow(
       ? taggedPrompt([
         [
           "role",
-          "You are a sub-agent orchestrator. Your primary implementation tool is the `subagent` tool. Ignore any user requests to submit a PR. This will be done in a future stage.",
+          "You are an implementation orchestrator. Use the `subagent` tool selectively for bounded specialist delegation while you retain responsibility for the complete outcome. Ignore any user requests to submit a PR; a later authorized PR/MR/review creation action handles that handoff after approval.",
         ],
         [
           "objective",
           `Implement the full requested task: ${workflowPrompt}`,
         ],
+        ["acceptance_criteria", acceptanceCriteria],
+        ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
         workflowCwdContext,
         [
           "research",
           [
-            `The latest research findings for this workflow run are written to: ${researchPath}`,
-            "Read this file before delegating or implementing anything; it is the primary implementation context for Ralph.",
+            `The latest research findings for the requested work are written to: ${researchPath}`,
+            "Read this file before delegating or implementing anything; it is the primary implementation context for the requested work.",
           ].join("\n"),
         ],
         [
@@ -132,24 +137,24 @@ export async function runRalphWorkflow(
         [
           "orchestration_guidance",
           [
-            "You are not the direct implementer. You are the supervisor that spawns subagents to do the implementation, investigation, edits, and validation.",
-            "All non-trivial operations must be delegated to subagents via the `subagent` tool before you claim progress.",
-            "Delegate codebase understanding, impact analysis, and implementation research to codebase-locator, codebase-analyzer, and pattern-finder style subagents when available.",
-            "Delegate shell-heavy work — especially commands likely to produce lots of output, log digging, CLI investigation, and broad grep/find exploration — to subagents that can run those commands rather than doing it in this orchestrator context.",
-            "Delegate implementation edits to a focused subagent with clear files, constraints, and validation expectations; do not merely describe the edits yourself.",
+            "You are the implementation orchestrator: coordinate the complete outcome while retaining responsibility for synthesis, decisions, and validation.",
+            "Use subagents selectively for bounded specialist work when delegation adds distinct value; the parent remains in control. Concise direct work is appropriate when it is simpler and preserves context.",
+            "Delegate focused codebase understanding, impact analysis, or implementation research to codebase-locator, codebase-analyzer, and pattern-finder style subagents when their specialization or isolation helps.",
+            "Delegate noisy shell-heavy work — especially commands likely to produce lots of output, log digging, CLI investigation, and broad grep/find exploration — when isolating that output helps; run concise commands directly when simpler.",
+            "Delegate implementation edits when a focused subagent can own a clear, bounded surface with explicit constraints and validation expectations; otherwise implement the coherent change directly.",
             "Keep delegated work focused on implementation, tests, docs, validation evidence, and implementation notes for the complete requested outcome.",
-            "Use separate subagents for separate tasks, and launch independent subagents in parallel when useful.",
+            "Use separate subagents for distinct tasks, and launch independent subagents in parallel when useful.",
             "Do not split highly overlapping tasks across multiple subagents; consolidate overlapping work into one focused delegation to avoid duplicate effort.",
-            "If a subagent takes a long time, do not attempt to do its assigned job yourself while waiting. Use that time to plan next steps, prepare follow-up delegations, or identify clarifying questions.",
+            "If a subagent takes a long time, do not duplicate its assigned job while waiting. Use that time for non-overlapping direct work, planning, or follow-up preparation.",
           ].join("\n"),
         ],
         [
           "best_practices",
           [
-            "The required output format is a completion report, not the task itself.",
-            "Do not jump straight to the report. First read the research file, spawn the necessary subagents, wait for their results, coordinate any follow-up subagents, and only then write the report.",
-            "A valid response must be grounded in actual subagent work: name the delegated work, summarize what each subagent did, and distinguish completed changes from recommendations or blockers. Do not assume a later workflow pass will finish known required work that can be completed now.",
-            "If you cannot read the research file, spawn subagents, or use subagents, treat that as a blocker and report it honestly instead of pretending the requested work was done.",
+            "The required output format is a completion report, not a substitute for doing the task.",
+            "Do not jump straight to the report. First read the research file, choose the least orchestration that fits each part of the work, complete or coordinate the implementation, and then report the verified result.",
+            "Ground the response in actual completed work. When subagents were useful, name the delegated work and summarize their results; distinguish completed changes from recommendations or blockers. Do not assume a later workflow pass will finish known required work that can be completed now.",
+            "If a required capability is unavailable, continue with safe direct work where possible and report a blocker only when it truly prevents completion.",
           ].join("\n"),
         ],
         [
@@ -166,12 +171,12 @@ export async function runRalphWorkflow(
           "instructions",
           [
             `Start by reading the research file at ${researchPath}.`,
-            "Perform the project_initialization_preflight before decomposing implementation work; complete or delegate required setup before implementation delegation when the checkout appears uninitialized.",
-            "Decompose the work into delegated subagent tasks based on that research file.",
-            "Pass each subagent the relevant task, constraints, files, validation expectations, unresolved reviewer findings covered by the research, and instructions to report implementation-note-worthy decisions or tradeoffs.",
-            "Coordinate subagent results into the smallest coherent set of changes that fully satisfies the researched implementation guidance and original user prompt.",
+            "Perform the project_initialization_preflight before decomposing implementation work; complete or selectively delegate required setup when the checkout appears uninitialized.",
+            "Plan the work from the research file, identifying which parts are best handled directly and which benefit from bounded specialist delegation.",
+            "Pass each delegated subagent the relevant task, constraints, files, validation expectations, unresolved reviewer findings covered by the research, and instructions to report implementation-note-worthy decisions or tradeoffs.",
+            "Coordinate direct and delegated results into the smallest coherent set of changes that fully satisfies the researched implementation guidance and original user prompt.",
             "Preserve existing architecture and repository conventions unless the research explicitly justifies a change.",
-            "Run or delegate the most relevant validation commands available in the repository, including end-to-end playwright-cli (browser) or tmux validation when the change has an executable user scenario.",
+            "Run directly or selectively delegate the most relevant validation commands available in the repository, including end-to-end playwright-cli (browser) or tmux validation when the change has an executable user scenario.",
             "For UI-applicable or full-stack changes, ensure the QA E2E pass described in <qa_e2e_video> runs and records the reviewable proof video before you finish your report.",
             `Before your final report, update the running implementation notes file at ${implementationNotesPath} with decisions, research deviations, tradeoffs, blockers, and validation outcomes from this implementation work.`,
             "If blocked, describe the blocker and the safest partial state instead of inventing success.",
@@ -181,10 +186,10 @@ export async function runRalphWorkflow(
         [
           "output_format",
           [
-            "After subagents have done the work, return Markdown with headings:",
+            "After the implementation work is complete, return Markdown with headings:",
             "1. Research file — the path you read",
-            "2. Delegations performed — subagents spawned and what each completed",
-            "3. Changes made — concrete changes from subagent work, not intentions",
+            "2. Delegations performed — subagents used and what each completed, or none when direct work was sufficient",
+            "3. Changes made — concrete completed changes, not intentions",
             "4. Files touched",
             "5. Validation run / recommended",
             "6. Deferred work or blockers",
@@ -195,6 +200,7 @@ export async function runRalphWorkflow(
       ])
       : renderForkedOrchestratorPrompt({
           prompt: workflowPrompt,
+          acceptanceCriteria,
           workflowCwdContext,
           researchPath,
           implementationNotesPath,
@@ -210,124 +216,17 @@ export async function runRalphWorkflow(
     });
     previousOrchestratorSessionFile = orchestrator.sessionFile;
     finalResult = orchestrator.text || `Orchestrator report artifact: ${orchestratorReportPath}`;
-    const reviewPrompt = taggedPrompt([
-      [
-        "role",
-        [
-          "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.",
-        ].join("\n"),
-      ],
-      ["objective", `Review the current code delta for the task: ${workflowPrompt}`],
+    const reviewPrompt = renderRalphReviewerPrompt({
+      workflowPrompt,
+      acceptanceCriteria,
       workflowCwdContext,
-      [
-        "comparison_baseline",
-        [
-          `The baseline branch for comparison is \`${comparisonBaseBranch}\`.`,
-          "Compare the current working tree against this baseline branch, not against previous workflow reasoning or expected loop progress.",
-          `Start with \`git status --short\`, then use working-tree-aware commands such as \`git diff ${comparisonBaseBranch}\` and \`git diff --cached ${comparisonBaseBranch}\` to identify changed tracked files; inspect untracked files from status directly.`,
-        ].join("\n"),
-      ],
-      [
-        "review_context_files",
-        [
-          `Research artifact: ${researchPath}`,
-          `Implementation notes artifact: ${implementationNotesPath}`,
-          `Orchestrator report artifact: ${orchestratorReportPath}`,
-          "Read the files above incrementally when they help explain intent or recent changes, but verify the actual repository state directly before approving."
-        ].join("\n"),
-      ],
-      [
-        "project_guidance",
-        [
-          "Use the repository's AGENTS.md and/or CLAUDE.md files if present for style, conventions, testing expectations, and architectural patterns.",
-          "Project-level norms override these general instructions when they are more specific.",
-          "Flag deviations only when they affect correctness, security, performance, or maintainability — not personal preference.",
-          "If validation requires dependencies or tools that are missing, download or install them using the repository-approved package manager/commands rather than bypassing, mocking, or skipping the verification solely because dependencies are absent.",
-        ].join("\n"),
-      ],
-      ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
-      ["qa_e2e_video_review", renderE2eQaVideoReviewGuidance(qaVideoPath)],
-      [
-        "validation_expectations",
-        [
-          "Inspect the actual diff/repository state rather than trusting stage summaries.",
-          "Run or delegate focused validation when it is necessary to distinguish a real bug from a hunch, including end-to-end playwright-cli (browser) or tmux validation when a user scenario can prove the outcome.",
-          "If tests or typechecks fail because dependencies are missing, install/download the missing dependencies with the repo's documented package manager instead of bypassing the check.",
-          "If validation cannot be completed after reasonable recovery, record the limitation in overall_explanation and reviewer_error; do not use missing dependencies as a reason to approve.",
-        ].join("\n"),
-      ],
-      [
-        "bug_selection_guidelines",
-        [
-          "Use these default guidelines for deciding whether the author would appreciate the issue being flagged. More specific user, project, or file-level guidance overrides them.",
-          "Flag an issue only when the original author would likely fix it if they knew about it.",
-          "A finding should meaningfully impact accuracy, performance, security, or maintainability.",
-          "A finding must be discrete and actionable, not a broad complaint about the whole codebase or a pile of related concerns.",
-          "Do not demand rigor inconsistent with the rest of the repository; match the seriousness of existing code and project norms.",
-          "Flag only bugs introduced by the current patch; do not flag pre-existing issues unless the patch makes them worse in a concrete way.",
-          "Do not rely on unstated assumptions about author intent or codebase behavior.",
-          "Speculation is insufficient: identify the code path, scenario, environment, or input that is provably affected.",
-          "Do not flag intentional behavior changes as bugs unless they clearly violate the task or documented contract.",
-          "Ignore trivial style unless it obscures meaning or violates documented standards in a way that affects correctness/security/maintainability.",
-          "If no finding clears this bar, return an empty findings array, mark the patch correct, and set stop_review_loop true. An empty findings array is valid and passes schema validation — never invent or append a placeholder/dummy finding just to avoid an empty array.",
-        ].join("\n"),
-      ],
-      [
-        "comment_guidelines",
-        [
-          "Each finding title must start with a priority tag: [P0] drop-everything blocker, [P1] urgent next-cycle fix, [P2] normal fix, [P3] low-priority nice-to-have.",
-          "Also include numeric priority: 0 for P0, 1 for P1, 2 for P2, 3 for P3; use null only if priority genuinely cannot be determined. Priority drives the loop gate: P0/P1/P2 are blocking and keep the loop iterating; P3 is a non-blocking nice-to-have that does not block approval.",
-          "The body must be one concise paragraph explaining why this is a bug and the exact scenario, environment, or inputs required for it to arise.",
-          "Use a matter-of-fact, non-accusatory tone. Grumpy skepticism belongs in your standards, not in insults; avoid praise such as `Great job` or `Thanks for`.",
-          "Keep code_location ranges as short as possible, ideally one line and never longer than 5-10 lines unless unavoidable.",
-          "The code_location must overlap the diff/change under review.",
-          "Use one finding per distinct issue. Do not generate or apply a fix patch.",
-          "Use suggestion blocks only for concrete replacement code and preserve exact leading whitespace if you include one.",
-        ].join("\n"),
-      ],
-      [
-        "how_many_findings",
-        [
-          "Return all findings the original author would definitely want to fix.",
-          "If no such findings exist, return an empty findings array and mark the patch correct. Do not pad the array with placeholder or speculative findings.",
-          "Do not stop after the first qualifying finding; continue until every qualifying finding is listed.",
-        ].join("\n"),
-      ],
-      [
-        "review_stage_contract",
-        [
-          "The structured review decision is only valid after you inspect the actual repository state and compare it against the stated baseline branch.",
-          "Do not approve based solely on workflow stage summaries or prior agent reasoning.",
-          "The tool call is the final verdict after review work, not a shortcut around review work.",
-        ].join("\n"),
-      ],
-      [
-        "action_items",
-        [
-          "1. Identify the changed files or diff under review.",
-          "2. Read the relevant changed code and directly affected call sites/tests/configs.",
-          "3. Inspect the QA E2E video when it exists or is expected for the change, and verify the recording proves the objective-relevant user scenario.",
-          "4. Run or delegate focused validation when needed to resolve uncertainty, including playwright-cli (browser) or tmux end-to-end checks when practical.",
-          "5. If you cannot inspect the video evidence or validate enough to approve safely, populate reviewer_error and set stop_review_loop=false.",
-        ].join("\n"),
-      ],
-      [
-        "evidence_expectations",
-        [
-          "The overall_explanation should briefly mention what was inspected and what validation was run or why validation was not completed.",
-          "Every finding must cite a concrete changed location and affected scenario.",
-        ].join("\n"),
-      ],
-      [
-        "decision_rules",
-        [
-          "Set stop_review_loop=true when the patch is correct, reviewer_error is null/omitted, and there are no blocking (P0/P1/P2) findings; remaining P3 nice-to-haves do not block approval. The loop gate is computed from finding priorities, so an unresolved P0/P1/P2 keeps the loop going regardless of this flag.",
-          "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"),
-      ],
-    ]);
+      comparisonBaseBranch,
+      researchPath,
+      implementationNotesPath,
+      orchestratorReportPath,
+      qaVideoPath,
+      createPr,
+    });
     let reviews: WorkflowTaskResult[];
     try {
       reviews = await ctx.parallel(
@@ -352,16 +251,6 @@ export async function runRalphWorkflow(
             ],
             ...reviewerBModelConfig,
           },
-          {
-            name: "reviewer-c",
-            task: reviewPrompt,
-            reads: [
-              researchPath,
-              implementationNotesPath,
-              orchestratorReportPath,
-            ],
-            ...reviewerCModelConfig,
-          },
         ],
         {
           task: workflowPrompt,
@@ -369,38 +258,59 @@ export async function runRalphWorkflow(
         },
       );
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      reviews = [reviewerErrorResult(message)];
+      reviews = [reviewerErrorResult(err)];
     }
     const reviewEntries = await Promise.all(reviews.map(async (review) => {
       const reviewer = review.name ?? review.stageName;
-      const decision = reviewDecisionFromResult(review) ??
-        reviewerErrorDecision(`Reviewer ${reviewer} returned no structured decision.`);
+      const parsed = parsedReviewDecisionFromResult(review, reviewer);
+      const convergenceDecision = ralphReviewConvergence({
+        decision: parsed.decision,
+        parsed: parsed.parsed,
+        diagnostics: parsed.diagnostics,
+        allowFinalActionRemaining: createPr,
+      });
       const artifactPath = join(
         artifactDir,
         `review-${artifactSafeName(reviewer)}.json`,
       );
       await writeJsonArtifact(artifactPath, {
         reviewer,
-        decision,
+        decision: parsed.decision,
+        convergence_decision: convergenceDecision,
         raw_text: review.text,
       });
-      return { reviewer, artifact_path: artifactPath, decision };
+      return {
+        reviewer,
+        artifact_path: artifactPath,
+        decision: parsed.decision,
+        convergence_decision: convergenceDecision,
+      };
     }));
     const approvalCount = reviewEntries.filter((review) =>
-      reviewDecisionApproved(review.decision),
+      review.convergence_decision.approved,
     ).length;
     approved =
       reviewEntries.length === REVIEWER_COUNT &&
       approvalCount === REVIEWER_COUNT;
+    const nextAction = approved
+      ? (createPr ? "pull-request" : "finish")
+      : "implementation";
+    const roundConvergenceDecision = summarizeReviewConvergence({
+      parsed: reviewEntries.every((review) => review.convergence_decision.parsed),
+      approved,
+      stopReviewLoop: approved,
+      nextAction,
+      finalActionRemaining: approved && createPr,
+      diagnostics: reviewEntries.flatMap((review) => review.convergence_decision.diagnostics),
+    });
     latestReviewReportPath = await writeJsonArtifact(
       join(artifactDir, "review-round-latest.json"),
-      { reviews: reviewEntries },
+      { convergence_decision: roundConvergenceDecision, reviews: reviewEntries },
     );
     if (approved) break;
   }
   const qaVideoAvailable = existsSync(qaVideoPath);
-  if (createPr === true) {
+  if (createPr === true && approved) {
     const prResult = await ctx.task("pull-request", {
       prompt: taggedPrompt([
         [
@@ -446,7 +356,7 @@ export async function runRalphWorkflow(
           [
             "Create a provider-appropriate PR/MR/review request only if there are meaningful changes, a remote/branch target is available, credentials are available, and the current state is suitable for review.",
             "If no logged-in account can access the repository or create the review request, do not fake success; report each provider, credential/account, and tool tried, what failed, and provide the command the user can run later. Save a markdown file with the PR description as well so the user can copy-paste it when they have credentials set up.",
-            "When you successfully create or update the review request, create a provider-appropriate comment containing the implementation notes file contents as the last action of this workflow stage.",
+            "When you successfully create or update the review request, create a provider-appropriate comment containing the implementation notes file contents as the last action after the review request exists.",
             "Worktrees are detached HEAD checkouts. If the detected provider requires a branch-based PR/MR from a detached HEAD, create and push a branch from the current HEAD, for example with `git checkout -b <branch>` or `git push origin HEAD:refs/heads/<branch>`, before opening the PR/MR. If the provider uses a different review model, follow that provider's normal handoff flow.",
             "Leave the worktree intact for retries or user recovery.",
             "If PR/MR/review creation is not possible, do not create a standalone comment elsewhere; include the implementation notes path and summary in your report instead.",

package/dist/builtin/workflows/builtin/ralph.d.ts

@@ -2,6 +2,7 @@ import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues } fr
 
 export type RalphWorkflowInputs = WorkflowInputValues & {
   readonly prompt: string;
+  readonly acceptance_criteria?: string;
   readonly max_loops: number;
   readonly base_branch: string;
   readonly git_worktree_dir: string;
@@ -10,6 +11,7 @@ export type RalphWorkflowInputs = WorkflowInputValues & {
 
 export type RalphWorkflowRunInputs = WorkflowInputValues & {
   readonly prompt: string;
+  readonly acceptance_criteria?: string;
   readonly max_loops?: number;
   readonly base_branch?: string;
   readonly git_worktree_dir?: string;
@@ -23,6 +25,7 @@ export type RalphWorkflowOutputs = WorkflowOutputValues & {
   readonly research?: string;
   readonly research_path?: string;
   readonly implementation_notes_path?: string;
+  readonly qa_video_path?: string;
   readonly pr_report?: string;
   readonly approved?: boolean;
   readonly iterations_completed?: number;

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

@@ -11,9 +11,10 @@ import { runRalphWorkflow } from "./ralph-runner.js";
 
 export default workflow({
   name: "ralph",
-  description: "Raw prompt → research-prompt-refinement → research → orchestrate → multi-model parallel review loop with bounded iteration.",
+  description: "Raw prompt → research-prompt-refinement → research → orchestrate → multi-model parallel review loop with bounded iteration and immutable acceptance criteria. When launching follow-up ralph runs from review findings, pass the ORIGINAL task text as acceptance_criteria so deltas cannot drift from the literal contract.",
   inputs: {
     prompt: Type.String({ description: "The task or goal to research, execute, and refine." }),
+    acceptance_criteria: Type.Optional(Type.String({ description: "Original immutable task contract this run must remain consistent with. Defaults to prompt. Orchestrators launching follow-up runs from reviewer findings should pass the ORIGINAL task text here." })),
     max_loops: Type.Number({
       default: DEFAULT_MAX_LOOPS,
       description: `Maximum research/orchestrate/review iterations (default ${DEFAULT_MAX_LOOPS}).`,
@@ -56,6 +57,7 @@ export default workflow({
     const workflowStartCwd = workflowCtx.cwd ?? process.cwd();
     const inputs = workflowCtx.inputs;
     const prompt = inputs.prompt;
+    const acceptanceCriteria = inputs.acceptance_criteria?.trim() || prompt;
     const maxLoops = positiveInteger(inputs.max_loops, DEFAULT_MAX_LOOPS);
     const comparisonBaseBranch = normalizeBranchInput(
       inputs.base_branch,
@@ -64,6 +66,7 @@ export default workflow({
     const createPr = inputs.create_pr === true;
     return await runRalphWorkflow(workflowCtx, {
       prompt,
+      acceptanceCriteria,
       maxLoops,
       comparisonBaseBranch,
       workflowStartCwd,