@bastani/atomic 0.9.4-alpha.9 → 0.9.5-alpha.1

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

@@ -9,6 +9,23 @@ export function formatReviewReport(reviews: readonly ReviewRecord[]): string {
       `Decision: ${review.decision}`,
       `Artifact: ${review.artifact_path}`,
       `Verification remaining: ${review.verification_remaining}`,
+      "Finding alignment warning: beyond_objective and contradicts_objective findings are non-blocking and must not be folded into follow-up objectives without checking them against the acceptance criteria.",
+      review.findings.length === 0
+        ? "Findings: none"
+        : [
+            "Findings:",
+            ...review.findings.map((finding) =>
+              `- ${finding.objective_alignment}: ${finding.title}`
+            ),
+          ].join("\n"),
+      review.requirements_traceability.length === 0
+        ? "Requirements traceability: none"
+        : [
+            "Requirements traceability:",
+            ...review.requirements_traceability.map((entry) =>
+              `- ${entry.status}: ${entry.requirement} — ${entry.evidence}`
+            ),
+          ].join("\n"),
     ].join("\n"))
     .join("\n\n---\n\n");
 }
@@ -35,6 +52,9 @@ export function renderFinalReport(
     "## Objective",
     ledger.objective,
     "",
+    "## Acceptance criteria",
+    ledger.acceptance_criteria,
+    "",
     "## Final status",
     ledger.status,
     "",
@@ -47,6 +67,9 @@ export function renderFinalReport(
     "## Final decision",
     lastDecision?.reason ?? "No reducer decision was recorded.",
     "",
+    "## Objective-alignment warning",
+    "Review findings classified beyond_objective or contradicts_objective are non-blocking and must not be promoted into follow-up objectives without checking them against the acceptance criteria.",
+    "",
     "## Remaining work if incomplete",
     ledger.status === "complete" ? "none" : remainingWork,
   ].join("\n");

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

@@ -5,14 +5,32 @@ export function reviewDecisionFromResult(result: WorkflowTaskResult): ReviewDeci
   return result.structured as ReviewDecision | undefined;
 }
 
