@bastani/atomic 0.9.5-alpha.1 → 0.9.5-alpha.10

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

@@ -1,135 +1,167 @@
 import { reviewDecisionSchema } from "./ralph-core.js";
 
-// Model chains are curated from Atomic's agentic-coding benchmark
-// (pass@1 / avg $ per task, 2026-07-02):
-// - Placement principle: REVIEWERS get best-in-class verification quality
-//   (fable-5:xhigh 70%/$13.41 leads reviewer-A and the goal reviewer);
-//   EVERY OTHER stage gets the best measured performance-per-dollar
-//   (gpt-5.5:xhigh 67%/$7.23 for hard stages, gpt-5.5:medium 54%/$2.75 for
-//   workhorse stages, gpt-5.5:low $1.20 for retrieval).
-// - Pareto frontier: gpt-5.5 low ($1.20/27%) → gpt-5.5 medium ($2.75/54%) →
-//   fable-5 low ($3.76/60%) → gpt-5.5 high ($5.10/64%) → fable-5 medium
-//   ($6.09/65%) → gpt-5.5 xhigh ($7.23/67%) → fable-5 high ($9.18/69%) →
-//   fable-5 xhigh ($13.41/70%).
-// - Dropped as strictly dominated: claude-sonnet-5 (40-54% at $4-26, up to
-//   268 steps), claude-sonnet-4.6 (30%/$5.52), gemini-3.1-pro (12%/$9.48),
-//   gemini-3.5-flash (37%/$7.34, 276k output tokens).
-// - claude-opus-4.8 rides at :high — its value point (52%/$4.28); :xhigh
-//   doubles the cost for +2pts.
-// - glm-5.2 is reviewer-C's diversity primary only (third model family
-//   decorrelates review errors); elsewhere it is a budget fallback. Note:
-//   GLM-5.2 has only two real reasoning tiers — its thinkingLevelMap collapses
+// Model chains are curated from Atomic's agentic-coding benchmark and the
+// July 2026 frontier refresh:
+// - Critical synthesis/review stages prefer fable-5:xhigh, then gpt-5.5 xhigh
+//   variants, openrouter fugu-ultra, long-context opus, and GLM fallbacks.
+// - Research remains on gpt-5.5:medium / fable-5:low for perf-per-dollar.
+// - Reviewer B keeps gpt-5.5:xhigh as an independent frontier family to
+//   decorrelate review errors from reviewer A.
+// - Dominated benchmark models stay out of the chains: claude-sonnet-5,
+//   claude-sonnet-4.6, gemini-3.1-pro, and gemini-3.5-flash.
+// - GLM-5.2 has only two real reasoning tiers — its thinkingLevelMap collapses
 //   minimal/low/medium/high to "high" and xhigh to "max" — so chains only use
 //   :high (budget tier, 36%/$2.84) or :xhigh (best tier, 44%/$3.92); the
 //   openrouter/z-ai mirror maps :xhigh exclusively, so it is always :xhigh.
 
 export const promptEngineerModelConfig = {
-    model: "openai-codex/gpt-5.5:xhigh",
+    model: "anthropic/claude-fable-5:high",
     fallbackModels: [
+      "openai-codex/gpt-5.6-sol:xhigh",
+      "github-copilot/gpt-5.6-sol:xhigh",
+      "openai/gpt-5.6-sol:xhigh",
+      "openai-codex/gpt-5.5:xhigh",
       "github-copilot/gpt-5.5:xhigh",
       "openai/gpt-5.5:xhigh",
-      "anthropic/claude-fable-5:xhigh",
       "github-copilot/claude-opus-4.8 (1m):high",
       "anthropic/claude-opus-4-8:high",
+      "cursor/claude-fable-5:high",
+      "cursor/gpt-5.6-sol:xhigh",
+      "cursor/gpt-5.5:high",
+      "cursor/claude-opus-4-8-thinking:high",
+      "cursor/grok-4.5",
       "zai/glm-5.2:xhigh",
       "zai-coding-cn/glm-5.2:xhigh",
+      "cursor/glm-5.2",
+      "openrouter/anthropic/claude-fable-5:high",
+      "openrouter/openai/gpt-5.6-sol:xhigh",
+      "openrouter/sakana/fugu-ultra:high",
       "openrouter/openai/gpt-5.5:xhigh",
-      "openrouter/anthropic/claude-fable-5:xhigh",
       "openrouter/anthropic/claude-opus-4-8:high",
+      "openrouter/x-ai/grok-4.5",
       "openrouter/z-ai/glm-5.2:xhigh"
     ],
     excludedTools: ["ask_user_question"],
 };
 
 export const researchModelConfig = {
-    model: "openai-codex/gpt-5.5:medium",
+    model: "openai-codex/gpt-5.6-sol:medium",
     fallbackModels: [
-        "github-copilot/gpt-5.5:medium",
-        "openai/gpt-5.5:medium",
-        "anthropic/claude-fable-5:low",
-        "github-copilot/claude-opus-4.8 (1m):medium",
-        "anthropic/claude-opus-4-8:medium",
-        "zai/glm-5.2:high",
-        "zai-coding-cn/glm-5.2:high",
-        "openrouter/openai/gpt-5.5:medium",
-        "openrouter/anthropic/claude-fable-5:low",
-        "openrouter/anthropic/claude-opus-4-8:medium",
-        "openrouter/z-ai/glm-5.2:xhigh"
+      "github-copilot/gpt-5.6-sol:medium",
+      "openai/gpt-5.6-sol:medium",
+      "openai-codex/gpt-5.5:medium",
+      "github-copilot/gpt-5.5:medium",
+      "openai/gpt-5.5:medium",
+      "anthropic/claude-fable-5:low",
+      "github-copilot/claude-opus-4.8 (1m):medium",
+      "anthropic/claude-opus-4-8:medium",
+      "cursor/gpt-5.6-sol:medium",
+      "cursor/gpt-5.5:medium",
+      "cursor/claude-fable-5:low",
+      "cursor/claude-opus-4-8-thinking:medium",
+      "cursor/grok-4.5",
+      "zai/glm-5.2:high",
+      "zai-coding-cn/glm-5.2:high",
+      "cursor/glm-5.2",
+      "openrouter/openai/gpt-5.6-sol:medium",
+      "openrouter/openai/gpt-5.5:medium",
+      "openrouter/anthropic/claude-fable-5:low",
+      "openrouter/anthropic/claude-opus-4-8:medium",
+      "openrouter/x-ai/grok-4.5",
+      "openrouter/z-ai/glm-5.2:high"
     ],
     excludedTools: ["ask_user_question"],
 };
 
 export const orchestratorModelConfig = {
-    model: "openai-codex/gpt-5.5:medium",
-    fallbackModels: [
-        "github-copilot/gpt-5.5:medium",
-        "openai/gpt-5.5:medium",
-        "anthropic/claude-fable-5:low",
-        "github-copilot/claude-opus-4.8 (1m):medium",
-        "anthropic/claude-opus-4-8:medium",
-        "zai/glm-5.2:high",
-        "zai-coding-cn/glm-5.2:high",
-        "openrouter/openai/gpt-5.5:medium",
-        "openrouter/anthropic/claude-fable-5:low",
-        "openrouter/anthropic/claude-opus-4-8:medium",
-        "openrouter/z-ai/glm-5.2:xhigh"
-    ],
-    excludedTools: ["ask_user_question"],
-};
-
-export const reviewerAModelConfig = {
-    model: "anthropic/claude-fable-5:xhigh",
+    model: "openai-codex/gpt-5.6-sol:xhigh",
     fallbackModels: [
+      "github-copilot/gpt-5.6-sol:xhigh",
+      "openai/gpt-5.6-sol:xhigh",
+      "anthropic/claude-fable-5:high",
       "openai-codex/gpt-5.5:xhigh",
       "github-copilot/gpt-5.5:xhigh",
       "openai/gpt-5.5:xhigh",
       "github-copilot/claude-opus-4.8 (1m):high",
       "anthropic/claude-opus-4-8:high",
+      "cursor/gpt-5.6-sol:xhigh",
+      "cursor/claude-fable-5:high",
+      "cursor/gpt-5.5:high",
+      "cursor/claude-opus-4-8-thinking:high",
+      "cursor/grok-4.5",
       "zai/glm-5.2:xhigh",
       "zai-coding-cn/glm-5.2:xhigh",
-      "openrouter/anthropic/claude-fable-5:xhigh",
+      "cursor/glm-5.2",
+      "openrouter/openai/gpt-5.6-sol:xhigh",
+      "openrouter/anthropic/claude-fable-5:high",
+      "openrouter/sakana/fugu-ultra:high",
       "openrouter/openai/gpt-5.5:xhigh",
       "openrouter/anthropic/claude-opus-4-8:high",
+      "openrouter/x-ai/grok-4.5",
       "openrouter/z-ai/glm-5.2:xhigh"
     ],
     excludedTools: ["ask_user_question"],
-    schema: reviewDecisionSchema,
 };
 
