@bastani/atomic 0.9.4 → 0.9.5-alpha.2

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

@@ -13,9 +13,10 @@ import { DEFAULT_MAX_TURNS } from "./goal-types.js";
 
 export default workflow({
   name: "goal",
-  description: "Goal Runner workflow with bounded LM turns, ledger artifacts, parallel reviewers, and reducer-gated completion.",
+  description: "Goal Runner workflow with bounded LM turns, immutable acceptance criteria, ledger artifacts, parallel reviewers, and reducer-gated completion. When launching follow-up goal runs from review findings, pass the ORIGINAL task text as acceptance_criteria so deltas cannot drift from the literal contract.",
   inputs: {
-    objective: Type.String({ description: "The objective for the Goal Runner workflow." }),
+    objective: Type.String({ description: "The objective or delta for this Goal Runner workflow run." }),
+    acceptance_criteria: Type.Optional(Type.String({ description: "Original immutable task contract this run must remain consistent with. Defaults to objective. Orchestrators launching follow-up runs from reviewer findings should pass the ORIGINAL task text here." })),
     max_turns: Type.Number({
       default: DEFAULT_MAX_TURNS,
       description: "Maximum worker/review turns before Goal Runner stops as needs_human.",
@@ -39,6 +40,7 @@ export default workflow({
     approved: Type.Optional(Type.Boolean({ description: "Whether the reducer reached complete." })),
     goal_id: Type.Optional(Type.String({ description: "Per-run goal identifier stored in the ledger." })),
     objective: Type.Optional(Type.String({ description: "Raw goal objective used by the run." })),
+    acceptance_criteria: Type.Optional(Type.String({ description: "Immutable acceptance criteria used by the run." })),
     ledger_path: Type.Optional(Type.String({ description: "OS-temp path to goal-ledger.json with receipts, reviewer decisions, blockers, and lifecycle events." })),
     turns_completed: Type.Optional(Type.Number({ description: "Worker/review turns completed." })),
     iterations_completed: Type.Optional(Type.Number({ description: "Worker/review turns completed, retained for status summaries." })),

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

@@ -37,12 +37,14 @@ export type GoalWorkflowReceipt = {
 };
 export type GoalWorkflowInputs = WorkflowInputValues & {
   readonly objective: string;
+  readonly acceptance_criteria?: string;
   readonly max_turns: number;
   readonly base_branch: string;
   readonly create_pr: boolean;
 };
 export type GoalWorkflowRunInputs = WorkflowInputValues & {
   readonly objective: string;
+  readonly acceptance_criteria?: string;
   readonly max_turns?: number;
   readonly base_branch?: string;
   readonly create_pr?: boolean;
@@ -53,6 +55,7 @@ export type GoalWorkflowOutputs = WorkflowOutputValues & {
   readonly approved?: boolean;
   readonly goal_id?: string;
   readonly objective?: string;
+  readonly acceptance_criteria?: string;
   readonly ledger_path?: string;
   readonly turns_completed?: number;
   readonly iterations_completed?: number;
@@ -70,6 +73,7 @@ export type GoalWorkflowDefinition = WorkflowDefinition<
 
 export type RalphWorkflowInputs = WorkflowInputValues & {
   readonly prompt: string;
+  readonly acceptance_criteria?: string;
   readonly max_loops: number;
   readonly base_branch: string;
   readonly git_worktree_dir: string;
@@ -77,6 +81,7 @@ export type RalphWorkflowInputs = WorkflowInputValues & {
 };
 export type RalphWorkflowRunInputs = WorkflowInputValues & {
   readonly prompt: string;
+  readonly acceptance_criteria?: string;
   readonly max_loops?: number;
   readonly base_branch?: string;
   readonly git_worktree_dir?: string;
@@ -89,6 +94,7 @@ export type RalphWorkflowOutputs = WorkflowOutputValues & {
   readonly research?: string;
   readonly research_path?: string;
   readonly implementation_notes_path?: string;
+  readonly qa_video_path?: string;
   readonly pr_report?: string;
   readonly approved?: boolean;
   readonly iterations_completed?: number;

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

@@ -86,6 +86,7 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
       "zai-coding-cn/glm-5.2:xhigh",
       "openrouter/anthropic/claude-fable-5:xhigh",
       "openrouter/anthropic/claude-opus-4-8:xhigh",
+      "openrouter/sakana/fugu-ultra:high",
       "openrouter/z-ai/glm-5.2:xhigh"
     ],
   };

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

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { Type } from "typebox";
 import type { WorkflowTaskResult } from "../src/shared/types.js";
-import { E2E_VERIFICATION_GUIDANCE } from "./shared-prompts.js";
+import { E2E_VERIFICATION_GUIDANCE, LITERAL_OBJECTIVE_CONTRACT } from "./shared-prompts.js";
 import type { ReviewDecision } from "./ralph-review-gate.js";
 
 export const DEFAULT_MAX_LOOPS = 10;
@@ -26,6 +26,12 @@ const reviewFindingSchema = Type.Object(
     title: Type.String(),
     body: Type.String(),
     confidence_score: Type.Number({ minimum: 0, maximum: 1 }),
+    objective_alignment: Type.Union([
+      Type.Literal("required_by_objective"),
+      Type.Literal("consistent_with_objective"),
+      Type.Literal("beyond_objective"),
+      Type.Literal("contradicts_objective"),
+    ]),
     priority: Type.Optional(
       Type.Union([Type.Integer({ minimum: 0, maximum: 3 }), Type.Null()]),
     ),
@@ -46,6 +52,20 @@ const reviewFindingSchema = Type.Object(
   { additionalProperties: false },
 );
 
+const requirementsTraceabilitySchema = Type.Object(
+  {
+    requirement: Type.String(),
+    status: Type.Union([
+      Type.Literal("proven"),
+      Type.Literal("contradicted"),
+      Type.Literal("missing"),
+      Type.Literal("unverified"),
+    ]),
+    evidence: Type.String(),
+  },
+  { additionalProperties: false },
+);
+
 const reviewerErrorSchema = Type.Object(
   {
     kind: Type.Union([
@@ -69,6 +89,7 @@ export const reviewDecisionSchema = Type.Object(
     ]),
     overall_explanation: Type.String(),
     overall_confidence_score: Type.Number({ minimum: 0, maximum: 1 }),
+    requirements_traceability: Type.Array(requirementsTraceabilitySchema),
     stop_review_loop: Type.Boolean(),
     reviewer_error: Type.Optional(
       Type.Union([Type.Null(), reviewerErrorSchema]),
@@ -170,6 +191,7 @@ export function renderQaE2eVideoGuidance(qaVideoPath: string): string {
     `Record that QA E2E pass as a reviewable video so the user can watch the feature working. After \`playwright-cli open\`, start recording with \`playwright-cli video-start ${qaVideoPath}\`, annotate the scenario with \`playwright-cli video-chapter\` / \`playwright-cli video-show-actions\`, exercise the full user scenario, then \`playwright-cli video-stop\`. Write the video to exactly this path and overwrite any prior recording so it always reflects the latest implemented state: ${qaVideoPath}`,
     `After recording, add the video to the implementation notes as a reference: include a \`## QA E2E Video\` entry with the absolute path ${qaVideoPath} and a one-line description of the proven scenario, so the user can review the proof when this stage finishes.`,
     "If the change has no user-visible UI scenario (pure refactor, docs, infra, or non-UI library code), do not fabricate a video; record in the implementation notes that no QA E2E video applies and why.",
+    "Assume credentials, auth, and browser environment access exist until a concrete attempt proves otherwise. Before declaring the QA E2E video impractical, check credential/auth state with non-destructive commands, attempt to launch the app/flow, and record the exact command(s) plus observed failure output.",
     "If `playwright-cli` or a browser runtime is unavailable, install it once per the skill (`npm install -g @playwright/cli@latest`, then `npx playwright install chromium` for a missing browser executable). If it still cannot run, record the smallest validation actually performed and note that the QA E2E video could not be produced — never claim a video exists when it does not.",
   ].join("\n");
 }
@@ -186,6 +208,7 @@ export function reviewerErrorDecision(error: string): ReviewDecision {
       "Reviewer execution failed, so the review gate cannot safely approve the current repository state.",
     overall_confidence_score: 0,
     stop_review_loop: false,
+    requirements_traceability: [],
     reviewer_error: {
       kind: "reviewer_failure",
       message: error,
@@ -258,6 +281,7 @@ export function forkContinuationOptions(
 
 export function renderResearchPromptRefinementPrompt(args: {
   readonly request: string;
+  readonly acceptanceCriteria: string;
   readonly workflowCwdContext: PromptSection;
   readonly latestReviewReportPath: string | undefined;
 }): string {
@@ -265,6 +289,9 @@ export function renderResearchPromptRefinementPrompt(args: {
   return [
     basePrompt,
     taggedPrompt([
+      ["objective", `Research the full requested task: ${args.request}`],
+      ["acceptance_criteria", args.acceptanceCriteria],
+      ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
       args.workflowCwdContext,
       [
         "review_findings",
@@ -272,7 +299,7 @@ export function renderResearchPromptRefinementPrompt(args: {
           ? "No prior review artifact is available."
           : [
               `Latest review round artifact: ${args.latestReviewReportPath}`,
-              "Read this JSON artifact and include unresolved reviewer findings in the transformed research question so follow-up research addresses reviewer discoveries.",
+              "Read this JSON artifact and include unresolved reviewer findings in the transformed research question only when they are consistent with the literal objective and acceptance criteria.",
             ].join("\n"),
       ],
       [
@@ -285,6 +312,8 @@ export function renderResearchPromptRefinementPrompt(args: {
 
 export function renderResearchPrompt(args: {
   readonly transformedResearchQuestion: string;
+  readonly prompt: string;
+  readonly acceptanceCriteria: string;
   readonly workflowCwdContext: PromptSection;
   readonly latestReviewReportPath: string | undefined;
   readonly researchPath: string;
@@ -293,6 +322,9 @@ export function renderResearchPrompt(args: {
   return [
     basePrompt,
     taggedPrompt([
+      ["objective", `Research implementation requirements for: ${args.prompt}`],
+      ["acceptance_criteria", args.acceptanceCriteria],
+      ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
       args.workflowCwdContext,
       [
         "review_findings",
@@ -318,6 +350,7 @@ export function renderResearchPrompt(args: {
 
 export function renderForkedOrchestratorPrompt(args: {
   readonly prompt: string;
+  readonly acceptanceCriteria: string;
   readonly workflowCwdContext: PromptSection;
   readonly researchPath: string;
   readonly implementationNotesPath: string;
@@ -331,6 +364,8 @@ export function renderForkedOrchestratorPrompt(args: {
       ].join("\n"),
     ],
     ["objective", `Implement the full requested task: ${args.prompt}`],
+    ["acceptance_criteria", args.acceptanceCriteria],
+    ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
     args.workflowCwdContext,
     [
       "research",
@@ -367,6 +402,7 @@ export function renderForkedOrchestratorPrompt(args: {
 
 export type RalphInputs = {
   readonly prompt?: string;
+  readonly acceptance_criteria?: string;
   readonly max_loops?: number;
   readonly base_branch?: string;
   readonly git_worktree_dir?: string;
@@ -375,6 +411,7 @@ export type RalphInputs = {
 
 export type RalphWorkflowOptions = {
   readonly prompt: string;
+  readonly acceptanceCriteria: string;
   readonly maxLoops: number;
   readonly comparisonBaseBranch: string;
   readonly workflowStartCwd: string;

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

@@ -1,41 +1,34 @@
 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;
+//   reviewer C leads with GLM-5.2 xhigh, with openrouter fugu-ultra retained
+//   mid-chain, to decorrelate review errors.
+// - 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:xhigh",
     fallbackModels: [
+      "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",
+      "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/openai/gpt-5.5:xhigh",
       "openrouter/anthropic/claude-fable-5:xhigh",
-      "openrouter/anthropic/claude-opus-4-8:high",
+      "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"
     ],
     excludedTools: ["ask_user_question"],
@@ -60,19 +53,20 @@ export const researchModelConfig = {
 };
 
 export const orchestratorModelConfig = {
-    model: "openai-codex/gpt-5.5:medium",
+    model: "anthropic/claude-fable-5:xhigh",
     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"
+      "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"
     ],
     excludedTools: ["ask_user_question"],
 };
@@ -83,13 +77,14 @@ export const reviewerAModelConfig = {
       "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",
+      "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:high",
+      "openrouter/anthropic/claude-opus-4-8:xhigh",
       "openrouter/z-ai/glm-5.2:xhigh"
     ],
     excludedTools: ["ask_user_question"],
@@ -102,13 +97,14 @@ export const reviewerBModelConfig = {
       "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",
+      "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/openai/gpt-5.5:xhigh",
       "openrouter/anthropic/claude-fable-5:xhigh",
-      "openrouter/anthropic/claude-opus-4-8:high",
+      "openrouter/sakana/fugu-ultra:high",
+      "openrouter/anthropic/claude-opus-4-8:xhigh",
       "openrouter/z-ai/glm-5.2:xhigh"
     ],
     excludedTools: ["ask_user_question"],
@@ -119,16 +115,17 @@ export const reviewerCModelConfig = {
     model: "zai/glm-5.2:xhigh",
     fallbackModels: [
       "zai-coding-cn/glm-5.2:xhigh",
-      "openrouter/z-ai/glm-5.2: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",
+      "github-copilot/claude-opus-4.8 (1m):xhigh",
+      "anthropic/claude-opus-4-8:xhigh",
+      "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:high"
+      "openrouter/anthropic/claude-opus-4-8:xhigh"
     ],
     excludedTools: ["ask_user_question"],
     schema: reviewDecisionSchema,

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

@@ -23,10 +23,17 @@
  * depend on the model correctly deriving that flag.
  */
 
+export type ObjectiveAlignment =
+  | "required_by_objective"
+  | "consistent_with_objective"
+  | "beyond_objective"
+  | "contradicts_objective";
+
 export type ReviewFinding = {
   readonly title: string;
   readonly body: string;
   readonly confidence_score: number;
+  readonly objective_alignment: ObjectiveAlignment;
   readonly priority?: number | null;
   readonly code_location: {
     readonly absolute_file_path: string;
@@ -46,12 +53,19 @@ export type ReviewerError = {
   readonly message: string;
   readonly attempted_recovery: string;
 };
+export type RequirementTraceability = {
+  readonly requirement: string;
+  readonly status: "proven" | "contradicted" | "missing" | "unverified";
+  readonly evidence: string;
+};
+
 
 export type ReviewDecision = {
   readonly findings: readonly ReviewFinding[];
   readonly overall_correctness: "patch is correct" | "patch is incorrect";
   readonly overall_explanation: string;
   readonly overall_confidence_score: number;
+  readonly requirements_traceability: readonly RequirementTraceability[];
   readonly stop_review_loop: boolean;
   readonly reviewer_error?: ReviewerError | null;
 };
@@ -69,6 +83,13 @@ export const MAX_BLOCKING_PRIORITY = 2;
  * approves.
  */
 export function isBlockingFinding(finding: ReviewFinding): boolean {
+  const alignment = finding.objective_alignment;
+  if (alignment === "beyond_objective" || alignment === "contradicts_objective") {
+    return false;
+  }
+  if (alignment !== "required_by_objective" && alignment !== "consistent_with_objective") {
+    return true;
+  }
   const priority = finding.priority;
   if (priority === undefined || priority === null) return true;
   return priority <= MAX_BLOCKING_PRIORITY;
@@ -76,14 +97,18 @@ export function isBlockingFinding(finding: ReviewFinding): boolean {
 
 /**
  * A single reviewer approves (would stop the loop) when it judged the patch
- * correct, surfaced no reviewer execution error, and filed no blocking
- * (P0/P1/P2) finding. P3 nice-to-haves and placeholder/dummy findings do not
- * block approval.
+ * correct, surfaced no reviewer execution error, filed no blocking (P0/P1/P2)
+ * finding, and supplied a non-empty requirement traceability map where every
+ * explicit requirement is proven. P3 nice-to-haves and placeholder/dummy
+ * findings do not block approval.
  */
 export function reviewDecisionApproved(decision: ReviewDecision): boolean {
+  const traceability = decision.requirements_traceability;
   return (
     decision.overall_correctness === "patch is correct" &&
     decision.reviewer_error == null &&
-    !decision.findings.some(isBlockingFinding)
+    !decision.findings.some(isBlockingFinding) &&
+    traceability.length > 0 &&
+    traceability.every((entry) => entry.status === "proven")
   );
 }

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

@@ -5,6 +5,7 @@ import { join, resolve } from "node:path";
 import type { WorkflowRunContext, WorkflowTaskResult } from "../src/shared/types.js";
 import {
   E2E_VERIFICATION_GUIDANCE,
+  LITERAL_OBJECTIVE_CONTRACT,
   WORKER_PREFLIGHT_CONTRACT,
   renderE2eQaVideoReviewGuidance,
 } from "./shared-prompts.js";
@@ -43,7 +44,7 @@ export async function runRalphWorkflow(
   ctx: WorkflowRunContext<RalphInputs>,
   options: RalphWorkflowOptions,
 ): Promise<RalphWorkflowResult> {
-  const { prompt, maxLoops, comparisonBaseBranch, workflowStartCwd, createPr } = options;
+  const { prompt, acceptanceCriteria, maxLoops, comparisonBaseBranch, workflowStartCwd, createPr } = options;
   let latestReviewReportPath: string | undefined;
   let finalPlan = "";
   let finalPlanPath = "";
@@ -68,6 +69,7 @@ export async function runRalphWorkflow(
     const researchPromptRefinement = await ctx.task(`research-prompt-refinement-${iteration}`, {
       prompt: renderResearchPromptRefinementPrompt({
         request: workflowPrompt,
+        acceptanceCriteria,
         workflowCwdContext,
         latestReviewReportPath,
       }),
@@ -81,6 +83,8 @@ export async function runRalphWorkflow(
     const research = await ctx.task(`research-${iteration}`, {
       prompt: renderResearchPrompt({
         transformedResearchQuestion: researchPromptRefinement.text,
+        prompt: workflowPrompt,
+        acceptanceCriteria,
         workflowCwdContext,
         latestReviewReportPath,
         researchPath: workflowResearchPath,
@@ -108,6 +112,8 @@ export async function runRalphWorkflow(
           "objective",
           `Implement the full requested task: ${workflowPrompt}`,
         ],
+        ["acceptance_criteria", acceptanceCriteria],
+        ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
         workflowCwdContext,
         [
           "research",
@@ -195,6 +201,7 @@ export async function runRalphWorkflow(
       ])
       : renderForkedOrchestratorPrompt({
           prompt: workflowPrompt,
+          acceptanceCriteria,
           workflowCwdContext,
           researchPath,
           implementationNotesPath,
@@ -220,6 +227,8 @@ export async function runRalphWorkflow(
         ].join("\n"),
       ],
       ["objective", `Review the current code delta for the task: ${workflowPrompt}`],
+      ["acceptance_criteria", acceptanceCriteria],
+      ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
       workflowCwdContext,
       [
         "comparison_baseline",
@@ -279,6 +288,7 @@ export async function runRalphWorkflow(
         [
           "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.",
@@ -322,10 +332,7 @@ export async function runRalphWorkflow(
       ],
       [
         "decision_rules",
-        [
-          "Set stop_review_loop=true when the patch is correct, reviewer_error is null/omitted, and there are no blocking (P0/P1/P2) findings; remaining P3 nice-to-haves do not block approval. The loop gate is computed from finding priorities, so an unresolved P0/P1/P2 keeps the loop going regardless of this flag.",
-          "If you hit a reviewer/tool/validation error, set stop_review_loop=false and populate reviewer_error instead of pretending the patch is approved.",
-        ].join("\n"),
+        ["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"),
       ],
     ]);
     let reviews: WorkflowTaskResult[];

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

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

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

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

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

@@ -14,7 +14,9 @@ export const E2E_VERIFICATION_GUIDANCE = [
   "Verify correctness end-to-end whenever practical for user-visible behavior; do not rely only on code inspection, unit tests, or stage summaries when an executable user scenario can prove the outcome.",
   "For web or frontend flows — including frontend changes whose correctness depends on backend/API behavior — use the playwright-cli skill, or delegate to a subagent with `skill: \"playwright-cli\"`, to drive the application like a user and capture snapshot, screenshot, DOM, or network evidence when that proves the objective.",
   "For TUI or terminal-app flows, use the tmux skill, or delegate to a subagent with `skill: \"tmux\"`, to launch the app in an isolated tmux session, send keys, capture pane output, and simulate the scenario end to end.",
-  "If end-to-end verification is not practical in this checkout, record what was attempted, the smallest missing prerequisite, and the narrower validation that was run instead; do not claim end-to-end proof when it was not performed.",
+  "Assume credentials, auth, and environment access for playwright-cli/tmux E2E testing exist until a concrete attempt proves otherwise; never skip E2E based only on an assumed missing prerequisite.",
+  "Before declaring E2E impractical, do cheap non-destructive checks first (existing sessions, config files, env vars, CLI auth status), then actually attempt to launch the app or flow.",
+  "If end-to-end verification is not practical in this checkout, record the exact command(s) attempted, observed failure output, smallest missing prerequisite, and narrower validation run instead; an unattempted assumption is never valid grounds to skip.",
 ].join("\n");
 
 export function renderE2eQaVideoReviewGuidance(
@@ -29,5 +31,17 @@ export function renderE2eQaVideoReviewGuidance(
     "Use available video/file tooling such as `fetch_content` on the local video path with a prompt focused on whether the recording proves the required user scenario, or inspect representative frames/metadata when full video analysis is unavailable.",
     "Check that the video reflects the current repository/application state, exercises the objective-relevant user path, shows the expected final behavior, and does not visibly hide errors, stale UI, broken loading states, or skipped steps.",
     "For UI-applicable or full-stack changes, treat a missing, stale, unreadable, or inconclusive QA video as missing E2E evidence unless the receipt or implementation notes justify why no video applies and provide adequate alternate end-to-end proof.",
+    "Treat skipped E2E due to assumed-missing credentials, auth, or environment access as missing evidence unless the worker actually checked credential/auth state, attempted the launch/flow, and reported exact commands plus observed failure output.",
   ].join("\n");
 }
+
+
+export const LITERAL_OBJECTIVE_CONTRACT = [
+  "Literal objective contract:",
+  "- The objective and acceptance criteria are the sole and LITERAL source of truth for required behavior.",
+  "- Acceptance criteria are the immutable task contract; the run objective is a delta that must not contradict them.",
+  "- If the objective and acceptance criteria conflict, do not implement the contradiction. Surface it as a blocker or reviewer finding instead.",
+  "- When external knowledge (language specs, upstream issues, in-repo comments, general best practice, or prior reviewer speculation) conflicts with explicit objective wording, the objective/acceptance criteria win.",
+  "- Never silently resolve such a conflict in favor of external knowledge. Surface the conflict clearly.",
+  "- Do not add behaviors, restrictions, error conditions, or follow-up requirements beyond what the objective/acceptance criteria require.",
+].join("\n");

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.9.4",
+  "version": "0.9.5-alpha.2",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [

package/dist/builtin/workflows/src/extension/workflow-schema.ts

@@ -49,7 +49,7 @@ const StageSessionOptionProperties = {
   agentDir: Type.Optional(Type.String()),
   authStorage: Type.Optional(SdkSessionOptionSchema("authStorage")),
   modelRegistry: Type.Optional(SdkSessionOptionSchema("modelRegistry")),
-  model: Type.Optional(Type.Unsafe<WorkflowModelValue>({ description: "Primary model id or SDK model object. String ids may include a reasoning suffix, e.g. openai/gpt-5:high; valid levels: off|minimal|low|medium|high|xhigh. A parenthesized context-window token may precede or follow the suffix, e.g. github-copilot/claude-opus-4.8 (1m):high or github-copilot/claude-opus-4.8:high (1m). Use (long) for a generic long-context marker, or a rounded size matching the model's long tier (e.g. (1m) or (1.1m)); both select the model's advertised long tier." })),
+  model: Type.Optional(Type.Unsafe<WorkflowModelValue>({ description: "Primary model id or SDK model object. String ids may include a reasoning suffix, e.g. openai/gpt-5:high; valid levels: off|minimal|low|medium|high|xhigh. A parenthesized context-window token may precede or follow the suffix, e.g. github-copilot/claude-opus-4.8 (1m):xhigh or github-copilot/claude-opus-4.8:xhigh (1m). Use (long) for a generic long-context marker, or a rounded size matching the model's long tier (e.g. (1m) or (1.1m)); both select the model's advertised long tier." })),
   contextWindow: Type.Optional(Type.Number({ description: "Context-window token budget for the stage session (e.g. 1000000). Non-strict by default: an unsupported value keeps the model's default window. Prefer the per-model `(1m)` token in a model/fallbackModels entry when only specific models should use a larger window." })),
   contextWindowStrict: Type.Optional(Type.Boolean({ description: "Treat an unsupported contextWindow as an error instead of falling back to the model's default window." })),
   thinkingLevel: Type.Optional(SdkSessionOptionSchema("thinkingLevel")),