+const NON_BLOCKING_ALIGNMENTS = new Set([
+  "beyond_objective",
+  "contradicts_objective",
+]);
+
+function findingBlocksApproval(finding: ReviewDecision["findings"][number]): boolean {
+  const alignment = finding.objective_alignment;
+  if (NON_BLOCKING_ALIGNMENTS.has(alignment)) return false;
+  if (alignment !== "required_by_objective" && alignment !== "consistent_with_objective") {
+    return true;
+  }
+  return finding.priority !== 3;
+}
+
+function traceabilityApproves(decision: ReviewDecision): boolean {
+  return decision.requirements_traceability.length > 0 &&
+    decision.requirements_traceability.every((entry) => entry.status === "proven");
+}
+
 export function reviewApproved(decision: ReviewDecision): boolean {
-  const hasBlockingFindings = decision.findings.some(
-    (finding) => finding.priority !== 3,
-  );
+  const hasBlockingFindings = decision.findings.some(findingBlocksApproval);
   return (
     decision.stop_review_loop === true &&
     decision.overall_correctness === "patch is correct" &&
     decision.goal_oracle_satisfied === true &&
+    traceabilityApproves(decision) &&
     !hasBlockingFindings &&
     decision.reviewer_error == null
   );
@@ -26,6 +44,7 @@ export function reviewerErrorDecision(message: string): ReviewDecision {
       "Reviewer execution failed, so the review gate cannot safely approve the current repository state.",
     overall_confidence_score: 0,
     goal_oracle_satisfied: false,
+    requirements_traceability: [],
     receipt_assessment:
       "No reviewer receipt could be produced because reviewer execution failed.",
     verification_remaining: "Recover reviewer execution and re-run oracle validation.",
@@ -61,8 +80,14 @@ export function reviewDecisionToRecord(args: {
   const blocker = blockerFromReviewDecision(args.decision);
   const approved = reviewApproved(args.decision);
   const verificationGap = args.decision.verification_remaining.trim();
+  const traceabilityGaps = args.decision.requirements_traceability
+    .filter((entry) => entry.status !== "proven")
+    .map((entry) => `${entry.status}: ${entry.requirement} — ${entry.evidence}`);
   const gaps = [
-    ...args.decision.findings.map((finding) => `${finding.title}: ${finding.body}`),
+    ...args.decision.findings.map((finding) =>
+      `[${finding.objective_alignment}] ${finding.title}: ${finding.body}`
+    ),
+    ...traceabilityGaps,
     ...(approved || verificationGap.length === 0 ? [] : [verificationGap]),
     ...(args.decision.reviewer_error == null
       ? []

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

@@ -85,12 +85,13 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
       throw new Error("goal requires an objective input.");
     }
     const objective = rawObjective;
+    const acceptanceCriteria = inputs.acceptance_criteria?.trim() || objective;
 
     const maxTurns = positiveInteger(inputs.max_turns, DEFAULT_MAX_TURNS);
     const reviewQuorum = DEFAULT_REVIEW_QUORUM;
     const blockerThreshold = Math.min(DEFAULT_BLOCKER_THRESHOLD, maxTurns);
     const comparisonBaseBranch = normalizeBranchInput(inputs.base_branch, "origin/main");
-    const { ledger, ledgerPath, artifactDir } = await createGoalLedger(objective);
+    const { ledger, ledgerPath, artifactDir } = await createGoalLedger(objective, acceptanceCriteria);
 
     // Chains curated from Atomic's agentic-coding benchmark (see
     // ralph-models.ts for the frontier data and drop rationale).
@@ -415,6 +416,7 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
       approved: ledger.status === "complete",
       goal_id: ledger.goal_id,
       objective: ledger.objective,
+      acceptance_criteria: ledger.acceptance_criteria,
       ledger_path: ledgerPath,
       turns_completed: ledger.turns,
       iterations_completed: ledger.turns,

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

@@ -5,6 +5,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()]),
     ),
@@ -25,6 +31,21 @@ 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([
@@ -49,6 +70,7 @@ export const reviewDecisionSchema = Type.Object(
     overall_explanation: Type.String(),
     overall_confidence_score: Type.Number({ minimum: 0, maximum: 1 }),
     goal_oracle_satisfied: Type.Boolean(),
+    requirements_traceability: Type.Array(requirementsTraceabilitySchema),
     receipt_assessment: Type.String(),
     verification_remaining: Type.String(),
     stop_review_loop: Type.Boolean(),

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

@@ -14,10 +14,23 @@ export type WorkReceipt = {
   readonly summary: string;
 };
 
+export type ObjectiveAlignment =
+  | "required_by_objective"
+  | "consistent_with_objective"
+  | "beyond_objective"
+  | "contradicts_objective";
+
+export type RequirementTraceability = {
+  readonly requirement: string;
+  readonly status: "proven" | "contradicted" | "missing" | "unverified";
+  readonly evidence: string;
+};
+
 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;
@@ -44,6 +57,7 @@ export type ReviewDecision = {
   readonly overall_explanation: string;
   readonly overall_confidence_score: number;
   readonly goal_oracle_satisfied: boolean;
+  readonly requirements_traceability: readonly RequirementTraceability[];
   readonly receipt_assessment: string;
   readonly verification_remaining: string;
   readonly stop_review_loop: boolean;
@@ -93,6 +107,7 @@ export type GoalLifecycleEvent = {
 export type GoalLedger = {
   readonly goal_id: string;
   readonly objective: string;
+  readonly acceptance_criteria: string;
   status: GoalStatus;
   turns: number;
   readonly created_at: string;
@@ -112,6 +127,7 @@ export type ReducerOutcome = {
 
 export type GoalWorkflowInputs = {
   readonly objective: string;
+  readonly acceptance_criteria?: string;
   readonly max_turns: number;
   readonly base_branch: string;
   readonly create_pr: boolean;
@@ -123,6 +139,7 @@ export type GoalWorkflowOutputs = {
   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;

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

@@ -11,6 +11,7 @@ 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;
@@ -18,6 +19,7 @@ export type GoalWorkflowInputs = WorkflowInputValues & {
 
 export type GoalWorkflowRunInputs = WorkflowInputValues & {
   readonly objective: string;
+  readonly acceptance_criteria?: string;
   readonly max_turns?: number;
   readonly base_branch?: string;
   readonly create_pr?: boolean;
@@ -29,6 +31,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;

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/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-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,