-export const reviewerBModelConfig = {
-    model: "openai-codex/gpt-5.5:xhigh",
+export const reviewerAModelConfig = {
+    model: "anthropic/claude-fable-5:high",
     fallbackModels: [
+      "openai-codex/gpt-5.6-sol:max",
+      "github-copilot/gpt-5.6-sol:max",
+      "openai/gpt-5.6-sol:max",
+      "openai-codex/gpt-5.5:xhigh",
       "github-copilot/gpt-5.5:xhigh",
       "openai/gpt-5.5:xhigh",
-      "anthropic/claude-fable-5:xhigh",
       "github-copilot/claude-opus-4.8 (1m):high",
       "anthropic/claude-opus-4-8:high",
+      "cursor/claude-fable-5:high",
+      "cursor/gpt-5.6-sol:max",
+      "cursor/gpt-5.5:high",
+      "cursor/claude-opus-4-8-thinking:high",
+      "cursor/grok-4.5",
       "zai/glm-5.2:xhigh",
       "zai-coding-cn/glm-5.2:xhigh",
+      "cursor/glm-5.2",
+      "openrouter/anthropic/claude-fable-5:high",
+      "openrouter/openai/gpt-5.6-sol:max",
+      "openrouter/sakana/fugu-ultra:high",
       "openrouter/openai/gpt-5.5:xhigh",
-      "openrouter/anthropic/claude-fable-5:xhigh",
       "openrouter/anthropic/claude-opus-4-8:high",
+      "openrouter/x-ai/grok-4.5",
       "openrouter/z-ai/glm-5.2:xhigh"
     ],
     excludedTools: ["ask_user_question"],
     schema: reviewDecisionSchema,
 };
 
-export const reviewerCModelConfig = {
-    model: "zai/glm-5.2:xhigh",
+export const reviewerBModelConfig = {
+    model: "openai-codex/gpt-5.6-sol:max",
     fallbackModels: [
-      "zai-coding-cn/glm-5.2:xhigh",
-      "openrouter/z-ai/glm-5.2:xhigh",
+      "github-copilot/gpt-5.6-sol:max",
+      "openai/gpt-5.6-sol:max",
       "openai-codex/gpt-5.5:xhigh",
       "github-copilot/gpt-5.5:xhigh",
       "openai/gpt-5.5:xhigh",
-      "anthropic/claude-fable-5:xhigh",
+      "anthropic/claude-fable-5:high",
       "github-copilot/claude-opus-4.8 (1m):high",
       "anthropic/claude-opus-4-8:high",
+      "cursor/gpt-5.6-sol:max",
+      "cursor/gpt-5.5:high",
+      "cursor/claude-fable-5:high",
+      "cursor/claude-opus-4-8-thinking:high",
+      "cursor/grok-4.5",
+      "zai/glm-5.2:xhigh",
+      "zai-coding-cn/glm-5.2:xhigh",
+      "cursor/glm-5.2",
+      "openrouter/openai/gpt-5.6-sol:max",
       "openrouter/openai/gpt-5.5:xhigh",
-      "openrouter/anthropic/claude-fable-5:xhigh",
-      "openrouter/anthropic/claude-opus-4-8:high"
+      "openrouter/anthropic/claude-fable-5:high",
+      "openrouter/sakana/fugu-ultra:high",
+      "openrouter/anthropic/claude-opus-4-8:high",
+      "openrouter/x-ai/grok-4.5",
+      "openrouter/z-ai/glm-5.2:xhigh"
     ],
     excludedTools: ["ask_user_question"],
     schema: reviewDecisionSchema,
 };
+

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

@@ -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"),
+    ],
+  ]);
+}