@bastani/atomic 0.9.5-alpha.3 → 0.9.5-alpha.5

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [0.9.5-alpha.5] - 2026-07-06
+
+### Added
+
+- Added an internal tiered fallback ladder for automatic Verbatim Compaction when the strict `compression_ratio` target is not achievable: threshold and overflow auto-compaction now keep the standard strict planner pass as tier 1, tier 2 can accept a validated below-target result with at least one deletion when projected `tokensAfter` clears the relevant budget (`effectiveInputBudget - reserveTokens` for threshold, effective input budget for overflow), overflow commits from Atomic's internal ladder are gated on fitting the effective input budget even when the strict target is met, overflow-only tier 3 reruns the planner with critical LRU-style protected-entry eligibility for stale task-bearing user/custom/branch-summary context and an effective recent floor of `max(preserve_recent, 5)` across all compactable entries, and overflow-only tier 4 performs deterministic code-level LRU eviction without a model call or API credentials while enforcing the same effective last-5 recent floor until the effective input budget fits or no more safe deletion remains. The fallback tiers remain internal: extension hooks keep their existing shapes, extension-provided deletion requests still bypass the ladder including the overflow budget gate, and no public compaction mode API is exposed.
+- Added hard iteration caps to compaction recovery loops: planner provider turns are capped at 50 per planner run (including tool-call turns), planner nudge follow-ups are capped at 50 per planner run, and deterministic overflow eviction is capped at 50 passes, so compaction cannot spin indefinitely and terminal failures report the achieved reduction, deletion count, projected `tokensAfter`, and budget.
+
+### Fixed
+
+- Fixed overflow auto-compaction silently no-oping when planner authentication was unavailable or when the current branch has no preparable compactable transcript: overflow recovery now either skips model tiers and runs deterministic no-auth LRU eviction directly through the existing validation pipeline, or surfaces a terminal error that nothing more was safely deletable.
+- Fixed feasible partial compaction results being discarded solely because they missed the strict ratio target: automatic threshold and overflow compaction now commit validated below-target deletions when their projected `tokensAfter` clears the trigger/budget boundary, including partial deletion state salvaged after a provider context-overflow error.
+
+## [0.9.5-alpha.4] - 2026-07-05
+
+### Changed
+
+- Simplified first-run onboarding to a one-time verifiable-coding-agent-runtime explanation shown after any What's New notes and directly above the normal input box; Atomic no longer intercepts pasted tasks, saves pre-login seeds, routes first-run input to `goal`/`ralph`, raises reasoning for onboarding, or requires `/chat` to continue normally. The notice now reminds unauthenticated users to run `/login` first, and starting a new session with `/new` clears any rendered first-run notice state from the previous session canvas.
+
 ## [0.9.5-alpha.3] - 2026-07-04
 
 ### Changed

