@bastani/atomic 0.9.11-alpha.4 → 0.9.11-alpha.6

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

@@ -1,4 +1,5 @@
 import {
+  ACCEPTANCE_MATRIX_CONTRACT,
   E2E_VERIFICATION_GUIDANCE,
   EVIDENCE_CLOSURE_POLICY,
   LITERAL_OBJECTIVE_CONTRACT,
@@ -8,6 +9,7 @@ import {
   REVIEWER_INTERCOM_COORDINATION_PROTOCOL,
   REVIEWER_OVERIMPLEMENTATION_GUARD,
   REVIEWER_SPEC_VS_OBJECTIVE_GUARD,
+  WORKTREE_DISCIPLINE_CONTRACT,
   renderE2eQaVideoReviewGuidance,
 } from "./shared-prompts.js";
 import { taggedPrompt, type PromptSection } from "./ralph-core.js";
@@ -24,155 +26,71 @@ export function renderRalphReviewerPrompt(args: {
   readonly createPr: boolean;
 }): string {
   return taggedPrompt([
+    ["acceptance_criteria", args.acceptanceCriteria],
     [
-      "role",
+      "review_context",
       [
-        "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.",
+        `Task: ${args.workflowPrompt}`,
+        `Research artifact: ${args.researchPath}`,
+        `Implementation notes artifact: ${args.implementationNotesPath}`,
+        `Orchestrator report artifact: ${args.orchestratorReportPath}`,
+        `Comparison baseline: ${args.comparisonBaseBranch}`,
       ].join("\n"),
     ],
-    ["objective", `Review the current code delta for the task: ${args.workflowPrompt}`],
-    ["acceptance_criteria", args.acceptanceCriteria],
+    args.workflowCwdContext,
     ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
+    ["acceptance_matrix", ACCEPTANCE_MATRIX_CONTRACT],
     ["independent_verification", REVIEWER_INDEPENDENT_VERIFICATION_CONTRACT],
     ["code_delta_review", REVIEW_CODE_DELTA_CONTRACT],
+    ["worktree_discipline", WORKTREE_DISCIPLINE_CONTRACT],
     ["reviewer_coordination", REVIEWER_INTERCOM_COORDINATION_PROTOCOL],
     ["regression_evidence", REGRESSION_EVIDENCE_CONTRACT],
+    ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
+    ["qa_e2e_video_review", renderE2eQaVideoReviewGuidance(args.qaVideoPath)],
     ["evidence_closure", EVIDENCE_CLOSURE_POLICY],
-    args.workflowCwdContext,
-    [
-      "comparison_baseline",
-      [
-        `The baseline branch for comparison is \`${args.comparisonBaseBranch}\`.`,
-        "Compare the current working tree against this baseline branch.",
-        `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.",
+        "Use repository AGENTS.md and/or CLAUDE.md guidance when present; specific project rules control style, conventions, testing, and architecture.",
+        "Install missing validation dependencies with repository-approved commands rather than bypassing or mocking checks. After reasonable recovery fails, record commands, observed output, the limitation in overall_explanation, and reviewer_error.",
       ].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"),
+        ? "PR/MR/review creation is an authorized post-approval final action. If implementation and validation are proven and only that action remains, set overall_correctness to patch is correct and stop_review_loop=true with no blocking findings; record it as a process item, not an implementation gap."
+        : "PR/MR/review creation is not enabled; do not require or attempt it during review.",
     ],
     [
-      "bug_selection_guidelines",
+      "finding_contract",
       [
-        "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.",
+        "Report every discrete, actionable defect introduced or concretely worsened by the patch that the author would likely fix because it materially affects accuracy, performance, security, or maintainability. Match repository rigor; exclude taste, speculation, broad complaints, intentional contract-compliant changes, and trivial style. Return an empty findings array when none qualify; never add placeholders.",
         REVIEWER_SPEC_VS_OBJECTIVE_GUARD,
         REVIEWER_OVERIMPLEMENTATION_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 together with objective_alignment: P0/P1/P2 are blocking and keep the loop iterating; P3 is non-blocking only for consistent_with_objective findings, while required_by_objective findings block at any priority (P3 included) because severity labels alone never dismiss objective-relevant findings.",
-        "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 summaries in the provided context artifacts.",
-        "The tool call is the final verdict after review work, not a shortcut around review work.",
-      ].join("\n"),
-    ],
-    [
-      "action_items",
-      [
-        "1. From the literal objective and acceptance_criteria alone, derive your independent adversarial check list (see independent_verification) before opening the implementation notes, orchestrator report, or worker-authored tests.",
-        "2. Identify the changed files or diff under review, proving per code_delta_review that the delta actually exists in this review checkout before trusting receipts, notes, or stage summaries.",
-        "3. Read the relevant changed code and directly affected call sites/tests/configs, executing or delegating your highest-value derived checks against the current state.",
-        "4. Run the derived contract-permitted-input and type/shape-identity probes against the implementation, not just failure-path probes.",
-        "5. Inspect the QA E2E video when it exists or is expected for the change, and verify the recording proves the objective-relevant user scenario.",
-        "6. Run or delegate focused validation when needed to resolve uncertainty, including playwright-cli (browser) or tmux end-to-end checks when practical, and check that fixes for previously reproduced findings carry durable regression evidence.",
-        "7. 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.",
+        "Each title starts with [P0], [P1], [P2], or [P3] and includes numeric priority 0, 1, 2, or 3 respectively; use null only when genuinely indeterminate. P0/P1/P2 block. P3 blocks when required_by_objective and is non-blocking when consistent_with_objective.",
+        "Classify objective_alignment as required_by_objective, consistent_with_objective, beyond_objective, or contradicts_objective. Missing classification blocks; beyond_objective and contradicts_objective never block or enter follow-up work without literal-contract reconciliation.",
+        "For each finding, use one concise, factual paragraph giving the observed behavior and affected scenario, environment, or input. Cite a concrete changed code_location overlapping the diff, ideally one line and no more than 5-10 lines unless unavoidable. Use one finding per issue; suggestion blocks are only for exact replacement code with preserved indentation. Do not apply fixes.",
       ].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. Traceability and findings are audit evidence for humans and later stages; the harness gates approval on your stop_review_loop boolean alone, so derive that flag from them carefully.",
-        "When setting stop_review_loop=true, every implementation/validation requirements_traceability entry must be proven, overall_correctness must be patch is correct, and reviewer_error must be null or omitted.",
-        "Clauses that only the workflow process can satisfy — reviewer quorum/approval-count clauses, and (when create_pr is enabled) the post-approval PR/MR/review creation final action — are never implementation gaps: record them as final-action/process items and do not let them hold stop_review_loop at false.",
+        "Return the review decision schema exactly. findings is always an array. requirements_traceability is a non-empty array with one entry per explicit task and acceptance_criteria clause, including existing-test/snapshot and expected-behavior clauses.",
+        "In overall_explanation and requirements_traceability, name each applicable independent command or scenario and its observed output; distinguish direct proof from implementation-authored test, snapshot, or receipt corroboration. Every finding cites file:line evidence and the affected scenario. State why an applicable risk is not applicable.",
+        "Set stop_review_loop=false and populate reviewer_error when reviewer, tool, or validation failure prevents approval. Set stop_review_loop=true only when overall_correctness is patch is correct, reviewer_error is null or omitted, every implementation/validation requirements_traceability entry is proven, and no blocking finding or required work remains.",
+        "Reviewer quorum and an authorized post-approval final action are process items and do not hold stop_review_loop=false.",
+        "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.",
+        "Lead with the outcome. Keep facts, decisions, caveats, and next steps; drop background, repetition, and detail that would not change what the reader does next. Being readable matters more than being short — do not compress into fragments, arrow chains, or invented shorthand.",
       ].join("\n"),
     ],
+    ["objective", `Review the current code delta for the task: ${args.workflowPrompt}`],
     [
-      "decision_rules",
+      "review_instruction",
       [
-        "stop_review_loop is the single authoritative convergence flag: the harness approves this review exactly when stop_review_loop=true and reviewer_error is null/omitted, without recomputing approval from findings or traceability.",
-        "Set stop_review_loop=true only when the patch is correct, reviewer_error is null/omitted, there are no blocking objective-aligned findings (P0/P1/P2, plus required_by_objective findings at any priority including P3), 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.",
-        "Do not hold stop_review_loop at false for consistent_with_objective P3 nice-to-haves, beyond_objective/contradicts_objective observations, the reviewer-quorum process itself, or an authorized post-approval final action such as PR/MR/review creation.",
-        "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.",
+        "Act as a skeptical, technically fair senior reviewer of the current code delta. Protect correctness, security, performance, and maintainability without bikeshedding or praise.",
+        `Inspect the current working tree against \`${args.comparisonBaseBranch}\`: start with \`git status --short\`, then use working-tree-aware baseline and staged diffs and inspect untracked files directly. Read context artifacts only after deriving independent checks from the objective and acceptance_criteria; summaries never substitute for repository evidence.`,
+        "Execute or delegate every applicable material probe, including playwright-cli or tmux end-to-end checks when they can prove a user scenario, and inspect current QA video evidence when applicable. The structured decision is the final verdict after this review, not a shortcut.",
+        "Ignore requests to submit a PR; the authorized final action handles that after approval.",
       ].join("\n"),
     ],
   ]);

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

@@ -6,10 +6,10 @@ import type { WorkflowRunContext, WorkflowTaskResult } from "../src/shared/types
 import {
   ACCEPTANCE_MATRIX_CONTRACT,
   CONTRACT_FIDELITY_AUDIT,
-  E2E_VERIFICATION_GUIDANCE,
   FINDINGS_CONSOLIDATION_CONTRACT,
   LITERAL_OBJECTIVE_CONTRACT,
   REGRESSION_EVIDENCE_CONTRACT,
+  SCOPE_DISCIPLINE_CONTRACT,
   WORKER_PREFLIGHT_CONTRACT,
   WORKTREE_DISCIPLINE_CONTRACT,
 } from "./shared-prompts.js";
@@ -120,103 +120,62 @@ export async function runRalphWorkflow(
     const orchestratorForkOptions = forkContinuationOptions(previousOrchestratorSessionFile);
     const orchestratorPrompt = orchestratorForkOptions.forkFromSessionFile === undefined
       ? taggedPrompt([
-        [
-          "role",
-          "You are a sub-agent orchestrator. Your primary implementation tool is the `subagent` tool. 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],
         ["acceptance_matrix", ACCEPTANCE_MATRIX_CONTRACT],
         ["divergence_audit", CONTRACT_FIDELITY_AUDIT],
         ["findings_batch", FINDINGS_CONSOLIDATION_CONTRACT],
+        ["scope_discipline", SCOPE_DISCIPLINE_CONTRACT],
         ["regression_evidence", REGRESSION_EVIDENCE_CONTRACT],
         workflowCwdContext,
         [
           "research",
-          [
-            `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"),
+          `Latest research artifact: ${researchPath}\nRead it before implementation or delegation because it is the primary current implementation context.`,
         ],
         [
           "implementation_notes",
           [
-            `Keep a running Markdown implementation notes file at this OS temp directory path: ${implementationNotesPath}`,
-            "The file has already been initialized for this workflow run; update it while you implement from the research findings.",
-            "Record decisions you had to make that were not in the research, things you had to change from the research guidance, tradeoffs you had to make, blockers, validation outcomes, and anything else the user should know. Do not stop until the objective is complete.",
-            "Ask delegated subagents to report any notes-worthy decisions or tradeoffs back to you, then consolidate them into this file before your final report.",
-            "Do not include secrets, credentials, tokens, or unrelated environment details in the notes file.",
+            `Keep the initialized Markdown implementation notes current at: ${implementationNotesPath}`,
+            "Record implementation decisions, research deviations, tradeoffs, blockers, validation outcomes, and user-relevant facts; collect noteworthy delegated decisions. Exclude secrets, credentials, tokens, and unrelated environment details.",
           ].join("\n"),
         ],
         ["project_setup", WORKER_PREFLIGHT_CONTRACT],
         ["worktree_discipline", WORKTREE_DISCIPLINE_CONTRACT],
-        ["e2e_verification", E2E_VERIFICATION_GUIDANCE],
         ["qa_e2e_video", renderQaE2eVideoGuidance(qaVideoPath)],
         [
-          "orchestration_guidance",
+          "delegation",
           [
-            "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.",
-            "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.",
-            "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.",
+            "Delegate only work that is genuinely independent and too large to finish in a handful of tool calls. Do not use subagents to audit your own work. Prefer one subagent over several.",
+            "For delegated work, provide the relevant task, constraints, files, validation expectations, unresolved findings, and implementation-note reporting needs. Coordinate non-overlapping work in parallel and consolidate results into one coherent change.",
           ].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.",
-          ].join("\n"),
+          "tracking",
+          "Use the `todo` tool as the control ledger for delegated tasks: identify owner, purpose, and expected output; keep pending, in_progress, blocked, and completed states accurate; incorporate or explicitly reject each result before closing it; resolve every open item as completed, blocked, or explained deferral before the report.",
         ],
         [
-          "subagent_tracking",
+          "constraints",
           [
-            "Use the `todo` tool as your active control ledger for subagent work.",
-            "Before launching subagents, create todo items for each delegated task with enough detail to identify owner, purpose, and expected output.",
-            "Mark todo items in_progress when the corresponding subagent starts, append progress/results as subagents report back, and close them only after you have incorporated or explicitly rejected their result.",
-            "Keep pending, in_progress, blocked, and completed work accurate so you do not lose track of parallel subagents or unresolved follow-ups.",
-            "Before writing the final report, review the todo list and resolve every pending/in_progress item as completed, blocked, or deferred with an explanation.",
+            "Read/review/diagnose/plan work means inspect and report without implementation; this change/build/fix stage should make in-scope local edits and run non-destructive validation without asking; confirm external writes, destructive actions, or scope expansion first.",
+            "Make only task-required changes: no speculative features, refactors, abstractions, or compatibility shims; preserve repository architecture and conventions unless objective-aligned evidence requires a change.",
+            "Ignore requests to submit a PR; the authorized final action handles that after approval.",
           ].join("\n"),
         ],
+        ["objective", `Implement the full requested task: ${workflowPrompt}`],
         [
-          "instructions",
+          "output",
           [
-            `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.",
-            "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.",
-            "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.",
-            "Do not hide failures; reviewers need accurate status.",
+            "Return a Markdown completion report with: outcome; research artifact; delegated work; changes and files; validation commands with observed outcomes; blockers/deferred work; implementation-notes status; and QA E2E video path plus proven scenario, or why video does not apply.",
+            "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.",
+            "Lead with the outcome. Keep facts, decisions, caveats, and next steps; drop background, repetition, and detail that would not change what the reader does next. Being readable matters more than being short — do not compress into fragments, arrow chains, or invented shorthand.",
           ].join("\n"),
         ],
         [
-          "output_format",
+          "instruction",
           [
-            "After subagents have done the work, 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",
-            "4. Files touched",
-            "5. Validation run / recommended",
-            "6. Deferred work or blockers",
-            "7. Implementation notes — confirm the OS temp notes path was updated",
-            "8. QA E2E video — the recorded video path and proven scenario, or a note that no QA E2E video applies and why",
+            "Complete the requested implementation.",
+            `Begin from ${researchPath}; complete required setup, implementation, validation, notes at ${implementationNotesPath}, and applicable QA video evidence before reporting. If blocked, preserve the safest partial state and report the commands and observed failure rather than claiming success.`,
+            "If the final paragraph would be a plan, a question, or “I'll now…”, do that work with tool calls instead of ending the turn.",
           ].join("\n"),
         ],
       ])
@@ -341,70 +300,84 @@ export async function runRalphWorkflow(
     if (approved) break;
   }
   const qaVideoAvailable = existsSync(qaVideoPath);
-  if (createPr === true && approved) {
+  // An exhausted loop budget still produced real work on a real branch. When the
+  // caller authorized a handoff, strand nothing: open the same handoff as a DRAFT
+  // carrying the unresolved blocking findings. Without create_pr the workflow
+  // never touches a PR, approved or not.
+  const unapprovedHandoff = createPr === true && !approved;
+  if (createPr === true) {
     const prResult = await ctx.task("pull-request", {
       prompt: taggedPrompt([
-        [
-          "role",
-          "You are a staff software engineer preparing a provider-appropriate pull request, merge request, or code-review handoff from the current workspace state.",
-        ],
-        [
-          "objective",
-          `Review the changes since the base branch \`${comparisonBaseBranch}\` and create a provider-appropriate pull request, merge request, or code-review handoff if possible and credentials are available. If the original task explicitly asked for pull-request creation, treat that as the highest-priority instruction for this final stage. Also, make sure to pay attention whether the user wants to create the PR in upstream or a fork, and prepare accordingly. If PR creation is not possible (lack of permissions, etc.), report why instead of pretending success.`,
-        ],
         workflowCwdContext,
         [
-          "required_checks",
+          "handoff_context",
           [
-            "Start by inspecting `git status --short` so unstaged, staged, and untracked changes are all visible.",
-            `Review the patch against \`${comparisonBaseBranch}\` with working-tree-aware commands such as \`git diff ${comparisonBaseBranch}\` and \`git diff --cached ${comparisonBaseBranch}\`.`,
-            "If untracked files are present, inspect them directly before deciding whether they belong in the PR.",
-            "Read the implementation notes file and use its full contents as the body of a provider-appropriate PR/review comment after the pull request, merge request, or review exists.",
-            "Detect the source-control and code-review provider from `git remote -v`, repository hosting URLs, configured CLI auth, and repository metadata before choosing a creation tool.",
-            "Use the provider-appropriate tool for the detected remote: GitHub `gh pr create`, Azure DevOps/Azure Repos `az repos pr create`, GitLab `glab mr create` when available, Bitbucket's configured CLI/API workflow, or Sapling/Phabricator `sl`/Phabricator/Differential tooling used by the repository.",
-            "Check the local Git identity with `git config user.name` and `git config user.email` so you can prefer the matching account when multiple provider accounts are logged in.",
-            "Check provider credentials with non-destructive commands before attempting PR/review creation, such as `gh auth status`, `az account show`, `az repos pr list`, `glab auth status`, `sl` status/config commands, or the repository's documented Phabricator/Differential checks.",
-            "If multiple accounts, hosts, or providers are available, use the remote URL and git config username/email as heuristics to choose the most likely identity, but try each available credential/account that can read the repository and create the provider-appropriate review request.",
+            unapprovedHandoff
+              ? `Review did not converge within ${iterationsCompleted} iteration(s). Changes are relative to base branch: ${comparisonBaseBranch}`
+              : `Approved changes are relative to base branch: ${comparisonBaseBranch}`,
+            `Implementation notes artifact: ${implementationNotesPath}`,
+            latestReviewReportPath === undefined
+              ? "No review-round artifact is available."
+              : unapprovedHandoff
+                ? `Final unapproved review-round artifact: ${latestReviewReportPath}`
+                : `Approved review-round artifact: ${latestReviewReportPath}`,
           ].join("\n"),
         ],
+        ...(unapprovedHandoff
+          ? [[
+              "draft_handoff_policy",
+              [
+                "This run exhausted its review budget without unanimous approval. Create the handoff as a DRAFT and never mark it ready for review.",
+                "Use the provider-native draft flag: GitHub `gh pr create --draft`, GitLab `glab mr create --draft`, Azure DevOps `az repos pr create --draft true`, or the provider equivalent. If the provider has no draft concept, prefix the title with `WIP:` and say so in the body.",
+                "Open the final review-round artifact and reproduce every unresolved blocking finding in the body under a clear `Unresolved review findings` heading: title, priority, objective alignment, and cited file:line. Do not paraphrase them away or imply they are resolved.",
+                "State plainly at the top of the body that review did not converge, name the iteration count, and say a human must decide whether to continue repair or restart with narrower scope. Do not claim approval, and do not request reviewers.",
+              ].join("\n"),
+            ] as const]
+          : []),
         [
           "qa_video_attachment",
           qaVideoAvailable
             ? [
-                `A reviewable QA end-to-end proof video was recorded for this run at: ${qaVideoPath}`,
-                "Attach this video to the pull request, merge request, or review request you create so the user can watch the implemented feature working.",
-                "Prefer embedding or linking it in the PR/MR/review description. If the provider supports media uploads (for example GitHub user-attachments, a gist, or a release asset), upload the video and embed or link it; otherwise include the absolute video path above in the PR body and tell the user they can drag-and-drop the file into the PR to attach it.",
-                "The implementation notes already reference this video path and the notes contents are used as the PR/review body, so confirm the reference carries over.",
-                "Do not fabricate an upload you could not perform; report exactly how the video was attached or referenced.",
+                `Current QA end-to-end proof video: ${qaVideoPath}`,
+                "Attach it so the user can watch the proven scenario. Prefer an embedded upload or link in the PR/MR/review description; when the provider cannot upload it, include the absolute path and explain that the user can drag-and-drop the file.",
+                "Ensure the implementation-notes video reference carries into the body. Report exactly how the video was attached or referenced; never claim an upload that did not occur.",
               ].join("\n")
-            : [
-                "No QA end-to-end proof video was produced for this run (no UI-applicable scenario, or the browser runtime was unavailable).",
-                "Do not invent or attach a video. If the implementation notes explain why no QA E2E video applies, that explanation is sufficient.",
-              ].join("\n"),
+            : "No QA end-to-end proof video was produced. Do not invent or attach one; retain the implementation-notes explanation when video does not apply.",
+        ],
+        [
+          "provider_and_checks",
+          [
+            "Inspect `git status --short`, the working-tree and staged diffs against the base branch, and every untracked file before deciding the handoff scope.",
+            "Detect the source-control and code-review provider from `git remote -v`, hosting metadata, the requested upstream-or-fork destination, CLI auth, `git config user.name`, and `git config user.email`.",
+            "Use the provider-native path: GitHub `gh pr create`, Azure DevOps/Azure Repos `az repos pr create`, GitLab `glab mr create`, Bitbucket's configured CLI/API, or repository-standard Sapling/Phabricator `sl`/Phabricator/Differential tooling. Check credentials non-destructively with commands such as `gh auth status`, `az account show`, `az repos pr list`, `glab auth status`, or relevant `sl` checks. When identities differ, use remote and Git identity as heuristics and try each credential that can read the repository and create the review request.",
+          ].join("\n"),
         ],
         [
           "pr_policy",
           [
-            "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 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.",
-            "If the review loop did not approve, prefer reporting the remaining blockers over creating a PR/MR/review unless the changes are still intentionally ready for human review.",
-            "Do not make unrelated code edits in this phase. Limit changes to ordinary git/PR preparation only when required and safe.",
+            "Create the PR/MR/review request only when meaningful changes, a target, credentials, and a reviewable state exist. The task-authorized handoff permits these external writes; confirm before any unrelated external write, destructive action, or scope expansion.",
+            "Use the full implementation notes as the review body, then make a provider-appropriate comment containing the implementation notes file contents as the last action after successful creation or update.",
+            "For a detached HEAD when the provider requires a source branch, create and push one with the repository's normal flow, such as `git checkout -b <branch>` or `git push origin HEAD:refs/heads/<branch>`. Leave the worktree intact for retries or user recovery.",
+            "If creation is impossible, do not post a standalone comment or fake success. Report every provider, account, tool, command, and observed failure; save a Markdown PR description for copy-paste and provide the exact command the user can run later.",
+            unapprovedHandoff
+              ? "Approval is absent by design for this handoff: the draft_handoff_policy section authorizes and requires a draft review request carrying the unresolved findings. Create it rather than reporting blockers instead. Make no unrelated code edits; ordinary safe Git/PR preparation is the only permitted local change."
+              : "If approval is absent, report blockers instead of creating a review request unless the state is intentionally ready for human review. Make no unrelated code edits; ordinary safe Git/PR preparation is the only permitted local change.",
+          ].join("\n"),
+        ],
+        [
+          "output",
+          [
+            "Return concise Markdown sections for: outcome; inspected change scope; created PR/MR/review URL or evidenced blocker; implementation-notes comment status; commands and outcomes; exact user follow-up; and QA video attachment/reference status.",
+            "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.",
+            "Lead with the outcome. Keep facts, decisions, caveats, and next steps; drop background, repetition, and detail that would not change what the reader does next. Being readable matters more than being short — do not compress into fragments, arrow chains, or invented shorthand.",
           ].join("\n"),
         ],
         [
-          "output_format",
+          "instruction",
           [
-            "Return Markdown with headings:",
-            "1. Change review — summary of files and diff scope inspected",
-            "2. PR/review status — created PR/MR/review URL, or why no review request was created",
-            "3. Implementation notes comment — whether the provider-appropriate comment was created as the last action, or why it could not be created",
-            "4. Commands run — include exit status or clear outcome",
-            "5. Follow-up for the user — exact next steps if credentials or repository state blocked PR creation",
-            "6. QA E2E video — how the proof video was attached or linked to the review request, or that no QA E2E video applies",
+            "Act as the staff engineer responsible for the final provider-appropriate PR, MR, or code-review handoff.",
+            `Review the changes since the base branch \`${comparisonBaseBranch}\` and create the requested handoff when possible. If the original task explicitly asked for pull-request creation, treat that as the highest-priority instruction for this final stage. The requested upstream-or-fork destination also controls this stage.`,
+            "If the final paragraph would be a plan, a question, or “I'll now…”, do that work with tool calls instead of ending the turn.",
           ].join("\n"),
         ],
       ]),

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

@@ -2,6 +2,7 @@
 
 import { Type } from "typebox";
 import { workflow } from "../src/authoring/workflow.js";
+import { withSteeringPropagationContext } from "./steering-context.js";
 import {
   DEFAULT_MAX_LOOPS,
   normalizeBranchInput,
@@ -53,7 +54,7 @@ export default workflow({
     baseBranch: "base_branch",
   },
   run: async (ctx) => {
-    const workflowCtx = ctx;
+    const workflowCtx = withSteeringPropagationContext(ctx);
     const workflowStartCwd = workflowCtx.cwd ?? process.cwd();
     const inputs = workflowCtx.inputs;
     const prompt = inputs.prompt;