package/dist/builtin/cursor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/cursor",
-  "version": "0.9.5-alpha.3",
+  "version": "0.9.5-alpha.5",
   "private": true,
   "description": "Experimental first-party Atomic extension for Cursor OAuth, model discovery, and streaming provider registration.",
   "contributors": [
@@ -40,7 +40,7 @@
     }
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.9.5-alpha.3",
+    "@bastani/atomic-natives": "0.9.5-alpha.5",
     "@bufbuild/protobuf": "^2.12.1",
     "@earendil-works/pi-ai": "^0.80.3"
   }

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.9.5-alpha.3",
+  "version": "0.9.5-alpha.5",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.9.5-alpha.3",
+  "version": "0.9.5-alpha.5",
   "private": true,
   "description": "Atomic extension that adapts MCP (Model Context Protocol) servers into the coding agent. Fork of: https://github.com/nicobailon/pi-mcp-adapter",
   "contributors": [

package/dist/builtin/subagents/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [0.9.5-alpha.5] - 2026-07-06
+
+### Changed
+
+- Changed the Claude Fable 5 reasoning level from `xhigh` to `high` in the builtin `debugger` agent, covering the `anthropic/claude-fable-5` primary and its OpenRouter mirror in the fallback chain.
+- Changed the Claude Opus 4.8 reasoning level from `xhigh` to `high` in the builtin `debugger` agent's fallback chain (`github-copilot/claude-opus-4.8 (1m)`, `anthropic/claude-opus-4-8`, and the OpenRouter mirror); Opus 4.8 entries at other levels in other agents are unchanged.
+
 ## [0.9.5-alpha.2] - 2026-07-04
 
 ### Changed

package/dist/builtin/subagents/agents/debugger.md

@@ -2,8 +2,8 @@
 name: debugger
 description: Debug errors, test failures, and unexpected behavior. Use PROACTIVELY when encountering issues, analyzing stack traces, or investigating system problems.
 tools: read, search, find, ls, bash, web_search, fetch_content, get_search_content, intercom, contact_supervisor, todo
-model: anthropic/claude-fable-5:xhigh
-fallbackModels: openai-codex/gpt-5.5:xhigh, github-copilot/gpt-5.5:xhigh, openai/gpt-5.5:xhigh, github-copilot/claude-opus-4.8 (1m):xhigh, anthropic/claude-opus-4-8:xhigh, zai/glm-5.2:xhigh, zai-coding-cn/glm-5.2:xhigh, openrouter/anthropic/claude-fable-5:xhigh, openrouter/sakana/fugu-ultra:high, openrouter/openai/gpt-5.5:xhigh, openrouter/anthropic/claude-opus-4-8:xhigh, openrouter/z-ai/glm-5.2:xhigh
+model: anthropic/claude-fable-5:high
+fallbackModels: 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, zai/glm-5.2:xhigh, zai-coding-cn/glm-5.2: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/z-ai/glm-5.2:xhigh
 skills: tdd, playwright-cli, tmux
 ---
 

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.9.5-alpha.3",
+  "version": "0.9.5-alpha.5",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.9.5-alpha.3",
+  "version": "0.9.5-alpha.5",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction. Fork of: https://github.com/nicobailon/pi-web-access",
   "contributors": [

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,6 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.9.5-alpha.5] - 2026-07-06
+
+### Added
+
+- Added `git_worktree_dir` to the builtin `goal` workflow with Ralph-parity input binding so Goal runs can create or reuse a repository worktree from `base_branch` while preserving the invoking repo-relative cwd for worker, reviewer, and optional final PR stages.
+
+### Changed
+
+- Changed the Claude Fable 5 reasoning level from `xhigh` to `high` across all builtin workflow model chains (`ralph` prompt-engineer/orchestrator/reviewer-a/reviewer-b/reviewer-c, `goal` reviewer, `deep-research-codebase` planner, and `open-claude-design`), covering both the native `anthropic/claude-fable-5` entries and their OpenRouter mirrors.
+- Changed the Claude Opus 4.8 reasoning level from `xhigh` to `high` across the same builtin workflow model chains, covering the `github-copilot/claude-opus-4.8 (1m)`, `anthropic/claude-opus-4-8`, and `openrouter/anthropic/claude-opus-4-8` entries; Opus 4.8 entries already at `medium`/`low` value points are unchanged.
+
+## [0.9.5-alpha.4] - 2026-07-05
+
+### Changed
+
+- Hardened the builtin `goal` and `ralph` loops against spec-vs-objective drift on enumerated error behavior (observed in an eval trace where an adversarial reviewer flagged a task-mandated diagnostic as a spec-conformance defect and the fix cycle silently reinterpreted the ambiguous input as valid behavior, losing the required error): the shared literal objective contract now instructs workers and reviewers to prefer loud errors over silent reinterpretation — when the objective/acceptance criteria enumerate required error conditions, messages, or rejections, each enumerated error gets the widest plausible trigger surface, ambiguous or unspecified inputs near an enumerated error case default to raising that error even when external spec knowledge says the input is valid, and narrowing an enumerated error's trigger surface requires explicit contract or pre-existing required-test demand. Both loops' reviewer bug-selection guidelines now forbid using external spec/standard conformance alone to flag a wide trigger surface for a contract-enumerated error as a defect; such spec-vs-objective tension must be classified `beyond_objective` instead of becoming a blocking finding that steers the implementation away from the contract's errors.
+- Extracted the Ralph reviewer prompt into `builtin/ralph-reviewer-prompt.ts` (`renderRalphReviewerPrompt`) and deduplicated the new reviewer guard into a shared `REVIEWER_SPEC_VS_OBJECTIVE_GUARD` constant consumed by both the Goal and Ralph reviewer prompts, keeping `ralph-runner.ts` under the repository's 500-line file gate. No behavioral change beyond the guard itself.
+
 ## [0.9.5-alpha.3] - 2026-07-04
 
 ### Changed

package/dist/builtin/workflows/builtin/deep-research-codebase-utils.ts

@@ -35,19 +35,19 @@ export const FILE_ONLY_OUTPUT = "file-only" satisfies WorkflowOutputMode;
 // for the frontier data). This planner uses the high-capacity synthesis roster
 // because it performs cross-codebase planning before partition fan-out.
 export const PLANNER_MODEL_CONFIG = {
-  model: "anthropic/claude-fable-5:xhigh",
+  model: "anthropic/claude-fable-5:high",
   fallbackModels: [
     "openai-codex/gpt-5.5:xhigh",
     "github-copilot/gpt-5.5:xhigh",
     "openai/gpt-5.5:xhigh",
-    "github-copilot/claude-opus-4.8 (1m):xhigh",
-    "anthropic/claude-opus-4-8:xhigh",
+    "github-copilot/claude-opus-4.8 (1m):high",
+    "anthropic/claude-opus-4-8:high",
     "zai/glm-5.2:xhigh",
     "zai-coding-cn/glm-5.2:xhigh",
-    "openrouter/anthropic/claude-fable-5:xhigh",
+    "openrouter/anthropic/claude-fable-5:high",
     "openrouter/sakana/fugu-ultra:high",
     "openrouter/openai/gpt-5.5:xhigh",
-    "openrouter/anthropic/claude-opus-4-8:xhigh",
+    "openrouter/anthropic/claude-opus-4-8:high",
     "openrouter/z-ai/glm-5.2:xhigh"
   ],
   excludedTools: ["ask_user_question"],

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

@@ -1,6 +1,7 @@
 import {
   E2E_VERIFICATION_GUIDANCE,
   LITERAL_OBJECTIVE_CONTRACT,
+  REVIEWER_SPEC_VS_OBJECTIVE_GUARD,
   WORKER_PREFLIGHT_CONTRACT,
   renderE2eQaVideoReviewGuidance,
 } from "./shared-prompts.js";
@@ -301,6 +302,7 @@ export function renderReviewerPrompt(args: {
         "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 and receipts prove the objective, return an empty findings array, mark the patch correct, set goal_oracle_satisfied true, and set stop_review_loop true.",
       ].join("\n"),

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

@@ -114,19 +114,19 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
     };
 
     const reviewerModelConfig = {
-      model: "anthropic/claude-fable-5:xhigh",
+      model: "anthropic/claude-fable-5:high",
       fallbackModels: [
           "openai-codex/gpt-5.5:xhigh",
           "github-copilot/gpt-5.5:xhigh",
           "openai/gpt-5.5:xhigh",
-          "github-copilot/claude-opus-4.8 (1m):xhigh",
-          "anthropic/claude-opus-4-8:xhigh",
+          "github-copilot/claude-opus-4.8 (1m):high",
+          "anthropic/claude-opus-4-8:high",
           "zai/glm-5.2:xhigh",
           "zai-coding-cn/glm-5.2:xhigh",
-          "openrouter/anthropic/claude-fable-5:xhigh",
+          "openrouter/anthropic/claude-fable-5:high",
           "openrouter/sakana/fugu-ultra:high",
           "openrouter/openai/gpt-5.5:xhigh",
-          "openrouter/anthropic/claude-opus-4-8:xhigh",
+          "openrouter/anthropic/claude-opus-4-8:high",
           "openrouter/z-ai/glm-5.2:xhigh"
       ],
       tools: goalRunnerTools,

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

@@ -130,6 +130,7 @@ export type GoalWorkflowInputs = {
   readonly acceptance_criteria?: string;
   readonly max_turns: number;
   readonly base_branch: string;
+  readonly git_worktree_dir: string;
   readonly create_pr: boolean;
 };
 

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

@@ -14,6 +14,7 @@ export type GoalWorkflowInputs = WorkflowInputValues & {
   readonly acceptance_criteria?: string;
   readonly max_turns: number;
   readonly base_branch: string;
+  readonly git_worktree_dir: string;
   readonly create_pr: boolean;
 };
 
@@ -22,6 +23,7 @@ export type GoalWorkflowRunInputs = WorkflowInputValues & {
   readonly acceptance_criteria?: string;
   readonly max_turns?: number;
   readonly base_branch?: string;
+  readonly git_worktree_dir?: string;
   readonly create_pr?: boolean;
 };
 

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

@@ -25,6 +25,11 @@ export default workflow({
       default: "origin/main",
       description: "Optional branch reviewers compare the current code delta against (default origin/main).",
     }),
+    git_worktree_dir: Type.String({
+      default: "",
+      description:
+        "Optional Git worktree path. Must start inside a Git repo; absolute paths are used as-is, relative paths resolve from the repo root, existing Git worktrees from the invoking repository are reused/shared as-is, and missing paths are created from base_branch.",
+    }),
     create_pr: Type.Boolean({
       default: false,
       description:
@@ -55,6 +60,10 @@ export default workflow({
     review_report_path: Type.Optional(Type.String({ description: "JSON artifact path for the latest reviewer decision round." })),
     pr_report: Type.Optional(Type.String({ description: "Pull-request report emitted only when create_pr=true, Goal reaches complete, and the final pull-request stage runs." })),
   },
+  worktreeFromInputs: {
+    gitWorktreeDir: "git_worktree_dir",
+    baseBranch: "base_branch",
+  },
   run: async (ctx) => {
     const workflowCtx = ctx;
     const workflowStartCwd = workflowCtx.cwd ?? process.cwd();

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

@@ -40,6 +40,7 @@ export type GoalWorkflowInputs = WorkflowInputValues & {
   readonly acceptance_criteria?: string;
   readonly max_turns: number;
   readonly base_branch: string;
+  readonly git_worktree_dir: string;
   readonly create_pr: boolean;
 };
 export type GoalWorkflowRunInputs = WorkflowInputValues & {
@@ -47,6 +48,7 @@ export type GoalWorkflowRunInputs = WorkflowInputValues & {
   readonly acceptance_criteria?: string;
   readonly max_turns?: number;
   readonly base_branch?: string;
+  readonly git_worktree_dir?: string;
   readonly create_pr?: boolean;
 };
 export type GoalWorkflowOutputs = WorkflowOutputValues & {

package/dist/builtin/workflows/builtin/open-claude-design-runner.ts

@@ -78,14 +78,14 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
   // strictly dominated in Atomic's benchmark (see ralph-models.ts). Opus stays
   // at :xhigh here — visual quality, not $/task, is the objective for design.
   const designModelConfig = {
-    model: "anthropic/claude-fable-5:xhigh",
+    model: "anthropic/claude-fable-5:high",
     fallbackModels: [
-      "github-copilot/claude-opus-4.8 (1m):xhigh",
-      "anthropic/claude-opus-4-8:xhigh",
+      "github-copilot/claude-opus-4.8 (1m):high",
+      "anthropic/claude-opus-4-8:high",
       "zai/glm-5.2:xhigh",
       "zai-coding-cn/glm-5.2:xhigh",
-      "openrouter/anthropic/claude-fable-5:xhigh",
-      "openrouter/anthropic/claude-opus-4-8:xhigh",
+      "openrouter/anthropic/claude-fable-5:high",
+      "openrouter/anthropic/claude-opus-4-8:high",
       "openrouter/sakana/fugu-ultra:high",
       "openrouter/z-ai/glm-5.2:xhigh"
     ],

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

@@ -16,19 +16,19 @@ import { reviewDecisionSchema } from "./ralph-core.js";
 //   openrouter/z-ai mirror maps :xhigh exclusively, so it is always :xhigh.
 
 export const promptEngineerModelConfig = {
-    model: "anthropic/claude-fable-5:xhigh",
+    model: "anthropic/claude-fable-5:high",
     fallbackModels: [
       "openai-codex/gpt-5.5:xhigh",
       "github-copilot/gpt-5.5:xhigh",
       "openai/gpt-5.5:xhigh",
-      "github-copilot/claude-opus-4.8 (1m):xhigh",
-      "anthropic/claude-opus-4-8:xhigh",
+      "github-copilot/claude-opus-4.8 (1m):high",
+      "anthropic/claude-opus-4-8:high",
       "zai/glm-5.2:xhigh",
       "zai-coding-cn/glm-5.2:xhigh",
-      "openrouter/anthropic/claude-fable-5:xhigh",
+      "openrouter/anthropic/claude-fable-5:high",
       "openrouter/sakana/fugu-ultra:high",
       "openrouter/openai/gpt-5.5:xhigh",
-      "openrouter/anthropic/claude-opus-4-8:xhigh",
+      "openrouter/anthropic/claude-opus-4-8:high",
       "openrouter/z-ai/glm-5.2:xhigh"
     ],
     excludedTools: ["ask_user_question"],
@@ -53,38 +53,38 @@ export const researchModelConfig = {
 };
 
 export const orchestratorModelConfig = {
-    model: "anthropic/claude-fable-5:xhigh",
+    model: "anthropic/claude-fable-5:high",
     fallbackModels: [
       "openai-codex/gpt-5.5:xhigh",
       "github-copilot/gpt-5.5:xhigh",
       "openai/gpt-5.5:xhigh",
-      "github-copilot/claude-opus-4.8 (1m):xhigh",
-      "anthropic/claude-opus-4-8:xhigh",
+      "github-copilot/claude-opus-4.8 (1m):high",
+      "anthropic/claude-opus-4-8:high",
       "zai/glm-5.2:xhigh",
       "zai-coding-cn/glm-5.2:xhigh",
-      "openrouter/anthropic/claude-fable-5:xhigh",
+      "openrouter/anthropic/claude-fable-5:high",
       "openrouter/sakana/fugu-ultra:high",
       "openrouter/openai/gpt-5.5:xhigh",
-      "openrouter/anthropic/claude-opus-4-8:xhigh",
+      "openrouter/anthropic/claude-opus-4-8:high",
       "openrouter/z-ai/glm-5.2:xhigh"
     ],
     excludedTools: ["ask_user_question"],
 };
 
 export const reviewerAModelConfig = {
-    model: "anthropic/claude-fable-5:xhigh",
+    model: "anthropic/claude-fable-5:high",
     fallbackModels: [
       "openai-codex/gpt-5.5:xhigh",
       "github-copilot/gpt-5.5:xhigh",
       "openai/gpt-5.5:xhigh",
-      "github-copilot/claude-opus-4.8 (1m):xhigh",
-      "anthropic/claude-opus-4-8:xhigh",
+      "github-copilot/claude-opus-4.8 (1m):high",
+      "anthropic/claude-opus-4-8:high",
       "zai/glm-5.2:xhigh",
       "zai-coding-cn/glm-5.2:xhigh",
-      "openrouter/anthropic/claude-fable-5:xhigh",
+      "openrouter/anthropic/claude-fable-5:high",
       "openrouter/sakana/fugu-ultra:high",
       "openrouter/openai/gpt-5.5:xhigh",
-      "openrouter/anthropic/claude-opus-4-8:xhigh",
+      "openrouter/anthropic/claude-opus-4-8:high",
       "openrouter/z-ai/glm-5.2:xhigh"
     ],
     excludedTools: ["ask_user_question"],
@@ -96,15 +96,15 @@ export const reviewerBModelConfig = {
     fallbackModels: [
       "github-copilot/gpt-5.5:xhigh",
       "openai/gpt-5.5:xhigh",
-      "anthropic/claude-fable-5:xhigh",
-      "github-copilot/claude-opus-4.8 (1m):xhigh",
-      "anthropic/claude-opus-4-8:xhigh",
+      "anthropic/claude-fable-5:high",
+      "github-copilot/claude-opus-4.8 (1m):high",
+      "anthropic/claude-opus-4-8:high",
       "zai/glm-5.2:xhigh",
       "zai-coding-cn/glm-5.2:xhigh",
       "openrouter/openai/gpt-5.5:xhigh",
-      "openrouter/anthropic/claude-fable-5:xhigh",
+      "openrouter/anthropic/claude-fable-5:high",
       "openrouter/sakana/fugu-ultra:high",
-      "openrouter/anthropic/claude-opus-4-8:xhigh",
+      "openrouter/anthropic/claude-opus-4-8:high",
       "openrouter/z-ai/glm-5.2:xhigh"
     ],
     excludedTools: ["ask_user_question"],
@@ -118,14 +118,14 @@ export const reviewerCModelConfig = {
       "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):xhigh",
-      "anthropic/claude-opus-4-8:xhigh",
+      "anthropic/claude-fable-5:high",
+      "github-copilot/claude-opus-4.8 (1m):high",
+      "anthropic/claude-opus-4-8:high",
       "openrouter/sakana/fugu-ultra:high",
       "openrouter/z-ai/glm-5.2:xhigh",
       "openrouter/openai/gpt-5.5:xhigh",
-      "openrouter/anthropic/claude-fable-5:xhigh",
-      "openrouter/anthropic/claude-opus-4-8:xhigh"
+      "openrouter/anthropic/claude-fable-5:high",
+      "openrouter/anthropic/claude-opus-4-8:high"
     ],
     excludedTools: ["ask_user_question"],
     schema: reviewDecisionSchema,

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

@@ -0,0 +1,138 @@
+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;
+}): 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. This will be done in a future stage.",
+      ].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)],
+    [
+      "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"),
+    ],
+    [
+      "decision_rules",
+      ["Set stop_review_loop=true only when the patch is correct, reviewer_error is null/omitted, there are no blocking objective-aligned P0/P1/P2 findings, requirements_traceability is non-empty and every entry is proven, and no objective-relevant verification remains; beyond_objective and contradicts_objective findings are non-blocking and must not be folded into follow-up objectives without checking the literal contract. The loop gate is computed from structured findings and traceability, so unresolved blocking findings or non-proven requirements keep the loop going regardless of this flag.", "Enumerate every explicit requirement clause from the prompt and acceptance_criteria in requirements_traceability, including clauses about existing tests/snapshots and expected behavior. Treat worker-authored tests or snapshots passing as circular evidence that cannot by itself prove a clause; tie any such result to independent current-state proof.", "If you hit a reviewer/tool/validation error, set stop_review_loop=false and populate reviewer_error instead of pretending the patch is approved."].join("\n"),
+    ],
+  ]);
+}